1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/string/public/nsXPCOMStrings.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,763 @@
1.4 +/* vim:set ts=2 sw=2 et cindent: */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef nsXPCOMStrings_h__
1.10 +#define nsXPCOMStrings_h__
1.11 +
1.12 +#include <string.h>
1.13 +#include "nscore.h"
1.14 +#include <limits>
1.15 +
1.16 +/**
1.17 + * nsXPCOMStrings.h
1.18 + *
1.19 + * This file describes a minimal API for working with XPCOM's abstract
1.20 + * string classes. It divorces the consumer from having any run-time
1.21 + * dependency on the implementation details of the abstract string types.
1.22 + */
1.23 +
1.24 +#include "nscore.h"
1.25 +
1.26 +/* The base string types */
1.27 +class nsAString;
1.28 +class nsACString;
1.29 +
1.30 +/* ------------------------------------------------------------------------- */
1.31 +
1.32 +/**
1.33 + * nsStringContainer
1.34 + *
1.35 + * This is an opaque data type that is large enough to hold the canonical
1.36 + * implementation of nsAString. The binary structure of this class is an
1.37 + * implementation detail.
1.38 + *
1.39 + * The string data stored in a string container is always single fragment
1.40 + * and may be null-terminated depending on how it is initialized.
1.41 + *
1.42 + * Typically, string containers are allocated on the stack for temporary
1.43 + * use. However, they can also be malloc'd if necessary. In either case,
1.44 + * a string container is not useful until it has been initialized with a
1.45 + * call to NS_StringContainerInit. The following example shows how to use
1.46 + * a string container to call a function that takes a |nsAString &| out-param.
1.47 + *
1.48 + * NS_METHOD GetBlah(nsAString &aBlah);
1.49 + *
1.50 + * nsresult MyCode()
1.51 + * {
1.52 + * nsresult rv;
1.53 + *
1.54 + * nsStringContainer sc;
1.55 + * rv = NS_StringContainerInit(sc);
1.56 + * if (NS_FAILED(rv))
1.57 + * return rv;
1.58 + *
1.59 + * rv = GetBlah(sc);
1.60 + * if (NS_SUCCEEDED(rv))
1.61 + * {
1.62 + * const char16_t *data;
1.63 + * NS_StringGetData(sc, &data);
1.64 + * //
1.65 + * // |data| now points to the result of the GetBlah function
1.66 + * //
1.67 + * }
1.68 + *
1.69 + * NS_StringContainerFinish(sc);
1.70 + * return rv;
1.71 + * }
1.72 + *
1.73 + * The following example show how to use a string container to pass a string
1.74 + * parameter to a function taking a |const nsAString &| in-param.
1.75 + *
1.76 + * NS_METHOD SetBlah(const nsAString &aBlah);
1.77 + *
1.78 + * nsresult MyCode()
1.79 + * {
1.80 + * nsresult rv;
1.81 + *
1.82 + * nsStringContainer sc;
1.83 + * rv = NS_StringContainerInit(sc);
1.84 + * if (NS_FAILED(rv))
1.85 + * return rv;
1.86 + *
1.87 + * const char16_t kData[] = {'x','y','z','\0'};
1.88 + * rv = NS_StringSetData(sc, kData, sizeof(kData)/2 - 1);
1.89 + * if (NS_SUCCEEDED(rv))
1.90 + * rv = SetBlah(sc);
1.91 + *
1.92 + * NS_StringContainerFinish(sc);
1.93 + * return rv;
1.94 + * }
1.95 + */
1.96 +class nsStringContainer;
1.97 +
1.98 +
1.99 +/**
1.100 + * This struct is never used directly. It is designed to have the same
1.101 + * size as nsString. It can be stack and heap allocated and the internal
1.102 + * functions cast it to nsString.
1.103 + * While this practice is a strict aliasing violation, it doesn't seem to
1.104 + * cause problems since the the struct is only accessed via the casts to
1.105 + * nsString.
1.106 + * We use protected instead of private to avoid compiler warnings about
1.107 + * the members being unused.
1.108 + */
1.109 +struct nsStringContainer_base
1.110 +{
1.111 +protected:
1.112 + void *d1;
1.113 + uint32_t d2;
1.114 + uint32_t d3;
1.115 +};
1.116 +
1.117 +/**
1.118 + * Flags that may be OR'd together to pass to NS_StringContainerInit2:
1.119 + */
1.120 +enum {
1.121 + /* Data passed into NS_StringContainerInit2 is not copied; instead, the
1.122 + * string references the passed in data pointer directly. The caller must
1.123 + * ensure that the data is valid for the lifetime of the string container.
1.124 + * This flag should not be combined with NS_STRING_CONTAINER_INIT_ADOPT. */
1.125 + NS_STRING_CONTAINER_INIT_DEPEND = (1 << 1),
1.126 +
1.127 + /* Data passed into NS_StringContainerInit2 is not copied; instead, the
1.128 + * string takes ownership over the data pointer. The caller must have
1.129 + * allocated the data array using the XPCOM memory allocator (nsMemory).
1.130 + * This flag should not be combined with NS_STRING_CONTAINER_INIT_DEPEND. */
1.131 + NS_STRING_CONTAINER_INIT_ADOPT = (1 << 2),
1.132 +
1.133 + /* Data passed into NS_StringContainerInit2 is a substring that is not
1.134 + * null-terminated. */
1.135 + NS_STRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
1.136 +};
1.137 +
1.138 +/**
1.139 + * NS_StringContainerInit
1.140 + *
1.141 + * @param aContainer string container reference
1.142 + * @return NS_OK if string container successfully initialized
1.143 + *
1.144 + * This function may allocate additional memory for aContainer. When
1.145 + * aContainer is no longer needed, NS_StringContainerFinish should be called.
1.146 + */
1.147 +XPCOM_API(nsresult)
1.148 +NS_StringContainerInit(nsStringContainer &aContainer);
1.149 +
1.150 +/**
1.151 + * NS_StringContainerInit2
1.152 + *
1.153 + * @param aContainer string container reference
1.154 + * @param aData character buffer (may be null)
1.155 + * @param aDataLength number of characters stored at aData (may pass
1.156 + * UINT32_MAX if aData is null-terminated)
1.157 + * @param aFlags flags affecting how the string container is
1.158 + * initialized. this parameter is ignored when aData
1.159 + * is null. otherwise, if this parameter is 0, then
1.160 + * aData is copied into the string.
1.161 + *
1.162 + * This function resembles NS_StringContainerInit but provides further
1.163 + * options that permit more efficient memory usage. When aContainer is
1.164 + * no longer needed, NS_StringContainerFinish should be called.
1.165 + *
1.166 + * NOTE: NS_StringContainerInit2(container, nullptr, 0, 0) is equivalent to
1.167 + * NS_StringContainerInit(container).
1.168 + */
1.169 +XPCOM_API(nsresult)
1.170 +NS_StringContainerInit2
1.171 + (nsStringContainer &aContainer, const char16_t *aData = nullptr,
1.172 + uint32_t aDataLength = UINT32_MAX, uint32_t aFlags = 0);
1.173 +
1.174 +/**
1.175 + * NS_StringContainerFinish
1.176 + *
1.177 + * @param aContainer string container reference
1.178 + *
1.179 + * This function frees any memory owned by aContainer.
1.180 + */
1.181 +XPCOM_API(void)
1.182 +NS_StringContainerFinish(nsStringContainer &aContainer);
1.183 +
1.184 +/* ------------------------------------------------------------------------- */
1.185 +
1.186 +/**
1.187 + * NS_StringGetData
1.188 + *
1.189 + * This function returns a const character pointer to the string's internal
1.190 + * buffer, the length of the string, and a boolean value indicating whether
1.191 + * or not the buffer is null-terminated.
1.192 + *
1.193 + * @param aStr abstract string reference
1.194 + * @param aData out param that will hold the address of aStr's
1.195 + * internal buffer
1.196 + * @param aTerminated if non-null, this out param will be set to indicate
1.197 + * whether or not aStr's internal buffer is null-
1.198 + * terminated
1.199 + * @return length of aStr's internal buffer
1.200 + */
1.201 +XPCOM_API(uint32_t)
1.202 +NS_StringGetData
1.203 + (const nsAString &aStr, const char16_t **aData,
1.204 + bool *aTerminated = nullptr);
1.205 +
1.206 +/**
1.207 + * NS_StringGetMutableData
1.208 + *
1.209 + * This function provides mutable access to a string's internal buffer. It
1.210 + * returns a pointer to an array of characters that may be modified. The
1.211 + * returned pointer remains valid until the string object is passed to some
1.212 + * other string function.
1.213 + *
1.214 + * Optionally, this function may be used to resize the string's internal
1.215 + * buffer. The aDataLength parameter specifies the requested length of the
1.216 + * string's internal buffer. By passing some value other than UINT32_MAX,
1.217 + * the caller can request that the buffer be resized to the specified number of
1.218 + * characters before returning. The caller is not responsible for writing a
1.219 + * null-terminator.
1.220 + *
1.221 + * @param aStr abstract string reference
1.222 + * @param aDataLength number of characters to resize the string's internal
1.223 + * buffer to or UINT32_MAX if no resizing is needed
1.224 + * @param aData out param that upon return holds the address of aStr's
1.225 + * internal buffer or null if the function failed
1.226 + * @return number of characters or zero if the function failed
1.227 + *
1.228 + * This function does not necessarily null-terminate aStr after resizing its
1.229 + * internal buffer. The behavior depends on the implementation of the abstract
1.230 + * string, aStr. If aStr is a reference to a nsStringContainer, then its data
1.231 + * will be null-terminated by this function.
1.232 + */
1.233 +XPCOM_API(uint32_t)
1.234 +NS_StringGetMutableData
1.235 + (nsAString &aStr, uint32_t aDataLength, char16_t **aData);
1.236 +
1.237 +/**
1.238 + * NS_StringCloneData
1.239 + *
1.240 + * This function returns a null-terminated copy of the string's
1.241 + * internal buffer.
1.242 + *
1.243 + * @param aStr abstract string reference
1.244 + * @return null-terminated copy of the string's internal buffer
1.245 + * (it must be free'd using using nsMemory::Free)
1.246 + */
1.247 +XPCOM_API(char16_t *)
1.248 +NS_StringCloneData
1.249 + (const nsAString &aStr);
1.250 +
1.251 +/**
1.252 + * NS_StringSetData
1.253 + *
1.254 + * This function copies aData into aStr.
1.255 + *
1.256 + * @param aStr abstract string reference
1.257 + * @param aData character buffer
1.258 + * @param aDataLength number of characters to copy from source string (pass
1.259 + * UINT32_MAX to copy until end of aData, designated by
1.260 + * a null character)
1.261 + * @return NS_OK if function succeeded
1.262 + *
1.263 + * This function does not necessarily null-terminate aStr after copying data
1.264 + * from aData. The behavior depends on the implementation of the abstract
1.265 + * string, aStr. If aStr is a reference to a nsStringContainer, then its data
1.266 + * will be null-terminated by this function.
1.267 + */
1.268 +XPCOM_API(nsresult)
1.269 +NS_StringSetData
1.270 + (nsAString &aStr, const char16_t *aData,
1.271 + uint32_t aDataLength = UINT32_MAX);
1.272 +
1.273 +/**
1.274 + * NS_StringSetDataRange
1.275 + *
1.276 + * This function copies aData into a section of aStr. As a result it can be
1.277 + * used to insert new characters into the string.
1.278 + *
1.279 + * @param aStr abstract string reference
1.280 + * @param aCutOffset starting index where the string's existing data
1.281 + * is to be overwritten (pass UINT32_MAX to cause
1.282 + * aData to be appended to the end of aStr, in which
1.283 + * case the value of aCutLength is ignored).
1.284 + * @param aCutLength number of characters to overwrite starting at
1.285 + * aCutOffset (pass UINT32_MAX to overwrite until the
1.286 + * end of aStr).
1.287 + * @param aData character buffer (pass null to cause this function
1.288 + * to simply remove the "cut" range)
1.289 + * @param aDataLength number of characters to copy from source string (pass
1.290 + * UINT32_MAX to copy until end of aData, designated by
1.291 + * a null character)
1.292 + * @return NS_OK if function succeeded
1.293 + *
1.294 + * This function does not necessarily null-terminate aStr after copying data
1.295 + * from aData. The behavior depends on the implementation of the abstract
1.296 + * string, aStr. If aStr is a reference to a nsStringContainer, then its data
1.297 + * will be null-terminated by this function.
1.298 + */
1.299 +XPCOM_API(nsresult)
1.300 +NS_StringSetDataRange
1.301 + (nsAString &aStr, uint32_t aCutOffset, uint32_t aCutLength,
1.302 + const char16_t *aData, uint32_t aDataLength = UINT32_MAX);
1.303 +
1.304 +/**
1.305 + * NS_StringCopy
1.306 + *
1.307 + * This function makes aDestStr have the same value as aSrcStr. It is
1.308 + * provided as an optimization.
1.309 + *
1.310 + * @param aDestStr abstract string reference to be modified
1.311 + * @param aSrcStr abstract string reference containing source string
1.312 + * @return NS_OK if function succeeded
1.313 + *
1.314 + * This function does not necessarily null-terminate aDestStr after copying
1.315 + * data from aSrcStr. The behavior depends on the implementation of the
1.316 + * abstract string, aDestStr. If aDestStr is a reference to a
1.317 + * nsStringContainer, then its data will be null-terminated by this function.
1.318 + */
1.319 +XPCOM_API(nsresult)
1.320 +NS_StringCopy
1.321 + (nsAString &aDestStr, const nsAString &aSrcStr);
1.322 +
1.323 +/**
1.324 + * NS_StringAppendData
1.325 + *
1.326 + * This function appends data to the existing value of aStr.
1.327 + *
1.328 + * @param aStr abstract string reference to be modified
1.329 + * @param aData character buffer
1.330 + * @param aDataLength number of characters to append (pass UINT32_MAX to
1.331 + * append until a null-character is encountered)
1.332 + * @return NS_OK if function succeeded
1.333 + *
1.334 + * This function does not necessarily null-terminate aStr upon completion.
1.335 + * The behavior depends on the implementation of the abstract string, aStr.
1.336 + * If aStr is a reference to a nsStringContainer, then its data will be null-
1.337 + * terminated by this function.
1.338 + */
1.339 +inline NS_HIDDEN_(nsresult)
1.340 +NS_StringAppendData(nsAString &aStr, const char16_t *aData,
1.341 + uint32_t aDataLength = UINT32_MAX)
1.342 +{
1.343 + return NS_StringSetDataRange(aStr, UINT32_MAX, 0, aData, aDataLength);
1.344 +}
1.345 +
1.346 +/**
1.347 + * NS_StringInsertData
1.348 + *
1.349 + * This function inserts data into the existing value of aStr at the specified
1.350 + * offset.
1.351 + *
1.352 + * @param aStr abstract string reference to be modified
1.353 + * @param aOffset specifies where in the string to insert aData
1.354 + * @param aData character buffer
1.355 + * @param aDataLength number of characters to append (pass UINT32_MAX to
1.356 + * append until a null-character is encountered)
1.357 + * @return NS_OK if function succeeded
1.358 + *
1.359 + * This function does not necessarily null-terminate aStr upon completion.
1.360 + * The behavior depends on the implementation of the abstract string, aStr.
1.361 + * If aStr is a reference to a nsStringContainer, then its data will be null-
1.362 + * terminated by this function.
1.363 + */
1.364 +inline NS_HIDDEN_(nsresult)
1.365 +NS_StringInsertData(nsAString &aStr, uint32_t aOffset, const char16_t *aData,
1.366 + uint32_t aDataLength = UINT32_MAX)
1.367 +{
1.368 + return NS_StringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
1.369 +}
1.370 +
1.371 +/**
1.372 + * NS_StringCutData
1.373 + *
1.374 + * This function shortens the existing value of aStr, by removing characters
1.375 + * at the specified offset.
1.376 + *
1.377 + * @param aStr abstract string reference to be modified
1.378 + * @param aCutOffset specifies where in the string to insert aData
1.379 + * @param aCutLength number of characters to remove
1.380 + * @return NS_OK if function succeeded
1.381 + */
1.382 +inline NS_HIDDEN_(nsresult)
1.383 +NS_StringCutData(nsAString &aStr, uint32_t aCutOffset, uint32_t aCutLength)
1.384 +{
1.385 + return NS_StringSetDataRange(aStr, aCutOffset, aCutLength, nullptr, 0);
1.386 +}
1.387 +
1.388 +/**
1.389 + * NS_StringSetIsVoid
1.390 + *
1.391 + * This function marks a string as being a "void string". Any data in the
1.392 + * string will be lost.
1.393 + */
1.394 +XPCOM_API(void)
1.395 +NS_StringSetIsVoid(nsAString& aStr, const bool aIsVoid);
1.396 +
1.397 +/**
1.398 + * NS_StringGetIsVoid
1.399 + *
1.400 + * This function provides a way to test if a string is a "void string", as
1.401 + * marked by NS_StringSetIsVoid.
1.402 + */
1.403 +XPCOM_API(bool)
1.404 +NS_StringGetIsVoid(const nsAString& aStr);
1.405 +
1.406 +/* ------------------------------------------------------------------------- */
1.407 +
1.408 +/**
1.409 + * nsCStringContainer
1.410 + *
1.411 + * This is an opaque data type that is large enough to hold the canonical
1.412 + * implementation of nsACString. The binary structure of this class is an
1.413 + * implementation detail.
1.414 + *
1.415 + * The string data stored in a string container is always single fragment
1.416 + * and may be null-terminated depending on how it is initialized.
1.417 + *
1.418 + * @see nsStringContainer for use cases and further documentation.
1.419 + */
1.420 +class nsCStringContainer;
1.421 +
1.422 +/**
1.423 + * Flags that may be OR'd together to pass to NS_StringContainerInit2:
1.424 + */
1.425 +enum {
1.426 + /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
1.427 + * string references the passed in data pointer directly. The caller must
1.428 + * ensure that the data is valid for the lifetime of the string container.
1.429 + * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_ADOPT. */
1.430 + NS_CSTRING_CONTAINER_INIT_DEPEND = (1 << 1),
1.431 +
1.432 + /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
1.433 + * string takes ownership over the data pointer. The caller must have
1.434 + * allocated the data array using the XPCOM memory allocator (nsMemory).
1.435 + * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_DEPEND. */
1.436 + NS_CSTRING_CONTAINER_INIT_ADOPT = (1 << 2),
1.437 +
1.438 + /* Data passed into NS_CStringContainerInit2 is a substring that is not
1.439 + * null-terminated. */
1.440 + NS_CSTRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
1.441 +};
1.442 +
1.443 +/**
1.444 + * NS_CStringContainerInit
1.445 + *
1.446 + * @param aContainer string container reference
1.447 + * @return NS_OK if string container successfully initialized
1.448 + *
1.449 + * This function may allocate additional memory for aContainer. When
1.450 + * aContainer is no longer needed, NS_CStringContainerFinish should be called.
1.451 + */
1.452 +XPCOM_API(nsresult)
1.453 +NS_CStringContainerInit(nsCStringContainer &aContainer);
1.454 +
1.455 +/**
1.456 + * NS_CStringContainerInit2
1.457 + *
1.458 + * @param aContainer string container reference
1.459 + * @param aData character buffer (may be null)
1.460 + * @param aDataLength number of characters stored at aData (may pass
1.461 + * UINT32_MAX if aData is null-terminated)
1.462 + * @param aFlags flags affecting how the string container is
1.463 + * initialized. this parameter is ignored when aData
1.464 + * is null. otherwise, if this parameter is 0, then
1.465 + * aData is copied into the string.
1.466 + *
1.467 + * This function resembles NS_CStringContainerInit but provides further
1.468 + * options that permit more efficient memory usage. When aContainer is
1.469 + * no longer needed, NS_CStringContainerFinish should be called.
1.470 + *
1.471 + * NOTE: NS_CStringContainerInit2(container, nullptr, 0, 0) is equivalent to
1.472 + * NS_CStringContainerInit(container).
1.473 + */
1.474 +XPCOM_API(nsresult)
1.475 +NS_CStringContainerInit2
1.476 + (nsCStringContainer &aContainer, const char *aData = nullptr,
1.477 + uint32_t aDataLength = UINT32_MAX, uint32_t aFlags = 0);
1.478 +
1.479 +/**
1.480 + * NS_CStringContainerFinish
1.481 + *
1.482 + * @param aContainer string container reference
1.483 + *
1.484 + * This function frees any memory owned by aContainer.
1.485 + */
1.486 +XPCOM_API(void)
1.487 +NS_CStringContainerFinish(nsCStringContainer &aContainer);
1.488 +
1.489 +/* ------------------------------------------------------------------------- */
1.490 +
1.491 +/**
1.492 + * NS_CStringGetData
1.493 + *
1.494 + * This function returns a const character pointer to the string's internal
1.495 + * buffer, the length of the string, and a boolean value indicating whether
1.496 + * or not the buffer is null-terminated.
1.497 + *
1.498 + * @param aStr abstract string reference
1.499 + * @param aData out param that will hold the address of aStr's
1.500 + * internal buffer
1.501 + * @param aTerminated if non-null, this out param will be set to indicate
1.502 + * whether or not aStr's internal buffer is null-
1.503 + * terminated
1.504 + * @return length of aStr's internal buffer
1.505 + */
1.506 +XPCOM_API(uint32_t)
1.507 +NS_CStringGetData
1.508 + (const nsACString &aStr, const char **aData,
1.509 + bool *aTerminated = nullptr);
1.510 +
1.511 +/**
1.512 + * NS_CStringGetMutableData
1.513 + *
1.514 + * This function provides mutable access to a string's internal buffer. It
1.515 + * returns a pointer to an array of characters that may be modified. The
1.516 + * returned pointer remains valid until the string object is passed to some
1.517 + * other string function.
1.518 + *
1.519 + * Optionally, this function may be used to resize the string's internal
1.520 + * buffer. The aDataLength parameter specifies the requested length of the
1.521 + * string's internal buffer. By passing some value other than UINT32_MAX,
1.522 + * the caller can request that the buffer be resized to the specified number of
1.523 + * characters before returning. The caller is not responsible for writing a
1.524 + * null-terminator.
1.525 + *
1.526 + * @param aStr abstract string reference
1.527 + * @param aDataLength number of characters to resize the string's internal
1.528 + * buffer to or UINT32_MAX if no resizing is needed
1.529 + * @param aData out param that upon return holds the address of aStr's
1.530 + * internal buffer or null if the function failed
1.531 + * @return number of characters or zero if the function failed
1.532 + *
1.533 + * This function does not necessarily null-terminate aStr after resizing its
1.534 + * internal buffer. The behavior depends on the implementation of the abstract
1.535 + * string, aStr. If aStr is a reference to a nsStringContainer, then its data
1.536 + * will be null-terminated by this function.
1.537 + */
1.538 +XPCOM_API(uint32_t)
1.539 +NS_CStringGetMutableData
1.540 + (nsACString &aStr, uint32_t aDataLength, char **aData);
1.541 +
1.542 +/**
1.543 + * NS_CStringCloneData
1.544 + *
1.545 + * This function returns a null-terminated copy of the string's
1.546 + * internal buffer.
1.547 + *
1.548 + * @param aStr abstract string reference
1.549 + * @return null-terminated copy of the string's internal buffer
1.550 + * (it must be free'd using using nsMemory::Free)
1.551 + */
1.552 +XPCOM_API(char *)
1.553 +NS_CStringCloneData
1.554 + (const nsACString &aStr);
1.555 +
1.556 +/**
1.557 + * NS_CStringSetData
1.558 + *
1.559 + * This function copies aData into aStr.
1.560 + *
1.561 + * @param aStr abstract string reference
1.562 + * @param aData character buffer
1.563 + * @param aDataLength number of characters to copy from source string (pass
1.564 + * UINT32_MAX to copy until end of aData, designated by
1.565 + * a null character)
1.566 + * @return NS_OK if function succeeded
1.567 + *
1.568 + * This function does not necessarily null-terminate aStr after copying data
1.569 + * from aData. The behavior depends on the implementation of the abstract
1.570 + * string, aStr. If aStr is a reference to a nsStringContainer, then its data
1.571 + * will be null-terminated by this function.
1.572 + */
1.573 +XPCOM_API(nsresult)
1.574 +NS_CStringSetData
1.575 + (nsACString &aStr, const char *aData,
1.576 + uint32_t aDataLength = UINT32_MAX);
1.577 +
1.578 +/**
1.579 + * NS_CStringSetDataRange
1.580 + *
1.581 + * This function copies aData into a section of aStr. As a result it can be
1.582 + * used to insert new characters into the string.
1.583 + *
1.584 + * @param aStr abstract string reference
1.585 + * @param aCutOffset starting index where the string's existing data
1.586 + * is to be overwritten (pass UINT32_MAX to cause
1.587 + * aData to be appended to the end of aStr, in which
1.588 + * case the value of aCutLength is ignored).
1.589 + * @param aCutLength number of characters to overwrite starting at
1.590 + * aCutOffset (pass UINT32_MAX to overwrite until the
1.591 + * end of aStr).
1.592 + * @param aData character buffer (pass null to cause this function
1.593 + * to simply remove the "cut" range)
1.594 + * @param aDataLength number of characters to copy from source string (pass
1.595 + * UINT32_MAX to copy until end of aData, designated by
1.596 + * a null character)
1.597 + * @return NS_OK if function succeeded
1.598 + *
1.599 + * This function does not necessarily null-terminate aStr after copying data
1.600 + * from aData. The behavior depends on the implementation of the abstract
1.601 + * string, aStr. If aStr is a reference to a nsStringContainer, then its data
1.602 + * will be null-terminated by this function.
1.603 + */
1.604 +XPCOM_API(nsresult)
1.605 +NS_CStringSetDataRange
1.606 + (nsACString &aStr, uint32_t aCutOffset, uint32_t aCutLength,
1.607 + const char *aData, uint32_t aDataLength = UINT32_MAX);
1.608 +
1.609 +/**
1.610 + * NS_CStringCopy
1.611 + *
1.612 + * This function makes aDestStr have the same value as aSrcStr. It is
1.613 + * provided as an optimization.
1.614 + *
1.615 + * @param aDestStr abstract string reference to be modified
1.616 + * @param aSrcStr abstract string reference containing source string
1.617 + * @return NS_OK if function succeeded
1.618 + *
1.619 + * This function does not necessarily null-terminate aDestStr after copying
1.620 + * data from aSrcStr. The behavior depends on the implementation of the
1.621 + * abstract string, aDestStr. If aDestStr is a reference to a
1.622 + * nsStringContainer, then its data will be null-terminated by this function.
1.623 + */
1.624 +XPCOM_API(nsresult)
1.625 +NS_CStringCopy
1.626 + (nsACString &aDestStr, const nsACString &aSrcStr);
1.627 +
1.628 +/**
1.629 + * NS_CStringAppendData
1.630 + *
1.631 + * This function appends data to the existing value of aStr.
1.632 + *
1.633 + * @param aStr abstract string reference to be modified
1.634 + * @param aData character buffer
1.635 + * @param aDataLength number of characters to append (pass UINT32_MAX to
1.636 + * append until a null-character is encountered)
1.637 + * @return NS_OK if function succeeded
1.638 + *
1.639 + * This function does not necessarily null-terminate aStr upon completion.
1.640 + * The behavior depends on the implementation of the abstract string, aStr.
1.641 + * If aStr is a reference to a nsStringContainer, then its data will be null-
1.642 + * terminated by this function.
1.643 + */
1.644 +inline NS_HIDDEN_(nsresult)
1.645 +NS_CStringAppendData(nsACString &aStr, const char *aData,
1.646 + uint32_t aDataLength = UINT32_MAX)
1.647 +{
1.648 + return NS_CStringSetDataRange(aStr, UINT32_MAX, 0, aData, aDataLength);
1.649 +}
1.650 +
1.651 +/**
1.652 + * NS_CStringInsertData
1.653 + *
1.654 + * This function inserts data into the existing value of aStr at the specified
1.655 + * offset.
1.656 + *
1.657 + * @param aStr abstract string reference to be modified
1.658 + * @param aOffset specifies where in the string to insert aData
1.659 + * @param aData character buffer
1.660 + * @param aDataLength number of characters to append (pass UINT32_MAX to
1.661 + * append until a null-character is encountered)
1.662 + * @return NS_OK if function succeeded
1.663 + *
1.664 + * This function does not necessarily null-terminate aStr upon completion.
1.665 + * The behavior depends on the implementation of the abstract string, aStr.
1.666 + * If aStr is a reference to a nsStringContainer, then its data will be null-
1.667 + * terminated by this function.
1.668 + */
1.669 +inline NS_HIDDEN_(nsresult)
1.670 +NS_CStringInsertData(nsACString &aStr, uint32_t aOffset, const char *aData,
1.671 + uint32_t aDataLength = UINT32_MAX)
1.672 +{
1.673 + return NS_CStringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
1.674 +}
1.675 +
1.676 +/**
1.677 + * NS_CStringCutData
1.678 + *
1.679 + * This function shortens the existing value of aStr, by removing characters
1.680 + * at the specified offset.
1.681 + *
1.682 + * @param aStr abstract string reference to be modified
1.683 + * @param aCutOffset specifies where in the string to insert aData
1.684 + * @param aCutLength number of characters to remove
1.685 + * @return NS_OK if function succeeded
1.686 + */
1.687 +inline NS_HIDDEN_(nsresult)
1.688 +NS_CStringCutData(nsACString &aStr, uint32_t aCutOffset, uint32_t aCutLength)
1.689 +{
1.690 + return NS_CStringSetDataRange(aStr, aCutOffset, aCutLength, nullptr, 0);
1.691 +}
1.692 +
1.693 +/**
1.694 + * NS_CStringSetIsVoid
1.695 + *
1.696 + * This function marks a string as being a "void string". Any data in the
1.697 + * string will be lost.
1.698 + */
1.699 +XPCOM_API(void)
1.700 +NS_CStringSetIsVoid(nsACString& aStr, const bool aIsVoid);
1.701 +
1.702 +/**
1.703 + * NS_CStringGetIsVoid
1.704 + *
1.705 + * This function provides a way to test if a string is a "void string", as
1.706 + * marked by NS_CStringSetIsVoid.
1.707 + */
1.708 +XPCOM_API(bool)
1.709 +NS_CStringGetIsVoid(const nsACString& aStr);
1.710 +
1.711 +/* ------------------------------------------------------------------------- */
1.712 +
1.713 +/**
1.714 + * Encodings that can be used with the following conversion routines.
1.715 + */
1.716 +enum nsCStringEncoding {
1.717 + /* Conversion between ASCII and UTF-16 assumes that all bytes in the source
1.718 + * string are 7-bit ASCII and can be inflated to UTF-16 by inserting null
1.719 + * bytes. Reverse conversion is done by truncating every other byte. The
1.720 + * conversion may result in loss and/or corruption of information if the
1.721 + * strings do not strictly contain ASCII data. */
1.722 + NS_CSTRING_ENCODING_ASCII = 0,
1.723 +
1.724 + /* Conversion between UTF-8 and UTF-16 is non-lossy. */
1.725 + NS_CSTRING_ENCODING_UTF8 = 1,
1.726 +
1.727 + /* Conversion from UTF-16 to the native filesystem charset may result in a
1.728 + * loss of information. No attempt is made to protect against data loss in
1.729 + * this case. The native filesystem charset applies to strings passed to
1.730 + * the "Native" method variants on nsIFile. */
1.731 + NS_CSTRING_ENCODING_NATIVE_FILESYSTEM = 2
1.732 +};
1.733 +
1.734 +/**
1.735 + * NS_CStringToUTF16
1.736 + *
1.737 + * This function converts the characters in a nsACString to an array of UTF-16
1.738 + * characters, in the platform endianness. The result is stored in a nsAString
1.739 + * object.
1.740 + *
1.741 + * @param aSource abstract string reference containing source string
1.742 + * @param aSrcEncoding character encoding of the source string
1.743 + * @param aDest abstract string reference to hold the result
1.744 + */
1.745 +XPCOM_API(nsresult)
1.746 +NS_CStringToUTF16(const nsACString &aSource, nsCStringEncoding aSrcEncoding,
1.747 + nsAString &aDest);
1.748 +
1.749 +/**
1.750 + * NS_UTF16ToCString
1.751 + *
1.752 + * This function converts the UTF-16 characters in a nsAString to a single-byte
1.753 + * encoding. The result is stored in a nsACString object. In some cases this
1.754 + * conversion may be lossy. In such cases, the conversion may succeed with a
1.755 + * return code indicating loss of information. The exact behavior is not
1.756 + * specified at this time.
1.757 + *
1.758 + * @param aSource abstract string reference containing source string
1.759 + * @param aDestEncoding character encoding of the resulting string
1.760 + * @param aDest abstract string reference to hold the result
1.761 + */
1.762 +XPCOM_API(nsresult)
1.763 +NS_UTF16ToCString(const nsAString &aSource, nsCStringEncoding aDestEncoding,
1.764 + nsACString &aDest);
1.765 +
1.766 +#endif // nsXPCOMStrings_h__
