diff options
Diffstat (limited to 'xpcom/string/nsXPCOMStrings.h')
| -rw-r--r-- | xpcom/string/nsXPCOMStrings.h | 748 |
1 files changed, 748 insertions, 0 deletions
diff --git a/xpcom/string/nsXPCOMStrings.h b/xpcom/string/nsXPCOMStrings.h new file mode 100644 index 0000000000..493e092d69 --- /dev/null +++ b/xpcom/string/nsXPCOMStrings.h @@ -0,0 +1,748 @@ +/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* vim: set ts=8 sts=2 et sw=2 tw=80: */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#ifndef nsXPCOMStrings_h__ +#define nsXPCOMStrings_h__ + +#include <string.h> +#include "nscore.h" +#include <limits> + +/** + * nsXPCOMStrings.h + * + * This file describes a minimal API for working with XPCOM's abstract + * string classes. It divorces the consumer from having any run-time + * dependency on the implementation details of the abstract string types. + */ + +#include "nscore.h" + +/* The base string types */ +class nsAString; +class nsACString; + +/* ------------------------------------------------------------------------- */ + +/** + * nsStringContainer + * + * This is an opaque data type that is large enough to hold the canonical + * implementation of nsAString. The binary structure of this class is an + * implementation detail. + * + * The string data stored in a string container is always single fragment + * and may be null-terminated depending on how it is initialized. + * + * Typically, string containers are allocated on the stack for temporary + * use. However, they can also be malloc'd if necessary. In either case, + * a string container is not useful until it has been initialized with a + * call to NS_StringContainerInit. The following example shows how to use + * a string container to call a function that takes a |nsAString &| out-param. + * + * nsresult GetBlah(nsAString &aBlah); + * + * nsresult MyCode() + * { + * nsresult rv; + * + * nsStringContainer sc; + * rv = NS_StringContainerInit(sc); + * if (NS_FAILED(rv)) + * return rv; + * + * rv = GetBlah(sc); + * if (NS_SUCCEEDED(rv)) + * { + * const char16_t *data; + * NS_StringGetData(sc, &data); + * // + * // |data| now points to the result of the GetBlah function + * // + * } + * + * NS_StringContainerFinish(sc); + * return rv; + * } + * + * The following example show how to use a string container to pass a string + * parameter to a function taking a |const nsAString &| in-param. + * + * nsresult SetBlah(const nsAString &aBlah); + * + * nsresult MyCode() + * { + * nsresult rv; + * + * nsStringContainer sc; + * rv = NS_StringContainerInit(sc); + * if (NS_FAILED(rv)) + * return rv; + * + * const char16_t kData[] = {'x','y','z','\0'}; + * rv = NS_StringSetData(sc, kData, sizeof(kData)/2 - 1); + * if (NS_SUCCEEDED(rv)) + * rv = SetBlah(sc); + * + * NS_StringContainerFinish(sc); + * return rv; + * } + */ +class nsStringContainer; + + +/** + * This struct is never used directly. It is designed to have the same + * size as nsString. It can be stack and heap allocated and the internal + * functions cast it to nsString. + * While this practice is a strict aliasing violation, it doesn't seem to + * cause problems since the the struct is only accessed via the casts to + * nsString. + * We use protected instead of private to avoid compiler warnings about + * the members being unused. + */ +struct nsStringContainer_base +{ +protected: + void* d1; + uint32_t d2; + uint32_t d3; +}; + +/** + * Flags that may be OR'd together to pass to NS_StringContainerInit2: + */ +enum +{ + /* Data passed into NS_StringContainerInit2 is not copied; instead, the + * string references the passed in data pointer directly. The caller must + * ensure that the data is valid for the lifetime of the string container. + * This flag should not be combined with NS_STRING_CONTAINER_INIT_ADOPT. */ + NS_STRING_CONTAINER_INIT_DEPEND = (1 << 1), + + /* Data passed into NS_StringContainerInit2 is not copied; instead, the + * string takes ownership over the data pointer. The caller must have + * allocated the data array using the XPCOM memory allocator (nsMemory). + * This flag should not be combined with NS_STRING_CONTAINER_INIT_DEPEND. */ + NS_STRING_CONTAINER_INIT_ADOPT = (1 << 2), + + /* Data passed into NS_StringContainerInit2 is a substring that is not + * null-terminated. */ + NS_STRING_CONTAINER_INIT_SUBSTRING = (1 << 3) +}; + +/** + * NS_StringContainerInit + * + * @param aContainer string container reference + * @return NS_OK if string container successfully initialized + * + * This function may allocate additional memory for aContainer. When + * aContainer is no longer needed, NS_StringContainerFinish should be called. + */ +XPCOM_API(nsresult) NS_StringContainerInit(nsStringContainer& aContainer); + +/** + * NS_StringContainerInit2 + * + * @param aContainer string container reference + * @param aData character buffer (may be null) + * @param aDataLength number of characters stored at aData (may pass + * UINT32_MAX if aData is null-terminated) + * @param aFlags flags affecting how the string container is + * initialized. this parameter is ignored when aData + * is null. otherwise, if this parameter is 0, then + * aData is copied into the string. + * + * This function resembles NS_StringContainerInit but provides further + * options that permit more efficient memory usage. When aContainer is + * no longer needed, NS_StringContainerFinish should be called. + * + * NOTE: NS_StringContainerInit2(container, nullptr, 0, 0) is equivalent to + * NS_StringContainerInit(container). + */ +XPCOM_API(nsresult) NS_StringContainerInit2(nsStringContainer& aContainer, + const char16_t* aData = nullptr, + uint32_t aDataLength = UINT32_MAX, + uint32_t aFlags = 0); + +/** + * NS_StringContainerFinish + * + * @param aContainer string container reference + * + * This function frees any memory owned by aContainer. + */ +XPCOM_API(void) NS_StringContainerFinish(nsStringContainer& aContainer); + +/* ------------------------------------------------------------------------- */ + +/** + * NS_StringGetData + * + * This function returns a const character pointer to the string's internal + * buffer, the length of the string, and a boolean value indicating whether + * or not the buffer is null-terminated. + * + * @param aStr abstract string reference + * @param aData out param that will hold the address of aStr's + * internal buffer + * @param aTerminated if non-null, this out param will be set to indicate + * whether or not aStr's internal buffer is null- + * terminated + * @return length of aStr's internal buffer + */ +XPCOM_API(uint32_t) NS_StringGetData(const nsAString& aStr, + const char16_t** aData, + bool* aTerminated = nullptr); + +/** + * NS_StringGetMutableData + * + * This function provides mutable access to a string's internal buffer. It + * returns a pointer to an array of characters that may be modified. The + * returned pointer remains valid until the string object is passed to some + * other string function. + * + * Optionally, this function may be used to resize the string's internal + * buffer. The aDataLength parameter specifies the requested length of the + * string's internal buffer. By passing some value other than UINT32_MAX, + * the caller can request that the buffer be resized to the specified number of + * characters before returning. The caller is not responsible for writing a + * null-terminator. + * + * @param aStr abstract string reference + * @param aDataLength number of characters to resize the string's internal + * buffer to or UINT32_MAX if no resizing is needed + * @param aData out param that upon return holds the address of aStr's + * internal buffer or null if the function failed + * @return number of characters or zero if the function failed + * + * This function does not necessarily null-terminate aStr after resizing its + * internal buffer. The behavior depends on the implementation of the abstract + * string, aStr. If aStr is a reference to a nsStringContainer, then its data + * will be null-terminated by this function. + */ +XPCOM_API(uint32_t) NS_StringGetMutableData(nsAString& aStr, + uint32_t aDataLength, + char16_t** aData); + +/** + * NS_StringCloneData + * + * This function returns a null-terminated copy of the string's + * internal buffer. + * + * @param aStr abstract string reference + * @return null-terminated copy of the string's internal buffer + * (it must be free'd using using free) + */ +XPCOM_API(char16_t*) NS_StringCloneData(const nsAString& aStr); + +/** + * NS_StringSetData + * + * This function copies aData into aStr. + * + * @param aStr abstract string reference + * @param aData character buffer + * @param aDataLength number of characters to copy from source string (pass + * UINT32_MAX to copy until end of aData, designated by + * a null character) + * @return NS_OK if function succeeded + * + * This function does not necessarily null-terminate aStr after copying data + * from aData. The behavior depends on the implementation of the abstract + * string, aStr. If aStr is a reference to a nsStringContainer, then its data + * will be null-terminated by this function. + */ +XPCOM_API(nsresult) NS_StringSetData(nsAString& aStr, const char16_t* aData, + uint32_t aDataLength = UINT32_MAX); + +/** + * NS_StringSetDataRange + * + * This function copies aData into a section of aStr. As a result it can be + * used to insert new characters into the string. + * + * @param aStr abstract string reference + * @param aCutOffset starting index where the string's existing data + * is to be overwritten (pass UINT32_MAX to cause + * aData to be appended to the end of aStr, in which + * case the value of aCutLength is ignored). + * @param aCutLength number of characters to overwrite starting at + * aCutOffset (pass UINT32_MAX to overwrite until the + * end of aStr). + * @param aData character buffer (pass null to cause this function + * to simply remove the "cut" range) + * @param aDataLength number of characters to copy from source string (pass + * UINT32_MAX to copy until end of aData, designated by + * a null character) + * @return NS_OK if function succeeded + * + * This function does not necessarily null-terminate aStr after copying data + * from aData. The behavior depends on the implementation of the abstract + * string, aStr. If aStr is a reference to a nsStringContainer, then its data + * will be null-terminated by this function. + */ +XPCOM_API(nsresult) NS_StringSetDataRange(nsAString& aStr, + uint32_t aCutOffset, uint32_t aCutLength, + const char16_t* aData, + uint32_t aDataLength = UINT32_MAX); + +/** + * NS_StringCopy + * + * This function makes aDestStr have the same value as aSrcStr. It is + * provided as an optimization. + * + * @param aDestStr abstract string reference to be modified + * @param aSrcStr abstract string reference containing source string + * @return NS_OK if function succeeded + * + * This function does not necessarily null-terminate aDestStr after copying + * data from aSrcStr. The behavior depends on the implementation of the + * abstract string, aDestStr. If aDestStr is a reference to a + * nsStringContainer, then its data will be null-terminated by this function. + */ +XPCOM_API(nsresult) NS_StringCopy(nsAString& aDestStr, + const nsAString& aSrcStr); + +/** + * NS_StringAppendData + * + * This function appends data to the existing value of aStr. + * + * @param aStr abstract string reference to be modified + * @param aData character buffer + * @param aDataLength number of characters to append (pass UINT32_MAX to + * append until a null-character is encountered) + * @return NS_OK if function succeeded + * + * This function does not necessarily null-terminate aStr upon completion. + * The behavior depends on the implementation of the abstract string, aStr. + * If aStr is a reference to a nsStringContainer, then its data will be null- + * terminated by this function. + */ +inline NS_HIDDEN_(nsresult) +NS_StringAppendData(nsAString& aStr, const char16_t* aData, + uint32_t aDataLength = UINT32_MAX) +{ + return NS_StringSetDataRange(aStr, UINT32_MAX, 0, aData, aDataLength); +} + +/** + * NS_StringInsertData + * + * This function inserts data into the existing value of aStr at the specified + * offset. + * + * @param aStr abstract string reference to be modified + * @param aOffset specifies where in the string to insert aData + * @param aData character buffer + * @param aDataLength number of characters to append (pass UINT32_MAX to + * append until a null-character is encountered) + * @return NS_OK if function succeeded + * + * This function does not necessarily null-terminate aStr upon completion. + * The behavior depends on the implementation of the abstract string, aStr. + * If aStr is a reference to a nsStringContainer, then its data will be null- + * terminated by this function. + */ +inline NS_HIDDEN_(nsresult) +NS_StringInsertData(nsAString& aStr, uint32_t aOffset, const char16_t* aData, + uint32_t aDataLength = UINT32_MAX) +{ + return NS_StringSetDataRange(aStr, aOffset, 0, aData, aDataLength); +} + +/** + * NS_StringCutData + * + * This function shortens the existing value of aStr, by removing characters + * at the specified offset. + * + * @param aStr abstract string reference to be modified + * @param aCutOffset specifies where in the string to insert aData + * @param aCutLength number of characters to remove + * @return NS_OK if function succeeded + */ +inline NS_HIDDEN_(nsresult) +NS_StringCutData(nsAString& aStr, uint32_t aCutOffset, uint32_t aCutLength) +{ + return NS_StringSetDataRange(aStr, aCutOffset, aCutLength, nullptr, 0); +} + +/** + * NS_StringSetIsVoid + * + * This function marks a string as being a "void string". Any data in the + * string will be lost. + */ +XPCOM_API(void) NS_StringSetIsVoid(nsAString& aStr, const bool aIsVoid); + +/** + * NS_StringGetIsVoid + * + * This function provides a way to test if a string is a "void string", as + * marked by NS_StringSetIsVoid. + */ +XPCOM_API(bool) NS_StringGetIsVoid(const nsAString& aStr); + +/* ------------------------------------------------------------------------- */ + +/** + * nsCStringContainer + * + * This is an opaque data type that is large enough to hold the canonical + * implementation of nsACString. The binary structure of this class is an + * implementation detail. + * + * The string data stored in a string container is always single fragment + * and may be null-terminated depending on how it is initialized. + * + * @see nsStringContainer for use cases and further documentation. + */ +class nsCStringContainer; + +/** + * Flags that may be OR'd together to pass to NS_StringContainerInit2: + */ +enum +{ + /* Data passed into NS_CStringContainerInit2 is not copied; instead, the + * string references the passed in data pointer directly. The caller must + * ensure that the data is valid for the lifetime of the string container. + * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_ADOPT. */ + NS_CSTRING_CONTAINER_INIT_DEPEND = (1 << 1), + + /* Data passed into NS_CStringContainerInit2 is not copied; instead, the + * string takes ownership over the data pointer. The caller must have + * allocated the data array using the XPCOM memory allocator (nsMemory). + * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_DEPEND. */ + NS_CSTRING_CONTAINER_INIT_ADOPT = (1 << 2), + + /* Data passed into NS_CStringContainerInit2 is a substring that is not + * null-terminated. */ + NS_CSTRING_CONTAINER_INIT_SUBSTRING = (1 << 3) +}; + +/** + * NS_CStringContainerInit + * + * @param aContainer string container reference + * @return NS_OK if string container successfully initialized + * + * This function may allocate additional memory for aContainer. When + * aContainer is no longer needed, NS_CStringContainerFinish should be called. + */ +XPCOM_API(nsresult) NS_CStringContainerInit(nsCStringContainer& aContainer); + +/** + * NS_CStringContainerInit2 + * + * @param aContainer string container reference + * @param aData character buffer (may be null) + * @param aDataLength number of characters stored at aData (may pass + * UINT32_MAX if aData is null-terminated) + * @param aFlags flags affecting how the string container is + * initialized. this parameter is ignored when aData + * is null. otherwise, if this parameter is 0, then + * aData is copied into the string. + * + * This function resembles NS_CStringContainerInit but provides further + * options that permit more efficient memory usage. When aContainer is + * no longer needed, NS_CStringContainerFinish should be called. + * + * NOTE: NS_CStringContainerInit2(container, nullptr, 0, 0) is equivalent to + * NS_CStringContainerInit(container). + */ +XPCOM_API(nsresult) NS_CStringContainerInit2(nsCStringContainer& aContainer, + const char* aData = nullptr, + uint32_t aDataLength = UINT32_MAX, + uint32_t aFlags = 0); + +/** + * NS_CStringContainerFinish + * + * @param aContainer string container reference + * + * This function frees any memory owned by aContainer. + */ +XPCOM_API(void) NS_CStringContainerFinish(nsCStringContainer& aContainer); + +/* ------------------------------------------------------------------------- */ + +/** + * NS_CStringGetData + * + * This function returns a const character pointer to the string's internal + * buffer, the length of the string, and a boolean value indicating whether + * or not the buffer is null-terminated. + * + * @param aStr abstract string reference + * @param aData out param that will hold the address of aStr's + * internal buffer + * @param aTerminated if non-null, this out param will be set to indicate + * whether or not aStr's internal buffer is null- + * terminated + * @return length of aStr's internal buffer + */ +XPCOM_API(uint32_t) NS_CStringGetData(const nsACString& aStr, + const char** aData, + bool* aTerminated = nullptr); + +/** + * NS_CStringGetMutableData + * + * This function provides mutable access to a string's internal buffer. It + * returns a pointer to an array of characters that may be modified. The + * returned pointer remains valid until the string object is passed to some + * other string function. + * + * Optionally, this function may be used to resize the string's internal + * buffer. The aDataLength parameter specifies the requested length of the + * string's internal buffer. By passing some value other than UINT32_MAX, + * the caller can request that the buffer be resized to the specified number of + * characters before returning. The caller is not responsible for writing a + * null-terminator. + * + * @param aStr abstract string reference + * @param aDataLength number of characters to resize the string's internal + * buffer to or UINT32_MAX if no resizing is needed + * @param aData out param that upon return holds the address of aStr's + * internal buffer or null if the function failed + * @return number of characters or zero if the function failed + * + * This function does not necessarily null-terminate aStr after resizing its + * internal buffer. The behavior depends on the implementation of the abstract + * string, aStr. If aStr is a reference to a nsStringContainer, then its data + * will be null-terminated by this function. + */ +XPCOM_API(uint32_t) NS_CStringGetMutableData(nsACString& aStr, + uint32_t aDataLength, + char** aData); + +/** + * NS_CStringCloneData + * + * This function returns a null-terminated copy of the string's + * internal buffer. + * + * @param aStr abstract string reference + * @return null-terminated copy of the string's internal buffer + * (it must be free'd using using free) + */ +XPCOM_API(char*) NS_CStringCloneData(const nsACString& aStr); + +/** + * NS_CStringSetData + * + * This function copies aData into aStr. + * + * @param aStr abstract string reference + * @param aData character buffer + * @param aDataLength number of characters to copy from source string (pass + * UINT32_MAX to copy until end of aData, designated by + * a null character) + * @return NS_OK if function succeeded + * + * This function does not necessarily null-terminate aStr after copying data + * from aData. The behavior depends on the implementation of the abstract + * string, aStr. If aStr is a reference to a nsStringContainer, then its data + * will be null-terminated by this function. + */ +XPCOM_API(nsresult) NS_CStringSetData(nsACString& aStr, const char* aData, + uint32_t aDataLength = UINT32_MAX); + +/** + * NS_CStringSetDataRange + * + * This function copies aData into a section of aStr. As a result it can be + * used to insert new characters into the string. + * + * @param aStr abstract string reference + * @param aCutOffset starting index where the string's existing data + * is to be overwritten (pass UINT32_MAX to cause + * aData to be appended to the end of aStr, in which + * case the value of aCutLength is ignored). + * @param aCutLength number of characters to overwrite starting at + * aCutOffset (pass UINT32_MAX to overwrite until the + * end of aStr). + * @param aData character buffer (pass null to cause this function + * to simply remove the "cut" range) + * @param aDataLength number of characters to copy from source string (pass + * UINT32_MAX to copy until end of aData, designated by + * a null character) + * @return NS_OK if function succeeded + * + * This function does not necessarily null-terminate aStr after copying data + * from aData. The behavior depends on the implementation of the abstract + * string, aStr. If aStr is a reference to a nsStringContainer, then its data + * will be null-terminated by this function. + */ +XPCOM_API(nsresult) NS_CStringSetDataRange(nsACString& aStr, + uint32_t aCutOffset, + uint32_t aCutLength, + const char* aData, + uint32_t aDataLength = UINT32_MAX); + +/** + * NS_CStringCopy + * + * This function makes aDestStr have the same value as aSrcStr. It is + * provided as an optimization. + * + * @param aDestStr abstract string reference to be modified + * @param aSrcStr abstract string reference containing source string + * @return NS_OK if function succeeded + * + * This function does not necessarily null-terminate aDestStr after copying + * data from aSrcStr. The behavior depends on the implementation of the + * abstract string, aDestStr. If aDestStr is a reference to a + * nsStringContainer, then its data will be null-terminated by this function. + */ +XPCOM_API(nsresult) NS_CStringCopy(nsACString& aDestStr, + const nsACString& aSrcStr); + +/** + * NS_CStringAppendData + * + * This function appends data to the existing value of aStr. + * + * @param aStr abstract string reference to be modified + * @param aData character buffer + * @param aDataLength number of characters to append (pass UINT32_MAX to + * append until a null-character is encountered) + * @return NS_OK if function succeeded + * + * This function does not necessarily null-terminate aStr upon completion. + * The behavior depends on the implementation of the abstract string, aStr. + * If aStr is a reference to a nsStringContainer, then its data will be null- + * terminated by this function. + */ +inline NS_HIDDEN_(nsresult) +NS_CStringAppendData(nsACString& aStr, const char* aData, + uint32_t aDataLength = UINT32_MAX) +{ + return NS_CStringSetDataRange(aStr, UINT32_MAX, 0, aData, aDataLength); +} + +/** + * NS_CStringInsertData + * + * This function inserts data into the existing value of aStr at the specified + * offset. + * + * @param aStr abstract string reference to be modified + * @param aOffset specifies where in the string to insert aData + * @param aData character buffer + * @param aDataLength number of characters to append (pass UINT32_MAX to + * append until a null-character is encountered) + * @return NS_OK if function succeeded + * + * This function does not necessarily null-terminate aStr upon completion. + * The behavior depends on the implementation of the abstract string, aStr. + * If aStr is a reference to a nsStringContainer, then its data will be null- + * terminated by this function. + */ +inline NS_HIDDEN_(nsresult) +NS_CStringInsertData(nsACString& aStr, uint32_t aOffset, const char* aData, + uint32_t aDataLength = UINT32_MAX) +{ + return NS_CStringSetDataRange(aStr, aOffset, 0, aData, aDataLength); +} + +/** + * NS_CStringCutData + * + * This function shortens the existing value of aStr, by removing characters + * at the specified offset. + * + * @param aStr abstract string reference to be modified + * @param aCutOffset specifies where in the string to insert aData + * @param aCutLength number of characters to remove + * @return NS_OK if function succeeded + */ +inline NS_HIDDEN_(nsresult) +NS_CStringCutData(nsACString& aStr, uint32_t aCutOffset, uint32_t aCutLength) +{ + return NS_CStringSetDataRange(aStr, aCutOffset, aCutLength, nullptr, 0); +} + +/** + * NS_CStringSetIsVoid + * + * This function marks a string as being a "void string". Any data in the + * string will be lost. + */ +XPCOM_API(void) NS_CStringSetIsVoid(nsACString& aStr, const bool aIsVoid); + +/** + * NS_CStringGetIsVoid + * + * This function provides a way to test if a string is a "void string", as + * marked by NS_CStringSetIsVoid. + */ +XPCOM_API(bool) NS_CStringGetIsVoid(const nsACString& aStr); + +/* ------------------------------------------------------------------------- */ + +/** + * Encodings that can be used with the following conversion routines. + */ +enum nsCStringEncoding +{ + /* Conversion between ASCII and UTF-16 assumes that all bytes in the source + * string are 7-bit ASCII and can be inflated to UTF-16 by inserting null + * bytes. Reverse conversion is done by truncating every other byte. The + * conversion may result in loss and/or corruption of information if the + * strings do not strictly contain ASCII data. */ + NS_CSTRING_ENCODING_ASCII = 0, + + /* Conversion between UTF-8 and UTF-16 is non-lossy. */ + NS_CSTRING_ENCODING_UTF8 = 1, + + /* Conversion from UTF-16 to the native filesystem charset may result in a + * loss of information. No attempt is made to protect against data loss in + * this case. The native filesystem charset applies to strings passed to + * the "Native" method variants on nsIFile. */ + NS_CSTRING_ENCODING_NATIVE_FILESYSTEM = 2 +}; + +/** + * NS_CStringToUTF16 + * + * This function converts the characters in a nsACString to an array of UTF-16 + * characters, in the platform endianness. The result is stored in a nsAString + * object. + * + * @param aSource abstract string reference containing source string + * @param aSrcEncoding character encoding of the source string + * @param aDest abstract string reference to hold the result + */ +XPCOM_API(nsresult) NS_CStringToUTF16(const nsACString& aSource, + nsCStringEncoding aSrcEncoding, + nsAString& aDest); + +/** + * NS_UTF16ToCString + * + * This function converts the UTF-16 characters in a nsAString to a single-byte + * encoding. The result is stored in a nsACString object. In some cases this + * conversion may be lossy. In such cases, the conversion may succeed with a + * return code indicating loss of information. The exact behavior is not + * specified at this time. + * + * @param aSource abstract string reference containing source string + * @param aDestEncoding character encoding of the resulting string + * @param aDest abstract string reference to hold the result + */ +XPCOM_API(nsresult) NS_UTF16ToCString(const nsAString& aSource, + nsCStringEncoding aDestEncoding, + nsACString& aDest); + +#endif // nsXPCOMStrings_h__ |