Version 1.8 of gecko-sdk. Downloaded from here:...

gecko-sdk/include/nsStringAPI.h

+/* vim:set ts=2 sw=2 et cindent: */
+/* ***** BEGIN LICENSE BLOCK *****
+ * Version: MPL 1.1/GPL 2.0/LGPL 2.1
+ *
+ * The contents of this file are subject to the Mozilla Public License Version
+ * 1.1 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ * http://www.mozilla.org/MPL/
+ *
+ * Software distributed under the License is distributed on an "AS IS" basis,
+ * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
+ * for the specific language governing rights and limitations under the
+ * License.
+ *
+ * The Original Code is Mozilla.
+ *
+ * The Initial Developer of the Original Code is IBM Corporation.
+ * Portions created by IBM Corporation are Copyright (C) 2003
+ * IBM Corporation.  All Rights Reserved.
+ *
+ * Contributor(s):
+ *   Darin Fisher <darin@meer.net>
+ *
+ * Alternatively, the contents of this file may be used under the terms of
+ * either the GNU General Public License Version 2 or later (the "GPL"), or
+ * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
+ * in which case the provisions of the GPL or the LGPL are applicable instead
+ * of those above. If you wish to allow use of your version of this file only
+ * under the terms of either the GPL or the LGPL, and not to allow others to
+ * use your version of this file under the terms of the MPL, indicate your
+ * decision by deleting the provisions above and replace them with the notice
+ * and other provisions required by the GPL or the LGPL. If you do not delete
+ * the provisions above, a recipient may use your version of this file under
+ * the terms of any one of the MPL, the GPL or the LGPL.
+ *
+ * ***** END LICENSE BLOCK ***** */
+
+#ifndef nsStringAPI_h__
+#define nsStringAPI_h__
+
+#include <string.h>
+
+/**
+ * nsStringAPI.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.
+ */
+
+// Map frozen functions to private symbol names if not using strict API.
+#ifdef MOZILLA_INTERNAL_API
+# define NS_StringContainerInit           NS_StringContainerInit_P
+# define NS_StringContainerInit2          NS_StringContainerInit2_P
+# define NS_StringContainerFinish         NS_StringContainerFinish_P
+# define NS_StringGetData                 NS_StringGetData_P
+# define NS_StringGetMutableData          NS_StringGetMutableData_P
+# define NS_StringCloneData               NS_StringCloneData_P
+# define NS_StringSetData                 NS_StringSetData_P
+# define NS_StringSetDataRange            NS_StringSetDataRange_P
+# define NS_StringCopy                    NS_StringCopy_P
+# define NS_CStringContainerInit          NS_CStringContainerInit_P
+# define NS_CStringContainerInit2         NS_CStringContainerInit2_P
+# define NS_CStringContainerFinish        NS_CStringContainerFinish_P
+# define NS_CStringGetData                NS_CStringGetData_P
+# define NS_CStringGetMutableData         NS_CStringGetMutableData_P
+# define NS_CStringCloneData              NS_CStringCloneData_P
+# define NS_CStringSetData                NS_CStringSetData_P
+# define NS_CStringSetDataRange           NS_CStringSetDataRange_P
+# define NS_CStringCopy                   NS_CStringCopy_P
+# define NS_CStringToUTF16                NS_CStringToUTF16_P
+# define NS_UTF16ToCString                NS_UTF16ToCString_P
+#endif
+
+#include "nscore.h"
+
+#if defined( XPCOM_GLUE )
+#define NS_STRINGAPI(type) extern "C" NS_HIDDEN_(type)
+#elif defined( _IMPL_NS_STRINGAPI )
+#define NS_STRINGAPI(type) extern "C" NS_EXPORT type
+#else
+#define NS_STRINGAPI(type) extern "C" NS_IMPORT type
+#endif
+
+/* 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 PRUnichar *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 PRUnichar 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;
+
+/**
+ * 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.
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(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
+ *                      PR_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, nsnull, 0, 0) is equivalent to
+ * NS_StringContainerInit(container).
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(nsresult)
+NS_StringContainerInit2
+  (nsStringContainer &aContainer, const PRUnichar *aData = nsnull,
+   PRUint32 aDataLength = PR_UINT32_MAX, PRUint32 aFlags = 0);
+
+/**
+ * NS_StringContainerFinish
+ *
+ * @param aContainer    string container reference
+ *
+ * This function frees any memory owned by aContainer.
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(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
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(PRUint32)
+NS_StringGetData
+  (const nsAString &aStr, const PRUnichar **aData,
+   PRBool *aTerminated = nsnull);
+
+/**
+ * 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 PR_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 PR_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.
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(PRUint32)
+NS_StringGetMutableData
+  (nsAString &aStr, PRUint32 aDataLength, PRUnichar **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)
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(PRUnichar *)
+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
+ *                      PR_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.
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(nsresult)
+NS_StringSetData
+  (nsAString &aStr, const PRUnichar *aData,
+   PRUint32 aDataLength = PR_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 PR_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 PR_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
+ *                      PR_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.
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(nsresult)
+NS_StringSetDataRange
+  (nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
+   const PRUnichar *aData, PRUint32 aDataLength = PR_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.
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(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 PR_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 PRUnichar *aData,
+                    PRUint32 aDataLength = PR_UINT32_MAX)
+{
+  return NS_StringSetDataRange(aStr, PR_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 PR_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, PRUint32 aOffset, const PRUnichar *aData,
+                    PRUint32 aDataLength = PR_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, PRUint32 aCutOffset, PRUint32 aCutLength)
+{
+  return NS_StringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
+}
+
+/* ------------------------------------------------------------------------- */
+
+/**
+ * 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.
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(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
+ *                      PR_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, nsnull, 0, 0) is equivalent to
+ * NS_CStringContainerInit(container).
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(nsresult)
+NS_CStringContainerInit2
+  (nsCStringContainer &aContainer, const char *aData = nsnull,
+   PRUint32 aDataLength = PR_UINT32_MAX, PRUint32 aFlags = 0);
+
+/**
+ * NS_CStringContainerFinish
+ *
+ * @param aContainer    string container reference
+ *
+ * This function frees any memory owned by aContainer.
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(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
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(PRUint32)
+NS_CStringGetData
+  (const nsACString &aStr, const char **aData,
+   PRBool *aTerminated = nsnull);
+
+/**
+ * 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 PR_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 PR_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.
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(PRUint32)
+NS_CStringGetMutableData
+  (nsACString &aStr, PRUint32 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)
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(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
+ *                      PR_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.
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(nsresult)
+NS_CStringSetData
+  (nsACString &aStr, const char *aData,
+   PRUint32 aDataLength = PR_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 PR_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 PR_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
+ *                      PR_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.
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(nsresult)
+NS_CStringSetDataRange
+  (nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
+   const char *aData, PRUint32 aDataLength = PR_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.
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(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 PR_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,
+                    PRUint32 aDataLength = PR_UINT32_MAX)
+{
+  return NS_CStringSetDataRange(aStr, PR_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 PR_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, PRUint32 aOffset, const char *aData,
+                    PRUint32 aDataLength = PR_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, PRUint32 aCutOffset, PRUint32 aCutLength)
+{
+  return NS_CStringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
+}
+
+/* ------------------------------------------------------------------------- */
+
+/**
+ * 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 and nsILocalFile. */
+  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
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(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
+ *
+ * @status FROZEN
+ */
+NS_STRINGAPI(nsresult)
+NS_UTF16ToCString(const nsAString &aSource, nsCStringEncoding aDestEncoding,
+                  nsACString &aDest);
+
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Below we define nsAString and nsACString.  The "_external" suffix is an
+ * implementation detail.  nsAString_external is the name of the external
+ * representation of nsAString from the point of view of the Mozilla codebase.
+ * To a user of this API, nsAString_external is exactly nsAString.
+ *
+ * These classes should be treated as abstract classes with unspecified
+ * structure.  The inline methods are provided as helper functions around the
+ * C-style API provided above.
+ *
+ * Do not try to mix these definitions of nsAString and nsACString with the
+ * internal definition of these classes from nsAString.h in the Mozilla tree.
+ */
+
+#ifndef MOZILLA_INTERNAL_API
+#define nsAString_external nsAString
+#define nsACString_external nsACString
+#endif
+
+class nsAString_external
+{
+#ifndef MOZILLA_INTERNAL_API
+
+public:
+  typedef PRUnichar             char_type;
+  typedef nsAString_external    self_type;
+  typedef PRUint32              size_type;
+  typedef PRUint32              index_type;
+
+  NS_HIDDEN_(const char_type*) BeginReading() const
+  {
+    const char_type *data;
+    NS_StringGetData(*this, &data);
+    return data;
+  }
+
+  NS_HIDDEN_(const char_type*) EndReading() const
+  {
+    const char_type *data;
+    PRUint32 len = NS_StringGetData(*this, &data);
+    return data + len;
+  }
+
+  NS_HIDDEN_(char_type*) BeginWriting()
+  {
+    char_type *data;
+    NS_StringGetMutableData(*this, PR_UINT32_MAX, &data);
+    return data;
+  }
+
+  NS_HIDDEN_(PRBool) SetLength(PRUint32 aLen)
+  {
+    char_type *data;
+    NS_StringGetMutableData(*this, aLen, &data);
+    return data != nsnull;
+  }
+
+  NS_HIDDEN_(size_type) Length() const
+  {
+    const char_type* data;
+    return NS_StringGetData(*this, &data);
+  }
+
+  NS_HIDDEN_(PRBool) IsEmpty() const
+  {
+    return Length() == 0;
+  }
+
+  NS_HIDDEN_(void) Assign(const self_type& aString)
+  {
+    NS_StringCopy(*this, aString);
+  }
+  NS_HIDDEN_(void) Assign(const char_type* aData, size_type aLength = PR_UINT32_MAX)
+  {
+    NS_StringSetData(*this, aData, aLength);
+  }
+  NS_HIDDEN_(void) Assign(char_type aChar)
+  {
+    NS_StringSetData(*this, &aChar, 1);
+  }
+
+  NS_HIDDEN_(self_type&) operator=(const self_type& aString) { Assign(aString);   return *this; }
+  NS_HIDDEN_(self_type&) operator=(const char_type* aPtr)    { Assign(aPtr);      return *this; }
+  NS_HIDDEN_(self_type&) operator=(char_type aChar)          { Assign(aChar);     return *this; }
+
+  NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const char_type* data, size_type length = size_type(-1) )
+  {
+    NS_StringSetDataRange(*this, cutStart, cutLength, data, length);
+  }
+  NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, char_type c )
+  {
+    Replace(cutStart, cutLength, &c, 1);
+  }
+  NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const self_type& readable )
+  {
+    const char_type* data;
+    PRUint32 dataLen = NS_StringGetData(readable, &data);
+    NS_StringSetDataRange(*this, cutStart, cutLength, data, dataLen);
+  }
+
+  NS_HIDDEN_(void) Append( char_type c )                                                              { Replace(size_type(-1), 0, c); }
+  NS_HIDDEN_(void) Append( const char_type* data, size_type length = size_type(-1) )                  { Replace(size_type(-1), 0, data, length); }
+  NS_HIDDEN_(void) Append( const self_type& readable )                                                { Replace(size_type(-1), 0, readable); }
+
+  NS_HIDDEN_(self_type&) operator+=( char_type c )                                                    { Append(c);        return *this; }
+  NS_HIDDEN_(self_type&) operator+=( const char_type* data )                                          { Append(data);     return *this; }
+  NS_HIDDEN_(self_type&) operator+=( const self_type& readable )                                      { Append(readable); return *this; }
+
+  NS_HIDDEN_(void) Insert( char_type c, index_type pos )                                              { Replace(pos, 0, c); }
+  NS_HIDDEN_(void) Insert( const char_type* data, index_type pos, size_type length = size_type(-1) )  { Replace(pos, 0, data, length); }
+  NS_HIDDEN_(void) Insert( const self_type& readable, index_type pos )                                { Replace(pos, 0, readable); }
+
+  NS_HIDDEN_(void) Cut( index_type cutStart, size_type cutLength )                                    { Replace(cutStart, cutLength, nsnull, 0); }
+
+  NS_HIDDEN_(PRBool) Equals( const self_type &other ) const {
+    const char_type *cself;
+    const char_type *cother;
+    PRUint32 selflen = NS_StringGetData(*this, &cself);
+    PRUint32 otherlen = NS_StringGetData(other, &cother);
+
+    if (selflen != otherlen)
+      return PR_FALSE;
+
+    return memcmp(cself, cother, selflen * sizeof(char_type)) == 0;
+  }
+
+#endif // MOZILLA_INTERNAL_API
+
+protected:
+  // Prevent people from allocating a nsAString directly.
+  ~nsAString_external() {}
+
+private:
+  void *v;
+};
+
+class nsACString_external
+{
+#ifndef MOZILLA_INTERNAL_API
+
+public:
+  typedef char                  char_type;
+  typedef nsACString_external   self_type;
+  typedef PRUint32              size_type;
+  typedef PRUint32              index_type;
+
+  NS_HIDDEN_(const char_type*) BeginReading() const
+  {
+    const char_type *data;
+    NS_CStringGetData(*this, &data);
+    return data;
+  }
+
+  NS_HIDDEN_(const char_type*) EndReading() const
+  {
+    const char_type *data;
+    PRUint32 len = NS_CStringGetData(*this, &data);
+    return data + len;
+  }
+
+  NS_HIDDEN_(char_type*) BeginWriting()
+  {
+    char_type *data;
+    NS_CStringGetMutableData(*this, PR_UINT32_MAX, &data);
+    return data;
+  }
+
+  NS_HIDDEN_(PRBool) SetLength(PRUint32 aLen)
+  {
+    char_type *data;
+    NS_CStringGetMutableData(*this, aLen, &data);
+    return data != nsnull;
+  }
+
+  NS_HIDDEN_(size_type) Length() const
+  {
+    const char_type* data;
+    return NS_CStringGetData(*this, &data);
+  }
+
+  NS_HIDDEN_(PRBool) IsEmpty() const
+  {
+    return Length() == 0;
+  }
+
+  NS_HIDDEN_(void) Assign(const self_type& aString)
+  {
+    NS_CStringCopy(*this, aString);
+  }
+  NS_HIDDEN_(void) Assign(const char_type* aData, size_type aLength = PR_UINT32_MAX)
+  {
+    NS_CStringSetData(*this, aData, aLength);
+  }
+  NS_HIDDEN_(void) Assign(char_type aChar)
+  {
+    NS_CStringSetData(*this, &aChar, 1);
+  }
+
+  NS_HIDDEN_(self_type&) operator=(const self_type& aString) { Assign(aString);   return *this; }
+  NS_HIDDEN_(self_type&) operator=(const char_type* aPtr)    { Assign(aPtr);      return *this; }
+  NS_HIDDEN_(self_type&) operator=(char_type aChar)          { Assign(aChar);     return *this; }
+
+  NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const char_type* data, size_type length = size_type(-1) )
+  {
+    NS_CStringSetDataRange(*this, cutStart, cutLength, data, length);
+  }
+  NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, char_type c )
+  {
+    Replace(cutStart, cutLength, &c, 1);
+  }
+  NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const self_type& readable )
+  {
+    const char_type* data;
+    PRUint32 dataLen = NS_CStringGetData(readable, &data);
+    NS_CStringSetDataRange(*this, cutStart, cutLength, data, dataLen);
+  }
+
+  NS_HIDDEN_(void) Append( char_type c )                                                              { Replace(size_type(-1), 0, c); }
+  NS_HIDDEN_(void) Append( const char_type* data, size_type length = size_type(-1) )                  { Replace(size_type(-1), 0, data, length); }
+  NS_HIDDEN_(void) Append( const self_type& readable )                                                { Replace(size_type(-1), 0, readable); }
+
+  NS_HIDDEN_(self_type&) operator+=( char_type c )                                                    { Append(c);        return *this; }
+  NS_HIDDEN_(self_type&) operator+=( const char_type* data )                                          { Append(data);     return *this; }
+  NS_HIDDEN_(self_type&) operator+=( const self_type& readable )                                      { Append(readable); return *this; }
+
+  NS_HIDDEN_(void) Insert( char_type c, index_type pos )                                              { Replace(pos, 0, c); }
+  NS_HIDDEN_(void) Insert( const char_type* data, index_type pos, size_type length = size_type(-1) )  { Replace(pos, 0, data, length); }
+  NS_HIDDEN_(void) Insert( const self_type& readable, index_type pos )                                { Replace(pos, 0, readable); }
+
+  NS_HIDDEN_(void) Cut( index_type cutStart, size_type cutLength )                                    { Replace(cutStart, cutLength, nsnull, 0); }
+
+  NS_HIDDEN_(PRBool) Equals( const self_type &other ) const {
+    const char_type *cself;
+    const char_type *cother;
+    PRUint32 selflen = NS_CStringGetData(*this, &cself);
+    PRUint32 otherlen = NS_CStringGetData(other, &cother);
+
+    if (selflen != otherlen)
+      return PR_FALSE;
+ 
+    return memcmp(cself, cother, selflen * sizeof(char_type)) == 0;
+  }
+
+#endif // MOZILLA_INTERNAL_API
+
+protected:
+  // Prevent people from allocating a nsACString directly.
+  ~nsACString_external() {}
+
+private:
+  void *v;
+};
+
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Below we define nsStringContainer and nsCStringContainer.  These classes
+ * have unspecified structure.  In most cases, your code should use
+ * nsEmbedString instead of these classes; however, if you prefer C-style
+ * programming, then look no further...
+ */
+
+class nsStringContainer : public nsAString_external
+{
+private:
+  void     *d1;
+  PRUint32  d2;
+  void     *d3;
+
+public:
+  nsStringContainer() {} // MSVC6 needs this
+};
+
+class nsCStringContainer : public nsACString_external
+{
+private:
+  void    *d1;
+  PRUint32 d2;
+  void    *d3;
+
+public:
+  nsCStringContainer() {} // MSVC6 needs this
+};
+
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Below we define a number of inlined helper classes that make the frozen
+ * string API easier to use.
+ */
+
+#ifndef MOZILLA_INTERNAL_API
+#include "nsDebug.h"
+
+/**
+ * Rename symbols to avoid conflicting with internal versions.
+ */
+#define nsString                       nsString_external
+#define nsCString                      nsCString_external
+#define nsDependentString              nsDependentString_external
+#define nsDependentCString             nsDependentCString_external
+#define NS_ConvertASCIItoUTF16         NS_ConvertASCIItoUTF16_external
+#define NS_ConvertUTF8toUTF16          NS_ConvertUTF8toUTF16_external
+#define NS_ConvertUTF16toUTF8          NS_ConvertUTF16toUTF8_external
+#define NS_LossyConvertUTF16toASCII    NS_LossyConvertUTF16toASCII_external
+#define nsGetterCopies                 nsGetterCopies_external
+#define nsCGetterCopies                nsCGetterCopies_external
+#define nsDependentSubstring           nsDependentSubstring_external
+#define nsDependentCSubstring          nsDependentCSubstring_external
+
+/**
+ * basic strings
+ */
+
+class nsString : public nsStringContainer
+{
+public:
+  typedef nsString         self_type;
+  typedef nsAString        abstract_string_type;
+
+  nsString()
+  {
+    NS_StringContainerInit(*this);
+  }
+
+  nsString(const self_type& aString)
+  {
+    NS_StringContainerInit(*this);
+    NS_StringCopy(*this, aString);
+  }
+
+  explicit
+  nsString(const abstract_string_type& aReadable)
+  {
+    NS_StringContainerInit(*this);
+    NS_StringCopy(*this, aReadable);
+  }
+
+  explicit
+  nsString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
+  {
+    NS_StringContainerInit2(*this, aData, aLength, 0);
+  }
+  
+  ~nsString()
+  {
+    NS_StringContainerFinish(*this);
+  }
+
+  const char_type* get() const
+  {
+    const char_type* data;
+    NS_StringGetData(*this, &data);
+    return data;
+  }
+  
+  self_type& operator=(const self_type& aString)              { Assign(aString);   return *this; }
+  self_type& operator=(const abstract_string_type& aReadable) { Assign(aReadable); return *this; }
+  self_type& operator=(const char_type* aPtr)                 { Assign(aPtr);      return *this; }
+  self_type& operator=(char_type aChar)                       { Assign(aChar);     return *this; }
+
+  void Adopt(const char_type *aData, size_type aLength = PR_UINT32_MAX)
+  {
+    NS_StringContainerFinish(*this);
+    NS_StringContainerInit2(*this, aData, aLength,
+                            NS_STRING_CONTAINER_INIT_ADOPT);
+  }
+
+protected:
+  
+  nsString(const char_type* aData, size_type aLength, PRUint32 aFlags)
+  {
+    NS_StringContainerInit2(*this, aData, aLength, aFlags);
+  }
+};
+
+class nsCString : public nsCStringContainer
+{
+public:
+  typedef nsCString        self_type;
+  typedef nsACString       abstract_string_type;
+
+  nsCString()
+  {
+    NS_CStringContainerInit(*this);
+  }
+
+  nsCString(const self_type& aString)
+  {
+    NS_CStringContainerInit(*this);
+    NS_CStringCopy(*this, aString);
+  }
+
+  explicit
+  nsCString(const abstract_string_type& aReadable)
+  {
+    NS_CStringContainerInit(*this);
+    NS_CStringCopy(*this, aReadable);
+  }
+
+  explicit
+  nsCString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
+  {
+    NS_CStringContainerInit(*this);
+    NS_CStringSetData(*this, aData, aLength);
+  }
+  
+  ~nsCString()
+  {
+    NS_CStringContainerFinish(*this);
+  }
+
+  const char_type* get() const
+  {
+    const char_type* data;
+    NS_CStringGetData(*this, &data);
+    return data;
+  }
+  
+  self_type& operator=(const self_type& aString)              { Assign(aString);   return *this; }
+  self_type& operator=(const abstract_string_type& aReadable) { Assign(aReadable); return *this; }
+  self_type& operator=(const char_type* aPtr)                 { Assign(aPtr);      return *this; }
+  self_type& operator=(char_type aChar)                       { Assign(aChar);     return *this; }
+
+  void Adopt(const char_type *aData, size_type aLength = PR_UINT32_MAX)
+  {
+    NS_CStringContainerFinish(*this);
+    NS_CStringContainerInit2(*this, aData, aLength,
+                             NS_CSTRING_CONTAINER_INIT_ADOPT);
+  }
+
+protected:
+  
+  nsCString(const char_type* aData, size_type aLength, PRUint32 aFlags)
+  {
+    NS_CStringContainerInit2(*this, aData, aLength, aFlags);
+  }
+};
+
+
+/**
+ * dependent strings
+ */
+
+class nsDependentString : public nsString
+{
+public:
+  typedef nsDependentString         self_type;
+
+  nsDependentString() {}
+
+  explicit
+  nsDependentString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
+    : nsString(aData, aLength, NS_CSTRING_CONTAINER_INIT_DEPEND)
+  {}
+
+  void Rebind(const char_type* aData, size_type aLength = PR_UINT32_MAX)
+  {
+    NS_StringContainerFinish(*this);
+    NS_StringContainerInit2(*this, aData, aLength,
+                            NS_STRING_CONTAINER_INIT_DEPEND);
+  }
+  
+private:
+  self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
+};
+
+class nsDependentCString : public nsCString
+{
+public:
+  typedef nsDependentCString        self_type;
+
+  nsDependentCString() {}
+
+  explicit
+  nsDependentCString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
+    : nsCString(aData, aLength, NS_CSTRING_CONTAINER_INIT_DEPEND)
+  {}
+
+  void Rebind(const char_type* aData, size_type aLength = PR_UINT32_MAX)
+  {
+    NS_CStringContainerFinish(*this);
+    NS_CStringContainerInit2(*this, aData, aLength,
+                             NS_CSTRING_CONTAINER_INIT_DEPEND);
+  }
+  
+private:
+  self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
+};
+
+
+/**
+ * conversion classes
+ */
+
+class NS_ConvertASCIItoUTF16 : public nsString
+{
+public:
+  typedef NS_ConvertASCIItoUTF16    self_type;
+
+  explicit
+  NS_ConvertASCIItoUTF16(const nsACString& aStr)
+  {
+    NS_CStringToUTF16(aStr, NS_CSTRING_ENCODING_ASCII, *this);
+  }
+
+  explicit
+  NS_ConvertASCIItoUTF16(const char* aData, PRUint32 aLength = PR_UINT32_MAX)
+  {
+    NS_CStringToUTF16(nsDependentCString(aData, aLength),
+                      NS_CSTRING_ENCODING_ASCII, *this);
+  }
+
+private:
+  self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
+};
+
+class NS_ConvertUTF8toUTF16 : public nsString
+{
+public:
+  typedef NS_ConvertUTF8toUTF16    self_type;
+
+  explicit
+  NS_ConvertUTF8toUTF16(const nsACString& aStr)
+  {
+    NS_CStringToUTF16(aStr, NS_CSTRING_ENCODING_UTF8, *this);
+  }
+
+  explicit
+  NS_ConvertUTF8toUTF16(const char* aData, PRUint32 aLength = PR_UINT32_MAX)
+  {
+    NS_CStringToUTF16(nsDependentCString(aData, aLength),
+                      NS_CSTRING_ENCODING_UTF8, *this);
+  }
+
+private:
+  self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
+};
+
+class NS_ConvertUTF16toUTF8 : public nsCString
+{
+public:
+  typedef NS_ConvertUTF16toUTF8    self_type;
+
+  explicit
+  NS_ConvertUTF16toUTF8(const nsAString& aStr)
+  {
+    NS_UTF16ToCString(aStr, NS_CSTRING_ENCODING_UTF8, *this);
+  }
+
+  explicit
+  NS_ConvertUTF16toUTF8(const PRUnichar* aData, PRUint32 aLength = PR_UINT32_MAX)
+  {
+    NS_UTF16ToCString(nsDependentString(aData, aLength),
+                      NS_CSTRING_ENCODING_UTF8, *this);
+  }
+
+private:
+  self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
+};
+
+class NS_LossyConvertUTF16toASCII : public nsCString
+{
+public:
+  typedef NS_LossyConvertUTF16toASCII    self_type;
+
+  explicit
+  NS_LossyConvertUTF16toASCII(const nsAString& aStr)
+  {
+    NS_UTF16ToCString(aStr, NS_CSTRING_ENCODING_ASCII, *this);
+  }
+
+  explicit
+  NS_LossyConvertUTF16toASCII(const PRUnichar* aData, PRUint32 aLength = PR_UINT32_MAX)
+  {
+    NS_UTF16ToCString(nsDependentString(aData, aLength),
+                      NS_CSTRING_ENCODING_ASCII, *this);
+  }
+
+private:
+  self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
+};
+
+
+/**
+ * literal strings
+ *
+ * NOTE: HAVE_CPP_2BYTE_WCHAR_T may be automatically defined for some platforms
+ * in nscore.h.  On other platforms, it may be defined in xpcom-config.h.
+ * Under GCC, this define should only be set if compiling with -fshort-wchar.
+ */
+
+#ifdef HAVE_CPP_2BYTE_WCHAR_T
+  #define NS_LL(s)                                L##s
+  #define NS_MULTILINE_LITERAL_STRING(s)          nsDependentString(NS_REINTERPRET_CAST(const nsAString::char_type*, s), PRUint32((sizeof(s)/sizeof(wchar_t))-1))
+  #define NS_MULTILINE_LITERAL_STRING_INIT(n,s)   n(NS_REINTERPRET_CAST(const nsAString::char_type*, s), PRUint32((sizeof(s)/sizeof(wchar_t))-1))
+  #define NS_NAMED_MULTILINE_LITERAL_STRING(n,s)  const nsDependentString n(NS_REINTERPRET_CAST(const nsAString::char_type*, s), PRUint32((sizeof(s)/sizeof(wchar_t))-1))
+  typedef nsDependentString nsLiteralString;
+#else
+  #define NS_LL(s)                                s
+  #define NS_MULTILINE_LITERAL_STRING(s)          NS_ConvertASCIItoUTF16(s, PRUint32(sizeof(s)-1))
+  #define NS_MULTILINE_LITERAL_STRING_INIT(n,s)   n(s, PRUint32(sizeof(s)-1))
+  #define NS_NAMED_MULTILINE_LITERAL_STRING(n,s)  const NS_ConvertASCIItoUTF16 n(s, PRUint32(sizeof(s)-1))
+  typedef NS_ConvertASCIItoUTF16 nsLiteralString;
+#endif
+
+/*
+ * Macro arguments used in concatenation or stringification won't be expanded.
+ * Therefore, in order for |NS_L(FOO)| to work as expected (which is to expand
+ * |FOO| before doing whatever |NS_L| needs to do to it) a helper macro needs
+ * to be inserted in between to allow the macro argument to expand.
+ * See "3.10.6 Separate Expansion of Macro Arguments" of the CPP manual for a
+ * more accurate and precise explanation.
+ */
+
+#define NS_L(s)                                   NS_LL(s)
+
+#define NS_LITERAL_STRING(s)                      NS_STATIC_CAST(const nsString&, NS_MULTILINE_LITERAL_STRING(NS_LL(s)))
+#define NS_LITERAL_STRING_INIT(n,s)               NS_MULTILINE_LITERAL_STRING_INIT(n, NS_LL(s))
+#define NS_NAMED_LITERAL_STRING(n,s)              NS_NAMED_MULTILINE_LITERAL_STRING(n, NS_LL(s))
+
+#define NS_LITERAL_CSTRING(s)                     NS_STATIC_CAST(const nsDependentCString&, nsDependentCString(s, PRUint32(sizeof(s)-1)))
+#define NS_LITERAL_CSTRING_INIT(n,s)              n(s, PRUint32(sizeof(s)-1))
+#define NS_NAMED_LITERAL_CSTRING(n,s)             const nsDependentCString n(s, PRUint32(sizeof(s)-1))
+
+typedef nsDependentCString nsLiteralCString;
+
+
+/**
+ * getter_Copies support
+ *
+ *    NS_IMETHOD GetBlah(PRUnichar**);
+ *
+ *    void some_function()
+ *    {
+ *      nsString blah;
+ *      GetBlah(getter_Copies(blah));
+ *      // ...
+ *    }
+ */
+
+class nsGetterCopies
+{
+public:
+  typedef PRUnichar char_type;
+
+  nsGetterCopies(nsString& aStr)
+    : mString(aStr), mData(nsnull)
+  {}
+
+  ~nsGetterCopies()
+  {
+    mString.Adopt(mData);
+  }
+
+  operator char_type**()
+  {
+    return &mData;
+  }
+
+private:
+  nsString&  mString;
+  char_type* mData;
+};
+
+inline nsGetterCopies
+getter_Copies(nsString& aString)
+{
+  return nsGetterCopies(aString);
+}
+
+class nsCGetterCopies
+{
+public:
+  typedef char char_type;
+
+  nsCGetterCopies(nsCString& aStr)
+    : mString(aStr), mData(nsnull)
+  {}
+
+  ~nsCGetterCopies()
+  {
+    mString.Adopt(mData);
+  }
+
+  operator char_type**()
+  {
+    return &mData;
+  }
+
+private:
+  nsCString& mString;
+  char_type* mData;
+};
+
+inline nsCGetterCopies
+getter_Copies(nsCString& aString)
+{
+  return nsCGetterCopies(aString);
+}
+
+
+/**
+* substrings
+*/
+
+class nsDependentSubstring : public nsStringContainer
+{
+public:
+  typedef nsDependentSubstring self_type;
+  typedef nsAString            abstract_string_type;
+
+  ~nsDependentSubstring()
+  {
+    NS_StringContainerFinish(*this);
+  }
+
+  nsDependentSubstring()
+  {
+    NS_StringContainerInit(*this);
+  }
+
+  nsDependentSubstring(const char_type *aStart, PRUint32 aLength)
+  {
+    NS_StringContainerInit2(*this, aStart, aLength,
+                            NS_STRING_CONTAINER_INIT_DEPEND |
+                            NS_STRING_CONTAINER_INIT_SUBSTRING);
+  }
+
+  nsDependentSubstring(const abstract_string_type& aStr,
+                       PRUint32 aStartPos)
+  {
+    const PRUnichar* data;
+    PRUint32 len = NS_StringGetData(aStr, &data);
+    NS_StringContainerInit2(*this, data + aStartPos, len - aStartPos,
+                            NS_STRING_CONTAINER_INIT_DEPEND |
+                            NS_STRING_CONTAINER_INIT_SUBSTRING);
+  }
+
+  nsDependentSubstring(const abstract_string_type& aStr,
+                       PRUint32 aStartPos, PRUint32 aLength)
+  {
+    const PRUnichar* data;
+#ifdef DEBUG
+    PRUint32 len =
+#endif
+    NS_StringGetData(aStr, &data);
+    NS_ASSERTION(aStartPos + aLength <= len, "bad length");
+    NS_StringContainerInit2(*this, data + aStartPos, aLength,
+                            NS_STRING_CONTAINER_INIT_DEPEND |
+                            NS_STRING_CONTAINER_INIT_SUBSTRING);
+  }
+
+  void Rebind(const char_type *aStart, PRUint32 aLength)
+  {
+    NS_StringContainerFinish(*this);
+    NS_StringContainerInit2(*this, aStart, aLength,
+                            NS_STRING_CONTAINER_INIT_DEPEND |
+                            NS_STRING_CONTAINER_INIT_SUBSTRING);
+  }
+
+private:
+  self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
+};
+
+class nsDependentCSubstring : public nsCStringContainer
+{
+public:
+  typedef nsDependentCSubstring self_type;
+  typedef nsACString            abstract_string_type;
+
+  ~nsDependentCSubstring()
+  {
+    NS_CStringContainerFinish(*this);
+  }
+
+  nsDependentCSubstring()
+  {
+    NS_CStringContainerInit(*this);
+  }
+
+  nsDependentCSubstring(const char_type *aStart, PRUint32 aLength)
+  {
+    NS_CStringContainerInit2(*this, aStart, aLength,
+                             NS_CSTRING_CONTAINER_INIT_DEPEND |
+                             NS_CSTRING_CONTAINER_INIT_SUBSTRING);
+  }
+
+  nsDependentCSubstring(const abstract_string_type& aStr,
+                        PRUint32 aStartPos)
+  {
+    const char* data;
+    PRUint32 len = NS_CStringGetData(aStr, &data);
+    NS_CStringContainerInit2(*this, data + aStartPos, len - aStartPos,
+                             NS_CSTRING_CONTAINER_INIT_DEPEND |
+                             NS_CSTRING_CONTAINER_INIT_SUBSTRING);
+  }
+
+  nsDependentCSubstring(const abstract_string_type& aStr,
+                        PRUint32 aStartPos, PRUint32 aLength)
+  {
+    const char* data;
+#ifdef DEBUG
+    PRUint32 len =
+#endif
+    NS_CStringGetData(aStr, &data);
+    NS_ASSERTION(aStartPos + aLength <= len, "bad length");
+    NS_CStringContainerInit2(*this, data + aStartPos, aLength,
+                             NS_CSTRING_CONTAINER_INIT_DEPEND |
+                             NS_CSTRING_CONTAINER_INIT_SUBSTRING);
+  }
+
+  void Rebind(const char_type *aStart, PRUint32 aLength)
+  {
+    NS_CStringContainerFinish(*this);
+    NS_CStringContainerInit2(*this, aStart, aLength,
+                             NS_CSTRING_CONTAINER_INIT_DEPEND |
+                             NS_CSTRING_CONTAINER_INIT_SUBSTRING);
+  }
+
+private:
+  self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
+};
+
+
+/**
+ * Various nsDependentC?Substring constructor functions
+ */
+
+// PRUnichar
+inline
+const nsDependentSubstring
+Substring( const nsAString& str, PRUint32 startPos )
+{
+  return nsDependentSubstring(str, startPos);
+}
+
+inline
+const nsDependentSubstring
+Substring( const nsAString& str, PRUint32 startPos, PRUint32 length )
+{
+  return nsDependentSubstring(str, startPos, length);
+}
+
+inline
+const nsDependentSubstring
+Substring( const PRUnichar* start, const PRUnichar* end )
+{
+  return nsDependentSubstring(start, end - start);
+}
+
+inline
+const nsDependentSubstring
+Substring( const PRUnichar* start, PRUint32 length )
+{
+  return nsDependentSubstring(start, length);
+}
+
+inline
+const nsDependentSubstring
+StringHead( const nsAString& str, PRUint32 count )
+{
+  return nsDependentSubstring(str, 0, count);
+}
+
+inline
+const nsDependentSubstring
+StringTail( const nsAString& str, PRUint32 count )
+{
+  return nsDependentSubstring(str, str.Length() - count, count);
+}
+
+// char
+inline
+const nsDependentCSubstring
+Substring( const nsACString& str, PRUint32 startPos )
+{
+  return nsDependentCSubstring(str, startPos);
+}
+
+inline
+const nsDependentCSubstring
+Substring( const nsACString& str, PRUint32 startPos, PRUint32 length )
+{
+  return nsDependentCSubstring(str, startPos, length);
+}
+
+inline
+const nsDependentCSubstring
+Substring( const char* start, const char* end )
+{
+  return nsDependentCSubstring(start, end - start);
+}
+
+inline
+const nsDependentCSubstring
+Substring( const char* start, PRUint32 length )
+{
+  return nsDependentCSubstring(start, length);
+}
+
+inline
+const nsDependentCSubstring
+StringHead( const nsACString& str, PRUint32 count )
+{
+  return nsDependentCSubstring(str, 0, count);
+}
+
+inline
+const nsDependentCSubstring
+StringTail( const nsACString& str, PRUint32 count )
+{
+  return nsDependentCSubstring(str, str.Length() - count, count);
+}
+
+
+/*
+ * Canonical empty strings
+ */
+
+#define EmptyCString() nsCString()
+#define EmptyString() nsString()
+
+#endif // MOZILLA_INTERNAL_API
+
+#endif // nsStringAPI_h__