The Tor Browser / file revision

 /* vim:set ts=2 sw=2 et cindent: */

 /* 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.

  *

  *   NS_METHOD 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.

  *

  *   NS_METHOD 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 nsMemory::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 nsMemory::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__