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