nsStringAPI.h
上传用户:goldcmy89
上传日期:2017-12-03
资源大小:2246k
文件大小:56k
源码类别:

PlugIns编程

开发平台:

Visual C++

  1. /* vim:set ts=2 sw=2 et cindent: */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is Mozilla.
  16.  *
  17.  * The Initial Developer of the Original Code is IBM Corporation.
  18.  * Portions created by IBM Corporation are Copyright (C) 2003
  19.  * IBM Corporation.  All Rights Reserved.
  20.  *
  21.  * Contributor(s):
  22.  *   Darin Fisher <darin@meer.net>
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37. #ifndef nsStringAPI_h__
  38. #define nsStringAPI_h__
  39. #include <string.h>
  40. /**
  41.  * nsStringAPI.h
  42.  *
  43.  * This file describes a minimal API for working with XPCOM's abstract
  44.  * string classes.  It divorces the consumer from having any run-time
  45.  * dependency on the implementation details of the abstract string types.
  46.  */
  47. // Map frozen functions to private symbol names if not using strict API.
  48. #ifdef MOZILLA_INTERNAL_API
  49. # define NS_StringContainerInit           NS_StringContainerInit_P
  50. # define NS_StringContainerInit2          NS_StringContainerInit2_P
  51. # define NS_StringContainerFinish         NS_StringContainerFinish_P
  52. # define NS_StringGetData                 NS_StringGetData_P
  53. # define NS_StringGetMutableData          NS_StringGetMutableData_P
  54. # define NS_StringCloneData               NS_StringCloneData_P
  55. # define NS_StringSetData                 NS_StringSetData_P
  56. # define NS_StringSetDataRange            NS_StringSetDataRange_P
  57. # define NS_StringCopy                    NS_StringCopy_P
  58. # define NS_CStringContainerInit          NS_CStringContainerInit_P
  59. # define NS_CStringContainerInit2         NS_CStringContainerInit2_P
  60. # define NS_CStringContainerFinish        NS_CStringContainerFinish_P
  61. # define NS_CStringGetData                NS_CStringGetData_P
  62. # define NS_CStringGetMutableData         NS_CStringGetMutableData_P
  63. # define NS_CStringCloneData              NS_CStringCloneData_P
  64. # define NS_CStringSetData                NS_CStringSetData_P
  65. # define NS_CStringSetDataRange           NS_CStringSetDataRange_P
  66. # define NS_CStringCopy                   NS_CStringCopy_P
  67. # define NS_CStringToUTF16                NS_CStringToUTF16_P
  68. # define NS_UTF16ToCString                NS_UTF16ToCString_P
  69. #endif
  70. #include "nscore.h"
  71. #if defined( XPCOM_GLUE )
  72. #define NS_STRINGAPI(type) extern "C" NS_HIDDEN_(type)
  73. #elif defined( _IMPL_NS_STRINGAPI )
  74. #define NS_STRINGAPI(type) extern "C" NS_EXPORT type
  75. #else
  76. #define NS_STRINGAPI(type) extern "C" NS_IMPORT type
  77. #endif
  78. /* The base string types */
  79. class nsAString;
  80. class nsACString;
  81. /* ------------------------------------------------------------------------- */
  82. /**
  83.  * nsStringContainer
  84.  *
  85.  * This is an opaque data type that is large enough to hold the canonical
  86.  * implementation of nsAString.  The binary structure of this class is an
  87.  * implementation detail.
  88.  *
  89.  * The string data stored in a string container is always single fragment
  90.  * and may be null-terminated depending on how it is initialized.
  91.  *
  92.  * Typically, string containers are allocated on the stack for temporary
  93.  * use.  However, they can also be malloc'd if necessary.  In either case,
  94.  * a string container is not useful until it has been initialized with a
  95.  * call to NS_StringContainerInit.  The following example shows how to use
  96.  * a string container to call a function that takes a |nsAString &| out-param.
  97.  *
  98.  *   NS_METHOD GetBlah(nsAString &aBlah);
  99.  *
  100.  *   nsresult MyCode()
  101.  *   {
  102.  *     nsresult rv;
  103.  *
  104.  *     nsStringContainer sc;
  105.  *     rv = NS_StringContainerInit(sc);
  106.  *     if (NS_FAILED(rv))
  107.  *       return rv;
  108.  *
  109.  *     rv = GetBlah(sc);
  110.  *     if (NS_SUCCEEDED(rv))
  111.  *     {
  112.  *       const PRUnichar *data;
  113.  *       NS_StringGetData(sc, &data);
  114.  *       //
  115.  *       // |data| now points to the result of the GetBlah function
  116.  *       //
  117.  *     }
  118.  *
  119.  *     NS_StringContainerFinish(sc);
  120.  *     return rv;
  121.  *   }
  122.  *
  123.  * The following example show how to use a string container to pass a string
  124.  * parameter to a function taking a |const nsAString &| in-param.
  125.  *
  126.  *   NS_METHOD SetBlah(const nsAString &aBlah);
  127.  *
  128.  *   nsresult MyCode()
  129.  *   {
  130.  *     nsresult rv;
  131.  *
  132.  *     nsStringContainer sc;
  133.  *     rv = NS_StringContainerInit(sc);
  134.  *     if (NS_FAILED(rv))
  135.  *       return rv;
  136.  *
  137.  *     const PRUnichar kData[] = {'x','y','z',''};
  138.  *     rv = NS_StringSetData(sc, kData, sizeof(kData)/2 - 1);
  139.  *     if (NS_SUCCEEDED(rv))
  140.  *       rv = SetBlah(sc);
  141.  *
  142.  *     NS_StringContainerFinish(sc);
  143.  *     return rv;
  144.  *   }
  145.  */
  146. class nsStringContainer;
  147. /**
  148.  * Flags that may be OR'd together to pass to NS_StringContainerInit2:
  149.  */
  150. enum {
  151.   /* Data passed into NS_StringContainerInit2 is not copied; instead, the
  152.    * string references the passed in data pointer directly.  The caller must
  153.    * ensure that the data is valid for the lifetime of the string container.
  154.    * This flag should not be combined with NS_STRING_CONTAINER_INIT_ADOPT. */
  155.   NS_STRING_CONTAINER_INIT_DEPEND    = (1 << 1),
  156.   /* Data passed into NS_StringContainerInit2 is not copied; instead, the
  157.    * string takes ownership over the data pointer.  The caller must have
  158.    * allocated the data array using the XPCOM memory allocator (nsMemory).
  159.    * This flag should not be combined with NS_STRING_CONTAINER_INIT_DEPEND. */
  160.   NS_STRING_CONTAINER_INIT_ADOPT     = (1 << 2),
  161.   /* Data passed into NS_StringContainerInit2 is a substring that is not
  162.    * null-terminated. */
  163.   NS_STRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
  164. };
  165. /**
  166.  * NS_StringContainerInit
  167.  *
  168.  * @param aContainer    string container reference
  169.  * @return              NS_OK if string container successfully initialized
  170.  *
  171.  * This function may allocate additional memory for aContainer.  When
  172.  * aContainer is no longer needed, NS_StringContainerFinish should be called.
  173.  *
  174.  * @status FROZEN
  175.  */
  176. NS_STRINGAPI(nsresult)
  177. NS_StringContainerInit(nsStringContainer &aContainer);
  178. /**
  179.  * NS_StringContainerInit2
  180.  *
  181.  * @param aContainer    string container reference
  182.  * @param aData         character buffer (may be null)
  183.  * @param aDataLength   number of characters stored at aData (may pass
  184.  *                      PR_UINT32_MAX if aData is null-terminated)
  185.  * @param aFlags        flags affecting how the string container is
  186.  *                      initialized.  this parameter is ignored when aData
  187.  *                      is null.  otherwise, if this parameter is 0, then
  188.  *                      aData is copied into the string.
  189.  *
  190.  * This function resembles NS_StringContainerInit but provides further
  191.  * options that permit more efficient memory usage.  When aContainer is
  192.  * no longer needed, NS_StringContainerFinish should be called.
  193.  *
  194.  * NOTE: NS_StringContainerInit2(container, nsnull, 0, 0) is equivalent to
  195.  * NS_StringContainerInit(container).
  196.  *
  197.  * @status FROZEN
  198.  */
  199. NS_STRINGAPI(nsresult)
  200. NS_StringContainerInit2
  201.   (nsStringContainer &aContainer, const PRUnichar *aData = nsnull,
  202.    PRUint32 aDataLength = PR_UINT32_MAX, PRUint32 aFlags = 0);
  203. /**
  204.  * NS_StringContainerFinish
  205.  *
  206.  * @param aContainer    string container reference
  207.  *
  208.  * This function frees any memory owned by aContainer.
  209.  *
  210.  * @status FROZEN
  211.  */
  212. NS_STRINGAPI(void)
  213. NS_StringContainerFinish(nsStringContainer &aContainer);
  214. /* ------------------------------------------------------------------------- */
  215. /**
  216.  * NS_StringGetData
  217.  *
  218.  * This function returns a const character pointer to the string's internal
  219.  * buffer, the length of the string, and a boolean value indicating whether
  220.  * or not the buffer is null-terminated.
  221.  *
  222.  * @param aStr          abstract string reference
  223.  * @param aData         out param that will hold the address of aStr's
  224.  *                      internal buffer
  225.  * @param aTerminated   if non-null, this out param will be set to indicate
  226.  *                      whether or not aStr's internal buffer is null-
  227.  *                      terminated
  228.  * @return              length of aStr's internal buffer
  229.  *
  230.  * @status FROZEN
  231.  */
  232. NS_STRINGAPI(PRUint32)
  233. NS_StringGetData
  234.   (const nsAString &aStr, const PRUnichar **aData,
  235.    PRBool *aTerminated = nsnull);
  236. /**
  237.  * NS_StringGetMutableData
  238.  *
  239.  * This function provides mutable access to a string's internal buffer.  It
  240.  * returns a pointer to an array of characters that may be modified.  The
  241.  * returned pointer remains valid until the string object is passed to some
  242.  * other string function.
  243.  *
  244.  * Optionally, this function may be used to resize the string's internal
  245.  * buffer.  The aDataLength parameter specifies the requested length of the
  246.  * string's internal buffer.  By passing some value other than PR_UINT32_MAX,
  247.  * the caller can request that the buffer be resized to the specified number of
  248.  * characters before returning.  The caller is not responsible for writing a
  249.  * null-terminator.
  250.  *
  251.  * @param aStr          abstract string reference
  252.  * @param aDataLength   number of characters to resize the string's internal
  253.  *                      buffer to or PR_UINT32_MAX if no resizing is needed
  254.  * @param aData         out param that upon return holds the address of aStr's
  255.  *                      internal buffer or null if the function failed
  256.  * @return              number of characters or zero if the function failed
  257.  *
  258.  * This function does not necessarily null-terminate aStr after resizing its
  259.  * internal buffer.  The behavior depends on the implementation of the abstract
  260.  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
  261.  * will be null-terminated by this function.
  262.  *
  263.  * @status FROZEN
  264.  */
  265. NS_STRINGAPI(PRUint32)
  266. NS_StringGetMutableData
  267.   (nsAString &aStr, PRUint32 aDataLength, PRUnichar **aData);
  268. /**
  269.  * NS_StringCloneData
  270.  *
  271.  * This function returns a null-terminated copy of the string's
  272.  * internal buffer.
  273.  *
  274.  * @param aStr          abstract string reference
  275.  * @return              null-terminated copy of the string's internal buffer
  276.  *                      (it must be free'd using using nsMemory::Free)
  277.  *
  278.  * @status FROZEN
  279.  */
  280. NS_STRINGAPI(PRUnichar *)
  281. NS_StringCloneData
  282.   (const nsAString &aStr);
  283. /**
  284.  * NS_StringSetData
  285.  *
  286.  * This function copies aData into aStr.
  287.  *
  288.  * @param aStr          abstract string reference
  289.  * @param aData         character buffer
  290.  * @param aDataLength   number of characters to copy from source string (pass
  291.  *                      PR_UINT32_MAX to copy until end of aData, designated by
  292.  *                      a null character)
  293.  * @return              NS_OK if function succeeded
  294.  *
  295.  * This function does not necessarily null-terminate aStr after copying data
  296.  * from aData.  The behavior depends on the implementation of the abstract
  297.  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
  298.  * will be null-terminated by this function.
  299.  *
  300.  * @status FROZEN
  301.  */
  302. NS_STRINGAPI(nsresult)
  303. NS_StringSetData
  304.   (nsAString &aStr, const PRUnichar *aData,
  305.    PRUint32 aDataLength = PR_UINT32_MAX);
  306. /**
  307.  * NS_StringSetDataRange
  308.  *
  309.  * This function copies aData into a section of aStr.  As a result it can be
  310.  * used to insert new characters into the string.
  311.  *
  312.  * @param aStr          abstract string reference
  313.  * @param aCutOffset    starting index where the string's existing data
  314.  *                      is to be overwritten (pass PR_UINT32_MAX to cause
  315.  *                      aData to be appended to the end of aStr, in which
  316.  *                      case the value of aCutLength is ignored).
  317.  * @param aCutLength    number of characters to overwrite starting at
  318.  *                      aCutOffset (pass PR_UINT32_MAX to overwrite until the
  319.  *                      end of aStr).
  320.  * @param aData         character buffer (pass null to cause this function
  321.  *                      to simply remove the "cut" range)
  322.  * @param aDataLength   number of characters to copy from source string (pass
  323.  *                      PR_UINT32_MAX to copy until end of aData, designated by
  324.  *                      a null character)
  325.  * @return              NS_OK if function succeeded
  326.  *
  327.  * This function does not necessarily null-terminate aStr after copying data
  328.  * from aData.  The behavior depends on the implementation of the abstract
  329.  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
  330.  * will be null-terminated by this function.
  331.  *
  332.  * @status FROZEN
  333.  */
  334. NS_STRINGAPI(nsresult)
  335. NS_StringSetDataRange
  336.   (nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
  337.    const PRUnichar *aData, PRUint32 aDataLength = PR_UINT32_MAX);
  338. /**
  339.  * NS_StringCopy
  340.  *
  341.  * This function makes aDestStr have the same value as aSrcStr.  It is
  342.  * provided as an optimization.
  343.  *
  344.  * @param aDestStr      abstract string reference to be modified
  345.  * @param aSrcStr       abstract string reference containing source string
  346.  * @return              NS_OK if function succeeded
  347.  *
  348.  * This function does not necessarily null-terminate aDestStr after copying
  349.  * data from aSrcStr.  The behavior depends on the implementation of the
  350.  * abstract string, aDestStr.  If aDestStr is a reference to a
  351.  * nsStringContainer, then its data will be null-terminated by this function.
  352.  *
  353.  * @status FROZEN
  354.  */
  355. NS_STRINGAPI(nsresult)
  356. NS_StringCopy
  357.   (nsAString &aDestStr, const nsAString &aSrcStr);
  358. /**
  359.  * NS_StringAppendData
  360.  *
  361.  * This function appends data to the existing value of aStr.
  362.  *
  363.  * @param aStr          abstract string reference to be modified
  364.  * @param aData         character buffer
  365.  * @param aDataLength   number of characters to append (pass PR_UINT32_MAX to
  366.  *                      append until a null-character is encountered)
  367.  * @return              NS_OK if function succeeded
  368.  *
  369.  * This function does not necessarily null-terminate aStr upon completion.
  370.  * The behavior depends on the implementation of the abstract string, aStr.
  371.  * If aStr is a reference to a nsStringContainer, then its data will be null-
  372.  * terminated by this function.
  373.  */
  374. inline NS_HIDDEN_(nsresult)
  375. NS_StringAppendData(nsAString &aStr, const PRUnichar *aData,
  376.                     PRUint32 aDataLength = PR_UINT32_MAX)
  377. {
  378.   return NS_StringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
  379. }
  380. /**
  381.  * NS_StringInsertData
  382.  *
  383.  * This function inserts data into the existing value of aStr at the specified
  384.  * offset.
  385.  *
  386.  * @param aStr          abstract string reference to be modified
  387.  * @param aOffset       specifies where in the string to insert aData
  388.  * @param aData         character buffer
  389.  * @param aDataLength   number of characters to append (pass PR_UINT32_MAX to
  390.  *                      append until a null-character is encountered)
  391.  * @return              NS_OK if function succeeded
  392.  *
  393.  * This function does not necessarily null-terminate aStr upon completion.
  394.  * The behavior depends on the implementation of the abstract string, aStr.
  395.  * If aStr is a reference to a nsStringContainer, then its data will be null-
  396.  * terminated by this function.
  397.  */
  398. inline NS_HIDDEN_(nsresult)
  399. NS_StringInsertData(nsAString &aStr, PRUint32 aOffset, const PRUnichar *aData,
  400.                     PRUint32 aDataLength = PR_UINT32_MAX)
  401. {
  402.   return NS_StringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
  403. }
  404. /**
  405.  * NS_StringCutData
  406.  *
  407.  * This function shortens the existing value of aStr, by removing characters
  408.  * at the specified offset.
  409.  *
  410.  * @param aStr          abstract string reference to be modified
  411.  * @param aCutOffset    specifies where in the string to insert aData
  412.  * @param aCutLength    number of characters to remove
  413.  * @return              NS_OK if function succeeded
  414.  */
  415. inline NS_HIDDEN_(nsresult)
  416. NS_StringCutData(nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
  417. {
  418.   return NS_StringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
  419. }
  420. /* ------------------------------------------------------------------------- */
  421. /**
  422.  * nsCStringContainer
  423.  *
  424.  * This is an opaque data type that is large enough to hold the canonical
  425.  * implementation of nsACString.  The binary structure of this class is an
  426.  * implementation detail.
  427.  *
  428.  * The string data stored in a string container is always single fragment
  429.  * and may be null-terminated depending on how it is initialized.
  430.  *
  431.  * @see nsStringContainer for use cases and further documentation.
  432.  */
  433. class nsCStringContainer;
  434. /**
  435.  * Flags that may be OR'd together to pass to NS_StringContainerInit2:
  436.  */
  437. enum {
  438.   /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
  439.    * string references the passed in data pointer directly.  The caller must
  440.    * ensure that the data is valid for the lifetime of the string container.
  441.    * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_ADOPT. */
  442.   NS_CSTRING_CONTAINER_INIT_DEPEND    = (1 << 1),
  443.   /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
  444.    * string takes ownership over the data pointer.  The caller must have
  445.    * allocated the data array using the XPCOM memory allocator (nsMemory).
  446.    * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_DEPEND. */
  447.   NS_CSTRING_CONTAINER_INIT_ADOPT     = (1 << 2),
  448.   /* Data passed into NS_CStringContainerInit2 is a substring that is not
  449.    * null-terminated. */
  450.   NS_CSTRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
  451. };
  452. /**
  453.  * NS_CStringContainerInit
  454.  *
  455.  * @param aContainer    string container reference
  456.  * @return              NS_OK if string container successfully initialized
  457.  *
  458.  * This function may allocate additional memory for aContainer.  When
  459.  * aContainer is no longer needed, NS_CStringContainerFinish should be called.
  460.  *
  461.  * @status FROZEN
  462.  */
  463. NS_STRINGAPI(nsresult)
  464. NS_CStringContainerInit(nsCStringContainer &aContainer);
  465. /**
  466.  * NS_CStringContainerInit2
  467.  *
  468.  * @param aContainer    string container reference
  469.  * @param aData         character buffer (may be null)
  470.  * @param aDataLength   number of characters stored at aData (may pass
  471.  *                      PR_UINT32_MAX if aData is null-terminated)
  472.  * @param aFlags        flags affecting how the string container is
  473.  *                      initialized.  this parameter is ignored when aData
  474.  *                      is null.  otherwise, if this parameter is 0, then
  475.  *                      aData is copied into the string.
  476.  *
  477.  * This function resembles NS_CStringContainerInit but provides further
  478.  * options that permit more efficient memory usage.  When aContainer is
  479.  * no longer needed, NS_CStringContainerFinish should be called.
  480.  *
  481.  * NOTE: NS_CStringContainerInit2(container, nsnull, 0, 0) is equivalent to
  482.  * NS_CStringContainerInit(container).
  483.  *
  484.  * @status FROZEN
  485.  */
  486. NS_STRINGAPI(nsresult)
  487. NS_CStringContainerInit2
  488.   (nsCStringContainer &aContainer, const char *aData = nsnull,
  489.    PRUint32 aDataLength = PR_UINT32_MAX, PRUint32 aFlags = 0);
  490. /**
  491.  * NS_CStringContainerFinish
  492.  *
  493.  * @param aContainer    string container reference
  494.  *
  495.  * This function frees any memory owned by aContainer.
  496.  *
  497.  * @status FROZEN
  498.  */
  499. NS_STRINGAPI(void)
  500. NS_CStringContainerFinish(nsCStringContainer &aContainer);
  501. /* ------------------------------------------------------------------------- */
  502. /**
  503.  * NS_CStringGetData
  504.  *
  505.  * This function returns a const character pointer to the string's internal
  506.  * buffer, the length of the string, and a boolean value indicating whether
  507.  * or not the buffer is null-terminated.
  508.  *
  509.  * @param aStr          abstract string reference
  510.  * @param aData         out param that will hold the address of aStr's
  511.  *                      internal buffer
  512.  * @param aTerminated   if non-null, this out param will be set to indicate
  513.  *                      whether or not aStr's internal buffer is null-
  514.  *                      terminated
  515.  * @return              length of aStr's internal buffer
  516.  *
  517.  * @status FROZEN
  518.  */
  519. NS_STRINGAPI(PRUint32)
  520. NS_CStringGetData
  521.   (const nsACString &aStr, const char **aData,
  522.    PRBool *aTerminated = nsnull);
  523. /**
  524.  * NS_CStringGetMutableData
  525.  *
  526.  * This function provides mutable access to a string's internal buffer.  It
  527.  * returns a pointer to an array of characters that may be modified.  The
  528.  * returned pointer remains valid until the string object is passed to some
  529.  * other string function.
  530.  *
  531.  * Optionally, this function may be used to resize the string's internal
  532.  * buffer.  The aDataLength parameter specifies the requested length of the
  533.  * string's internal buffer.  By passing some value other than PR_UINT32_MAX,
  534.  * the caller can request that the buffer be resized to the specified number of
  535.  * characters before returning.  The caller is not responsible for writing a
  536.  * null-terminator.
  537.  *
  538.  * @param aStr          abstract string reference
  539.  * @param aDataLength   number of characters to resize the string's internal
  540.  *                      buffer to or PR_UINT32_MAX if no resizing is needed
  541.  * @param aData         out param that upon return holds the address of aStr's
  542.  *                      internal buffer or null if the function failed
  543.  * @return              number of characters or zero if the function failed
  544.  *
  545.  * This function does not necessarily null-terminate aStr after resizing its
  546.  * internal buffer.  The behavior depends on the implementation of the abstract
  547.  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
  548.  * will be null-terminated by this function.
  549.  *
  550.  * @status FROZEN
  551.  */
  552. NS_STRINGAPI(PRUint32)
  553. NS_CStringGetMutableData
  554.   (nsACString &aStr, PRUint32 aDataLength, char **aData);
  555. /**
  556.  * NS_CStringCloneData
  557.  *
  558.  * This function returns a null-terminated copy of the string's
  559.  * internal buffer.
  560.  *
  561.  * @param aStr          abstract string reference
  562.  * @return              null-terminated copy of the string's internal buffer
  563.  *                      (it must be free'd using using nsMemory::Free)
  564.  *
  565.  * @status FROZEN
  566.  */
  567. NS_STRINGAPI(char *)
  568. NS_CStringCloneData
  569.   (const nsACString &aStr);
  570. /**
  571.  * NS_CStringSetData
  572.  *
  573.  * This function copies aData into aStr.
  574.  *
  575.  * @param aStr          abstract string reference
  576.  * @param aData         character buffer
  577.  * @param aDataLength   number of characters to copy from source string (pass
  578.  *                      PR_UINT32_MAX to copy until end of aData, designated by
  579.  *                      a null character)
  580.  * @return              NS_OK if function succeeded
  581.  *
  582.  * This function does not necessarily null-terminate aStr after copying data
  583.  * from aData.  The behavior depends on the implementation of the abstract
  584.  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
  585.  * will be null-terminated by this function.
  586.  *
  587.  * @status FROZEN
  588.  */
  589. NS_STRINGAPI(nsresult)
  590. NS_CStringSetData
  591.   (nsACString &aStr, const char *aData,
  592.    PRUint32 aDataLength = PR_UINT32_MAX);
  593. /**
  594.  * NS_CStringSetDataRange
  595.  *
  596.  * This function copies aData into a section of aStr.  As a result it can be
  597.  * used to insert new characters into the string.
  598.  *
  599.  * @param aStr          abstract string reference
  600.  * @param aCutOffset    starting index where the string's existing data
  601.  *                      is to be overwritten (pass PR_UINT32_MAX to cause
  602.  *                      aData to be appended to the end of aStr, in which
  603.  *                      case the value of aCutLength is ignored).
  604.  * @param aCutLength    number of characters to overwrite starting at
  605.  *                      aCutOffset (pass PR_UINT32_MAX to overwrite until the
  606.  *                      end of aStr).
  607.  * @param aData         character buffer (pass null to cause this function
  608.  *                      to simply remove the "cut" range)
  609.  * @param aDataLength   number of characters to copy from source string (pass
  610.  *                      PR_UINT32_MAX to copy until end of aData, designated by
  611.  *                      a null character)
  612.  * @return              NS_OK if function succeeded
  613.  *
  614.  * This function does not necessarily null-terminate aStr after copying data
  615.  * from aData.  The behavior depends on the implementation of the abstract
  616.  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
  617.  * will be null-terminated by this function.
  618.  *
  619.  * @status FROZEN
  620.  */
  621. NS_STRINGAPI(nsresult)
  622. NS_CStringSetDataRange
  623.   (nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
  624.    const char *aData, PRUint32 aDataLength = PR_UINT32_MAX);
  625. /**
  626.  * NS_CStringCopy
  627.  *
  628.  * This function makes aDestStr have the same value as aSrcStr.  It is
  629.  * provided as an optimization.
  630.  *
  631.  * @param aDestStr      abstract string reference to be modified
  632.  * @param aSrcStr       abstract string reference containing source string
  633.  * @return              NS_OK if function succeeded
  634.  *
  635.  * This function does not necessarily null-terminate aDestStr after copying
  636.  * data from aSrcStr.  The behavior depends on the implementation of the
  637.  * abstract string, aDestStr.  If aDestStr is a reference to a
  638.  * nsStringContainer, then its data will be null-terminated by this function.
  639.  *
  640.  * @status FROZEN
  641.  */
  642. NS_STRINGAPI(nsresult)
  643. NS_CStringCopy
  644.   (nsACString &aDestStr, const nsACString &aSrcStr);
  645. /**
  646.  * NS_CStringAppendData
  647.  *
  648.  * This function appends data to the existing value of aStr.
  649.  *
  650.  * @param aStr          abstract string reference to be modified
  651.  * @param aData         character buffer
  652.  * @param aDataLength   number of characters to append (pass PR_UINT32_MAX to
  653.  *                      append until a null-character is encountered)
  654.  * @return              NS_OK if function succeeded
  655.  *
  656.  * This function does not necessarily null-terminate aStr upon completion.
  657.  * The behavior depends on the implementation of the abstract string, aStr.
  658.  * If aStr is a reference to a nsStringContainer, then its data will be null-
  659.  * terminated by this function.
  660.  */
  661. inline NS_HIDDEN_(nsresult)
  662. NS_CStringAppendData(nsACString &aStr, const char *aData,
  663.                     PRUint32 aDataLength = PR_UINT32_MAX)
  664. {
  665.   return NS_CStringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
  666. }
  667. /**
  668.  * NS_CStringInsertData
  669.  *
  670.  * This function inserts data into the existing value of aStr at the specified
  671.  * offset.
  672.  *
  673.  * @param aStr          abstract string reference to be modified
  674.  * @param aOffset       specifies where in the string to insert aData
  675.  * @param aData         character buffer
  676.  * @param aDataLength   number of characters to append (pass PR_UINT32_MAX to
  677.  *                      append until a null-character is encountered)
  678.  * @return              NS_OK if function succeeded
  679.  *
  680.  * This function does not necessarily null-terminate aStr upon completion.
  681.  * The behavior depends on the implementation of the abstract string, aStr.
  682.  * If aStr is a reference to a nsStringContainer, then its data will be null-
  683.  * terminated by this function.
  684.  */
  685. inline NS_HIDDEN_(nsresult)
  686. NS_CStringInsertData(nsACString &aStr, PRUint32 aOffset, const char *aData,
  687.                     PRUint32 aDataLength = PR_UINT32_MAX)
  688. {
  689.   return NS_CStringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
  690. }
  691. /**
  692.  * NS_CStringCutData
  693.  *
  694.  * This function shortens the existing value of aStr, by removing characters
  695.  * at the specified offset.
  696.  *
  697.  * @param aStr          abstract string reference to be modified
  698.  * @param aCutOffset    specifies where in the string to insert aData
  699.  * @param aCutLength    number of characters to remove
  700.  * @return              NS_OK if function succeeded
  701.  */
  702. inline NS_HIDDEN_(nsresult)
  703. NS_CStringCutData(nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
  704. {
  705.   return NS_CStringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
  706. }
  707. /* ------------------------------------------------------------------------- */
  708. /**
  709.  * Encodings that can be used with the following conversion routines.
  710.  */
  711. enum nsCStringEncoding {
  712.   /* Conversion between ASCII and UTF-16 assumes that all bytes in the source
  713.    * string are 7-bit ASCII and can be inflated to UTF-16 by inserting null
  714.    * bytes.  Reverse conversion is done by truncating every other byte.  The
  715.    * conversion may result in loss and/or corruption of information if the
  716.    * strings do not strictly contain ASCII data. */
  717.   NS_CSTRING_ENCODING_ASCII = 0,
  718.   /* Conversion between UTF-8 and UTF-16 is non-lossy. */
  719.   NS_CSTRING_ENCODING_UTF8 = 1,
  720.   /* Conversion from UTF-16 to the native filesystem charset may result in a
  721.    * loss of information.  No attempt is made to protect against data loss in
  722.    * this case.  The native filesystem charset applies to strings passed to
  723.    * the "Native" method variants on nsIFile and nsILocalFile. */
  724.   NS_CSTRING_ENCODING_NATIVE_FILESYSTEM = 2
  725. };
  726. /**
  727.  * NS_CStringToUTF16
  728.  *
  729.  * This function converts the characters in a nsACString to an array of UTF-16
  730.  * characters, in the platform endianness.  The result is stored in a nsAString
  731.  * object.
  732.  *
  733.  * @param aSource       abstract string reference containing source string
  734.  * @param aSrcEncoding  character encoding of the source string
  735.  * @param aDest         abstract string reference to hold the result
  736.  *
  737.  * @status FROZEN
  738.  */
  739. NS_STRINGAPI(nsresult)
  740. NS_CStringToUTF16(const nsACString &aSource, nsCStringEncoding aSrcEncoding,
  741.                   nsAString &aDest);
  742. /**
  743.  * NS_UTF16ToCString
  744.  *
  745.  * This function converts the UTF-16 characters in a nsAString to a single-byte
  746.  * encoding.  The result is stored in a nsACString object.  In some cases this
  747.  * conversion may be lossy.  In such cases, the conversion may succeed with a
  748.  * return code indicating loss of information.  The exact behavior is not
  749.  * specified at this time.
  750.  *
  751.  * @param aSource       abstract string reference containing source string
  752.  * @param aDestEncoding character encoding of the resulting string
  753.  * @param aDest         abstract string reference to hold the result
  754.  *
  755.  * @status FROZEN
  756.  */
  757. NS_STRINGAPI(nsresult)
  758. NS_UTF16ToCString(const nsAString &aSource, nsCStringEncoding aDestEncoding,
  759.                   nsACString &aDest);
  760. /* ------------------------------------------------------------------------- */
  761. /**
  762.  * Below we define nsAString and nsACString.  The "_external" suffix is an
  763.  * implementation detail.  nsAString_external is the name of the external
  764.  * representation of nsAString from the point of view of the Mozilla codebase.
  765.  * To a user of this API, nsAString_external is exactly nsAString.
  766.  *
  767.  * These classes should be treated as abstract classes with unspecified
  768.  * structure.  The inline methods are provided as helper functions around the
  769.  * C-style API provided above.
  770.  *
  771.  * Do not try to mix these definitions of nsAString and nsACString with the
  772.  * internal definition of these classes from nsAString.h in the Mozilla tree.
  773.  */
  774. #ifndef MOZILLA_INTERNAL_API
  775. #define nsAString_external nsAString
  776. #define nsACString_external nsACString
  777. #endif
  778. class nsAString_external
  779. {
  780. #ifndef MOZILLA_INTERNAL_API
  781. public:
  782.   typedef PRUnichar             char_type;
  783.   typedef nsAString_external    self_type;
  784.   typedef PRUint32              size_type;
  785.   typedef PRUint32              index_type;
  786.   NS_HIDDEN_(const char_type*) BeginReading() const
  787.   {
  788.     const char_type *data;
  789.     NS_StringGetData(*this, &data);
  790.     return data;
  791.   }
  792.   NS_HIDDEN_(const char_type*) EndReading() const
  793.   {
  794.     const char_type *data;
  795.     PRUint32 len = NS_StringGetData(*this, &data);
  796.     return data + len;
  797.   }
  798.   NS_HIDDEN_(char_type*) BeginWriting()
  799.   {
  800.     char_type *data;
  801.     NS_StringGetMutableData(*this, PR_UINT32_MAX, &data);
  802.     return data;
  803.   }
  804.   NS_HIDDEN_(PRBool) SetLength(PRUint32 aLen)
  805.   {
  806.     char_type *data;
  807.     NS_StringGetMutableData(*this, aLen, &data);
  808.     return data != nsnull;
  809.   }
  810.   NS_HIDDEN_(size_type) Length() const
  811.   {
  812.     const char_type* data;
  813.     return NS_StringGetData(*this, &data);
  814.   }
  815.   NS_HIDDEN_(PRBool) IsEmpty() const
  816.   {
  817.     return Length() == 0;
  818.   }
  819.   NS_HIDDEN_(void) Assign(const self_type& aString)
  820.   {
  821.     NS_StringCopy(*this, aString);
  822.   }
  823.   NS_HIDDEN_(void) Assign(const char_type* aData, size_type aLength = PR_UINT32_MAX)
  824.   {
  825.     NS_StringSetData(*this, aData, aLength);
  826.   }
  827.   NS_HIDDEN_(void) Assign(char_type aChar)
  828.   {
  829.     NS_StringSetData(*this, &aChar, 1);
  830.   }
  831.   NS_HIDDEN_(self_type&) operator=(const self_type& aString) { Assign(aString);   return *this; }
  832.   NS_HIDDEN_(self_type&) operator=(const char_type* aPtr)    { Assign(aPtr);      return *this; }
  833.   NS_HIDDEN_(self_type&) operator=(char_type aChar)          { Assign(aChar);     return *this; }
  834.   NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const char_type* data, size_type length = size_type(-1) )
  835.   {
  836.     NS_StringSetDataRange(*this, cutStart, cutLength, data, length);
  837.   }
  838.   NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, char_type c )
  839.   {
  840.     Replace(cutStart, cutLength, &c, 1);
  841.   }
  842.   NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const self_type& readable )
  843.   {
  844.     const char_type* data;
  845.     PRUint32 dataLen = NS_StringGetData(readable, &data);
  846.     NS_StringSetDataRange(*this, cutStart, cutLength, data, dataLen);
  847.   }
  848.   NS_HIDDEN_(void) Append( char_type c )                                                              { Replace(size_type(-1), 0, c); }
  849.   NS_HIDDEN_(void) Append( const char_type* data, size_type length = size_type(-1) )                  { Replace(size_type(-1), 0, data, length); }
  850.   NS_HIDDEN_(void) Append( const self_type& readable )                                                { Replace(size_type(-1), 0, readable); }
  851.   NS_HIDDEN_(self_type&) operator+=( char_type c )                                                    { Append(c);        return *this; }
  852.   NS_HIDDEN_(self_type&) operator+=( const char_type* data )                                          { Append(data);     return *this; }
  853.   NS_HIDDEN_(self_type&) operator+=( const self_type& readable )                                      { Append(readable); return *this; }
  854.   NS_HIDDEN_(void) Insert( char_type c, index_type pos )                                              { Replace(pos, 0, c); }
  855.   NS_HIDDEN_(void) Insert( const char_type* data, index_type pos, size_type length = size_type(-1) )  { Replace(pos, 0, data, length); }
  856.   NS_HIDDEN_(void) Insert( const self_type& readable, index_type pos )                                { Replace(pos, 0, readable); }
  857.   NS_HIDDEN_(void) Cut( index_type cutStart, size_type cutLength )                                    { Replace(cutStart, cutLength, nsnull, 0); }
  858.   NS_HIDDEN_(PRBool) Equals( const self_type &other ) const {
  859.     const char_type *cself;
  860.     const char_type *cother;
  861.     PRUint32 selflen = NS_StringGetData(*this, &cself);
  862.     PRUint32 otherlen = NS_StringGetData(other, &cother);
  863.     if (selflen != otherlen)
  864.       return PR_FALSE;
  865.     return memcmp(cself, cother, selflen * sizeof(char_type)) == 0;
  866.   }
  867. #endif // MOZILLA_INTERNAL_API
  868. protected:
  869.   // Prevent people from allocating a nsAString directly.
  870.   ~nsAString_external() {}
  871. private:
  872.   void *v;
  873. };
  874. class nsACString_external
  875. {
  876. #ifndef MOZILLA_INTERNAL_API
  877. public:
  878.   typedef char                  char_type;
  879.   typedef nsACString_external   self_type;
  880.   typedef PRUint32              size_type;
  881.   typedef PRUint32              index_type;
  882.   NS_HIDDEN_(const char_type*) BeginReading() const
  883.   {
  884.     const char_type *data;
  885.     NS_CStringGetData(*this, &data);
  886.     return data;
  887.   }
  888.   NS_HIDDEN_(const char_type*) EndReading() const
  889.   {
  890.     const char_type *data;
  891.     PRUint32 len = NS_CStringGetData(*this, &data);
  892.     return data + len;
  893.   }
  894.   NS_HIDDEN_(char_type*) BeginWriting()
  895.   {
  896.     char_type *data;
  897.     NS_CStringGetMutableData(*this, PR_UINT32_MAX, &data);
  898.     return data;
  899.   }
  900.   NS_HIDDEN_(PRBool) SetLength(PRUint32 aLen)
  901.   {
  902.     char_type *data;
  903.     NS_CStringGetMutableData(*this, aLen, &data);
  904.     return data != nsnull;
  905.   }
  906.   NS_HIDDEN_(size_type) Length() const
  907.   {
  908.     const char_type* data;
  909.     return NS_CStringGetData(*this, &data);
  910.   }
  911.   NS_HIDDEN_(PRBool) IsEmpty() const
  912.   {
  913.     return Length() == 0;
  914.   }
  915.   NS_HIDDEN_(void) Assign(const self_type& aString)
  916.   {
  917.     NS_CStringCopy(*this, aString);
  918.   }
  919.   NS_HIDDEN_(void) Assign(const char_type* aData, size_type aLength = PR_UINT32_MAX)
  920.   {
  921.     NS_CStringSetData(*this, aData, aLength);
  922.   }
  923.   NS_HIDDEN_(void) Assign(char_type aChar)
  924.   {
  925.     NS_CStringSetData(*this, &aChar, 1);
  926.   }
  927.   NS_HIDDEN_(self_type&) operator=(const self_type& aString) { Assign(aString);   return *this; }
  928.   NS_HIDDEN_(self_type&) operator=(const char_type* aPtr)    { Assign(aPtr);      return *this; }
  929.   NS_HIDDEN_(self_type&) operator=(char_type aChar)          { Assign(aChar);     return *this; }
  930.   NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const char_type* data, size_type length = size_type(-1) )
  931.   {
  932.     NS_CStringSetDataRange(*this, cutStart, cutLength, data, length);
  933.   }
  934.   NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, char_type c )
  935.   {
  936.     Replace(cutStart, cutLength, &c, 1);
  937.   }
  938.   NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const self_type& readable )
  939.   {
  940.     const char_type* data;
  941.     PRUint32 dataLen = NS_CStringGetData(readable, &data);
  942.     NS_CStringSetDataRange(*this, cutStart, cutLength, data, dataLen);
  943.   }
  944.   NS_HIDDEN_(void) Append( char_type c )                                                              { Replace(size_type(-1), 0, c); }
  945.   NS_HIDDEN_(void) Append( const char_type* data, size_type length = size_type(-1) )                  { Replace(size_type(-1), 0, data, length); }
  946.   NS_HIDDEN_(void) Append( const self_type& readable )                                                { Replace(size_type(-1), 0, readable); }
  947.   NS_HIDDEN_(self_type&) operator+=( char_type c )                                                    { Append(c);        return *this; }
  948.   NS_HIDDEN_(self_type&) operator+=( const char_type* data )                                          { Append(data);     return *this; }
  949.   NS_HIDDEN_(self_type&) operator+=( const self_type& readable )                                      { Append(readable); return *this; }
  950.   NS_HIDDEN_(void) Insert( char_type c, index_type pos )                                              { Replace(pos, 0, c); }
  951.   NS_HIDDEN_(void) Insert( const char_type* data, index_type pos, size_type length = size_type(-1) )  { Replace(pos, 0, data, length); }
  952.   NS_HIDDEN_(void) Insert( const self_type& readable, index_type pos )                                { Replace(pos, 0, readable); }
  953.   NS_HIDDEN_(void) Cut( index_type cutStart, size_type cutLength )                                    { Replace(cutStart, cutLength, nsnull, 0); }
  954.   NS_HIDDEN_(PRBool) Equals( const self_type &other ) const {
  955.     const char_type *cself;
  956.     const char_type *cother;
  957.     PRUint32 selflen = NS_CStringGetData(*this, &cself);
  958.     PRUint32 otherlen = NS_CStringGetData(other, &cother);
  959.     if (selflen != otherlen)
  960.       return PR_FALSE;
  961.  
  962.     return memcmp(cself, cother, selflen * sizeof(char_type)) == 0;
  963.   }
  964. #endif // MOZILLA_INTERNAL_API
  965. protected:
  966.   // Prevent people from allocating a nsACString directly.
  967.   ~nsACString_external() {}
  968. private:
  969.   void *v;
  970. };
  971. /* ------------------------------------------------------------------------- */
  972. /**
  973.  * Below we define nsStringContainer and nsCStringContainer.  These classes
  974.  * have unspecified structure.  In most cases, your code should use
  975.  * nsEmbedString instead of these classes; however, if you prefer C-style
  976.  * programming, then look no further...
  977.  */
  978. class nsStringContainer : public nsAString_external
  979. {
  980. private:
  981.   void     *d1;
  982.   PRUint32  d2;
  983.   void     *d3;
  984. public:
  985.   nsStringContainer() {} // MSVC6 needs this
  986. };
  987. class nsCStringContainer : public nsACString_external
  988. {
  989. private:
  990.   void    *d1;
  991.   PRUint32 d2;
  992.   void    *d3;
  993. public:
  994.   nsCStringContainer() {} // MSVC6 needs this
  995. };
  996. /* ------------------------------------------------------------------------- */
  997. /**
  998.  * Below we define a number of inlined helper classes that make the frozen
  999.  * string API easier to use.
  1000.  */
  1001. #ifndef MOZILLA_INTERNAL_API
  1002. #include "nsDebug.h"
  1003. /**
  1004.  * Rename symbols to avoid conflicting with internal versions.
  1005.  */
  1006. #define nsString                       nsString_external
  1007. #define nsCString                      nsCString_external
  1008. #define nsDependentString              nsDependentString_external
  1009. #define nsDependentCString             nsDependentCString_external
  1010. #define NS_ConvertASCIItoUTF16         NS_ConvertASCIItoUTF16_external
  1011. #define NS_ConvertUTF8toUTF16          NS_ConvertUTF8toUTF16_external
  1012. #define NS_ConvertUTF16toUTF8          NS_ConvertUTF16toUTF8_external
  1013. #define NS_LossyConvertUTF16toASCII    NS_LossyConvertUTF16toASCII_external
  1014. #define nsGetterCopies                 nsGetterCopies_external
  1015. #define nsCGetterCopies                nsCGetterCopies_external
  1016. #define nsDependentSubstring           nsDependentSubstring_external
  1017. #define nsDependentCSubstring          nsDependentCSubstring_external
  1018. /**
  1019.  * basic strings
  1020.  */
  1021. class nsString : public nsStringContainer
  1022. {
  1023. public:
  1024.   typedef nsString         self_type;
  1025.   typedef nsAString        abstract_string_type;
  1026.   nsString()
  1027.   {
  1028.     NS_StringContainerInit(*this);
  1029.   }
  1030.   nsString(const self_type& aString)
  1031.   {
  1032.     NS_StringContainerInit(*this);
  1033.     NS_StringCopy(*this, aString);
  1034.   }
  1035.   explicit
  1036.   nsString(const abstract_string_type& aReadable)
  1037.   {
  1038.     NS_StringContainerInit(*this);
  1039.     NS_StringCopy(*this, aReadable);
  1040.   }
  1041.   explicit
  1042.   nsString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
  1043.   {
  1044.     NS_StringContainerInit2(*this, aData, aLength, 0);
  1045.   }
  1046.   
  1047.   ~nsString()
  1048.   {
  1049.     NS_StringContainerFinish(*this);
  1050.   }
  1051.   const char_type* get() const
  1052.   {
  1053.     const char_type* data;
  1054.     NS_StringGetData(*this, &data);
  1055.     return data;
  1056.   }
  1057.   
  1058.   self_type& operator=(const self_type& aString)              { Assign(aString);   return *this; }
  1059.   self_type& operator=(const abstract_string_type& aReadable) { Assign(aReadable); return *this; }
  1060.   self_type& operator=(const char_type* aPtr)                 { Assign(aPtr);      return *this; }
  1061.   self_type& operator=(char_type aChar)                       { Assign(aChar);     return *this; }
  1062.   void Adopt(const char_type *aData, size_type aLength = PR_UINT32_MAX)
  1063.   {
  1064.     NS_StringContainerFinish(*this);
  1065.     NS_StringContainerInit2(*this, aData, aLength,
  1066.                             NS_STRING_CONTAINER_INIT_ADOPT);
  1067.   }
  1068. protected:
  1069.   
  1070.   nsString(const char_type* aData, size_type aLength, PRUint32 aFlags)
  1071.   {
  1072.     NS_StringContainerInit2(*this, aData, aLength, aFlags);
  1073.   }
  1074. };
  1075. class nsCString : public nsCStringContainer
  1076. {
  1077. public:
  1078.   typedef nsCString        self_type;
  1079.   typedef nsACString       abstract_string_type;
  1080.   nsCString()
  1081.   {
  1082.     NS_CStringContainerInit(*this);
  1083.   }
  1084.   nsCString(const self_type& aString)
  1085.   {
  1086.     NS_CStringContainerInit(*this);
  1087.     NS_CStringCopy(*this, aString);
  1088.   }
  1089.   explicit
  1090.   nsCString(const abstract_string_type& aReadable)
  1091.   {
  1092.     NS_CStringContainerInit(*this);
  1093.     NS_CStringCopy(*this, aReadable);
  1094.   }
  1095.   explicit
  1096.   nsCString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
  1097.   {
  1098.     NS_CStringContainerInit(*this);
  1099.     NS_CStringSetData(*this, aData, aLength);
  1100.   }
  1101.   
  1102.   ~nsCString()
  1103.   {
  1104.     NS_CStringContainerFinish(*this);
  1105.   }
  1106.   const char_type* get() const
  1107.   {
  1108.     const char_type* data;
  1109.     NS_CStringGetData(*this, &data);
  1110.     return data;
  1111.   }
  1112.   
  1113.   self_type& operator=(const self_type& aString)              { Assign(aString);   return *this; }
  1114.   self_type& operator=(const abstract_string_type& aReadable) { Assign(aReadable); return *this; }
  1115.   self_type& operator=(const char_type* aPtr)                 { Assign(aPtr);      return *this; }
  1116.   self_type& operator=(char_type aChar)                       { Assign(aChar);     return *this; }
  1117.   void Adopt(const char_type *aData, size_type aLength = PR_UINT32_MAX)
  1118.   {
  1119.     NS_CStringContainerFinish(*this);
  1120.     NS_CStringContainerInit2(*this, aData, aLength,
  1121.                              NS_CSTRING_CONTAINER_INIT_ADOPT);
  1122.   }
  1123. protected:
  1124.   
  1125.   nsCString(const char_type* aData, size_type aLength, PRUint32 aFlags)
  1126.   {
  1127.     NS_CStringContainerInit2(*this, aData, aLength, aFlags);
  1128.   }
  1129. };
  1130. /**
  1131.  * dependent strings
  1132.  */
  1133. class nsDependentString : public nsString
  1134. {
  1135. public:
  1136.   typedef nsDependentString         self_type;
  1137.   nsDependentString() {}
  1138.   explicit
  1139.   nsDependentString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
  1140.     : nsString(aData, aLength, NS_CSTRING_CONTAINER_INIT_DEPEND)
  1141.   {}
  1142.   void Rebind(const char_type* aData, size_type aLength = PR_UINT32_MAX)
  1143.   {
  1144.     NS_StringContainerFinish(*this);
  1145.     NS_StringContainerInit2(*this, aData, aLength,
  1146.                             NS_STRING_CONTAINER_INIT_DEPEND);
  1147.   }
  1148.   
  1149. private:
  1150.   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
  1151. };
  1152. class nsDependentCString : public nsCString
  1153. {
  1154. public:
  1155.   typedef nsDependentCString        self_type;
  1156.   nsDependentCString() {}
  1157.   explicit
  1158.   nsDependentCString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
  1159.     : nsCString(aData, aLength, NS_CSTRING_CONTAINER_INIT_DEPEND)
  1160.   {}
  1161.   void Rebind(const char_type* aData, size_type aLength = PR_UINT32_MAX)
  1162.   {
  1163.     NS_CStringContainerFinish(*this);
  1164.     NS_CStringContainerInit2(*this, aData, aLength,
  1165.                              NS_CSTRING_CONTAINER_INIT_DEPEND);
  1166.   }
  1167.   
  1168. private:
  1169.   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
  1170. };
  1171. /**
  1172.  * conversion classes
  1173.  */
  1174. class NS_ConvertASCIItoUTF16 : public nsString
  1175. {
  1176. public:
  1177.   typedef NS_ConvertASCIItoUTF16    self_type;
  1178.   explicit
  1179.   NS_ConvertASCIItoUTF16(const nsACString& aStr)
  1180.   {
  1181.     NS_CStringToUTF16(aStr, NS_CSTRING_ENCODING_ASCII, *this);
  1182.   }
  1183.   explicit
  1184.   NS_ConvertASCIItoUTF16(const char* aData, PRUint32 aLength = PR_UINT32_MAX)
  1185.   {
  1186.     NS_CStringToUTF16(nsDependentCString(aData, aLength),
  1187.                       NS_CSTRING_ENCODING_ASCII, *this);
  1188.   }
  1189. private:
  1190.   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
  1191. };
  1192. class NS_ConvertUTF8toUTF16 : public nsString
  1193. {
  1194. public:
  1195.   typedef NS_ConvertUTF8toUTF16    self_type;
  1196.   explicit
  1197.   NS_ConvertUTF8toUTF16(const nsACString& aStr)
  1198.   {
  1199.     NS_CStringToUTF16(aStr, NS_CSTRING_ENCODING_UTF8, *this);
  1200.   }
  1201.   explicit
  1202.   NS_ConvertUTF8toUTF16(const char* aData, PRUint32 aLength = PR_UINT32_MAX)
  1203.   {
  1204.     NS_CStringToUTF16(nsDependentCString(aData, aLength),
  1205.                       NS_CSTRING_ENCODING_UTF8, *this);
  1206.   }
  1207. private:
  1208.   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
  1209. };
  1210. class NS_ConvertUTF16toUTF8 : public nsCString
  1211. {
  1212. public:
  1213.   typedef NS_ConvertUTF16toUTF8    self_type;
  1214.   explicit
  1215.   NS_ConvertUTF16toUTF8(const nsAString& aStr)
  1216.   {
  1217.     NS_UTF16ToCString(aStr, NS_CSTRING_ENCODING_UTF8, *this);
  1218.   }
  1219.   explicit
  1220.   NS_ConvertUTF16toUTF8(const PRUnichar* aData, PRUint32 aLength = PR_UINT32_MAX)
  1221.   {
  1222.     NS_UTF16ToCString(nsDependentString(aData, aLength),
  1223.                       NS_CSTRING_ENCODING_UTF8, *this);
  1224.   }
  1225. private:
  1226.   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
  1227. };
  1228. class NS_LossyConvertUTF16toASCII : public nsCString
  1229. {
  1230. public:
  1231.   typedef NS_LossyConvertUTF16toASCII    self_type;
  1232.   explicit
  1233.   NS_LossyConvertUTF16toASCII(const nsAString& aStr)
  1234.   {
  1235.     NS_UTF16ToCString(aStr, NS_CSTRING_ENCODING_ASCII, *this);
  1236.   }
  1237.   explicit
  1238.   NS_LossyConvertUTF16toASCII(const PRUnichar* aData, PRUint32 aLength = PR_UINT32_MAX)
  1239.   {
  1240.     NS_UTF16ToCString(nsDependentString(aData, aLength),
  1241.                       NS_CSTRING_ENCODING_ASCII, *this);
  1242.   }
  1243. private:
  1244.   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
  1245. };
  1246. /**
  1247.  * literal strings
  1248.  *
  1249.  * NOTE: HAVE_CPP_2BYTE_WCHAR_T may be automatically defined for some platforms
  1250.  * in nscore.h.  On other platforms, it may be defined in xpcom-config.h.
  1251.  * Under GCC, this define should only be set if compiling with -fshort-wchar.
  1252.  */
  1253. #ifdef HAVE_CPP_2BYTE_WCHAR_T
  1254.   #define NS_LL(s)                                L##s
  1255.   #define NS_MULTILINE_LITERAL_STRING(s)          nsDependentString(NS_REINTERPRET_CAST(const nsAString::char_type*, s), PRUint32((sizeof(s)/sizeof(wchar_t))-1))
  1256.   #define NS_MULTILINE_LITERAL_STRING_INIT(n,s)   n(NS_REINTERPRET_CAST(const nsAString::char_type*, s), PRUint32((sizeof(s)/sizeof(wchar_t))-1))
  1257.   #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))
  1258.   typedef nsDependentString nsLiteralString;
  1259. #else
  1260.   #define NS_LL(s)                                s
  1261.   #define NS_MULTILINE_LITERAL_STRING(s)          NS_ConvertASCIItoUTF16(s, PRUint32(sizeof(s)-1))
  1262.   #define NS_MULTILINE_LITERAL_STRING_INIT(n,s)   n(s, PRUint32(sizeof(s)-1))
  1263.   #define NS_NAMED_MULTILINE_LITERAL_STRING(n,s)  const NS_ConvertASCIItoUTF16 n(s, PRUint32(sizeof(s)-1))
  1264.   typedef NS_ConvertASCIItoUTF16 nsLiteralString;
  1265. #endif
  1266. /*
  1267.  * Macro arguments used in concatenation or stringification won't be expanded.
  1268.  * Therefore, in order for |NS_L(FOO)| to work as expected (which is to expand
  1269.  * |FOO| before doing whatever |NS_L| needs to do to it) a helper macro needs
  1270.  * to be inserted in between to allow the macro argument to expand.
  1271.  * See "3.10.6 Separate Expansion of Macro Arguments" of the CPP manual for a
  1272.  * more accurate and precise explanation.
  1273.  */
  1274. #define NS_L(s)                                   NS_LL(s)
  1275. #define NS_LITERAL_STRING(s)                      NS_STATIC_CAST(const nsString&, NS_MULTILINE_LITERAL_STRING(NS_LL(s)))
  1276. #define NS_LITERAL_STRING_INIT(n,s)               NS_MULTILINE_LITERAL_STRING_INIT(n, NS_LL(s))
  1277. #define NS_NAMED_LITERAL_STRING(n,s)              NS_NAMED_MULTILINE_LITERAL_STRING(n, NS_LL(s))
  1278. #define NS_LITERAL_CSTRING(s)                     NS_STATIC_CAST(const nsDependentCString&, nsDependentCString(s, PRUint32(sizeof(s)-1)))
  1279. #define NS_LITERAL_CSTRING_INIT(n,s)              n(s, PRUint32(sizeof(s)-1))
  1280. #define NS_NAMED_LITERAL_CSTRING(n,s)             const nsDependentCString n(s, PRUint32(sizeof(s)-1))
  1281. typedef nsDependentCString nsLiteralCString;
  1282. /**
  1283.  * getter_Copies support
  1284.  *
  1285.  *    NS_IMETHOD GetBlah(PRUnichar**);
  1286.  *
  1287.  *    void some_function()
  1288.  *    {
  1289.  *      nsString blah;
  1290.  *      GetBlah(getter_Copies(blah));
  1291.  *      // ...
  1292.  *    }
  1293.  */
  1294. class nsGetterCopies
  1295. {
  1296. public:
  1297.   typedef PRUnichar char_type;
  1298.   nsGetterCopies(nsString& aStr)
  1299.     : mString(aStr), mData(nsnull)
  1300.   {}
  1301.   ~nsGetterCopies()
  1302.   {
  1303.     mString.Adopt(mData);
  1304.   }
  1305.   operator char_type**()
  1306.   {
  1307.     return &mData;
  1308.   }
  1309. private:
  1310.   nsString&  mString;
  1311.   char_type* mData;
  1312. };
  1313. inline nsGetterCopies
  1314. getter_Copies(nsString& aString)
  1315. {
  1316.   return nsGetterCopies(aString);
  1317. }
  1318. class nsCGetterCopies
  1319. {
  1320. public:
  1321.   typedef char char_type;
  1322.   nsCGetterCopies(nsCString& aStr)
  1323.     : mString(aStr), mData(nsnull)
  1324.   {}
  1325.   ~nsCGetterCopies()
  1326.   {
  1327.     mString.Adopt(mData);
  1328.   }
  1329.   operator char_type**()
  1330.   {
  1331.     return &mData;
  1332.   }
  1333. private:
  1334.   nsCString& mString;
  1335.   char_type* mData;
  1336. };
  1337. inline nsCGetterCopies
  1338. getter_Copies(nsCString& aString)
  1339. {
  1340.   return nsCGetterCopies(aString);
  1341. }
  1342. /**
  1343. * substrings
  1344. */
  1345. class nsDependentSubstring : public nsStringContainer
  1346. {
  1347. public:
  1348.   typedef nsDependentSubstring self_type;
  1349.   typedef nsAString            abstract_string_type;
  1350.   ~nsDependentSubstring()
  1351.   {
  1352.     NS_StringContainerFinish(*this);
  1353.   }
  1354.   nsDependentSubstring()
  1355.   {
  1356.     NS_StringContainerInit(*this);
  1357.   }
  1358.   nsDependentSubstring(const char_type *aStart, PRUint32 aLength)
  1359.   {
  1360.     NS_StringContainerInit2(*this, aStart, aLength,
  1361.                             NS_STRING_CONTAINER_INIT_DEPEND |
  1362.                             NS_STRING_CONTAINER_INIT_SUBSTRING);
  1363.   }
  1364.   nsDependentSubstring(const abstract_string_type& aStr,
  1365.                        PRUint32 aStartPos)
  1366.   {
  1367.     const PRUnichar* data;
  1368.     PRUint32 len = NS_StringGetData(aStr, &data);
  1369.     NS_StringContainerInit2(*this, data + aStartPos, len - aStartPos,
  1370.                             NS_STRING_CONTAINER_INIT_DEPEND |
  1371.                             NS_STRING_CONTAINER_INIT_SUBSTRING);
  1372.   }
  1373.   nsDependentSubstring(const abstract_string_type& aStr,
  1374.                        PRUint32 aStartPos, PRUint32 aLength)
  1375.   {
  1376.     const PRUnichar* data;
  1377. #ifdef DEBUG
  1378.     PRUint32 len =
  1379. #endif
  1380.     NS_StringGetData(aStr, &data);
  1381.     NS_ASSERTION(aStartPos + aLength <= len, "bad length");
  1382.     NS_StringContainerInit2(*this, data + aStartPos, aLength,
  1383.                             NS_STRING_CONTAINER_INIT_DEPEND |
  1384.                             NS_STRING_CONTAINER_INIT_SUBSTRING);
  1385.   }
  1386.   void Rebind(const char_type *aStart, PRUint32 aLength)
  1387.   {
  1388.     NS_StringContainerFinish(*this);
  1389.     NS_StringContainerInit2(*this, aStart, aLength,
  1390.                             NS_STRING_CONTAINER_INIT_DEPEND |
  1391.                             NS_STRING_CONTAINER_INIT_SUBSTRING);
  1392.   }
  1393. private:
  1394.   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
  1395. };
  1396. class nsDependentCSubstring : public nsCStringContainer
  1397. {
  1398. public:
  1399.   typedef nsDependentCSubstring self_type;
  1400.   typedef nsACString            abstract_string_type;
  1401.   ~nsDependentCSubstring()
  1402.   {
  1403.     NS_CStringContainerFinish(*this);
  1404.   }
  1405.   nsDependentCSubstring()
  1406.   {
  1407.     NS_CStringContainerInit(*this);
  1408.   }
  1409.   nsDependentCSubstring(const char_type *aStart, PRUint32 aLength)
  1410.   {
  1411.     NS_CStringContainerInit2(*this, aStart, aLength,
  1412.                              NS_CSTRING_CONTAINER_INIT_DEPEND |
  1413.                              NS_CSTRING_CONTAINER_INIT_SUBSTRING);
  1414.   }
  1415.   nsDependentCSubstring(const abstract_string_type& aStr,
  1416.                         PRUint32 aStartPos)
  1417.   {
  1418.     const char* data;
  1419.     PRUint32 len = NS_CStringGetData(aStr, &data);
  1420.     NS_CStringContainerInit2(*this, data + aStartPos, len - aStartPos,
  1421.                              NS_CSTRING_CONTAINER_INIT_DEPEND |
  1422.                              NS_CSTRING_CONTAINER_INIT_SUBSTRING);
  1423.   }
  1424.   nsDependentCSubstring(const abstract_string_type& aStr,
  1425.                         PRUint32 aStartPos, PRUint32 aLength)
  1426.   {
  1427.     const char* data;
  1428. #ifdef DEBUG
  1429.     PRUint32 len =
  1430. #endif
  1431.     NS_CStringGetData(aStr, &data);
  1432.     NS_ASSERTION(aStartPos + aLength <= len, "bad length");
  1433.     NS_CStringContainerInit2(*this, data + aStartPos, aLength,
  1434.                              NS_CSTRING_CONTAINER_INIT_DEPEND |
  1435.                              NS_CSTRING_CONTAINER_INIT_SUBSTRING);
  1436.   }
  1437.   void Rebind(const char_type *aStart, PRUint32 aLength)
  1438.   {
  1439.     NS_CStringContainerFinish(*this);
  1440.     NS_CStringContainerInit2(*this, aStart, aLength,
  1441.                              NS_CSTRING_CONTAINER_INIT_DEPEND |
  1442.                              NS_CSTRING_CONTAINER_INIT_SUBSTRING);
  1443.   }
  1444. private:
  1445.   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
  1446. };
  1447. /**
  1448.  * Various nsDependentC?Substring constructor functions
  1449.  */
  1450. // PRUnichar
  1451. inline
  1452. const nsDependentSubstring
  1453. Substring( const nsAString& str, PRUint32 startPos )
  1454. {
  1455.   return nsDependentSubstring(str, startPos);
  1456. }
  1457. inline
  1458. const nsDependentSubstring
  1459. Substring( const nsAString& str, PRUint32 startPos, PRUint32 length )
  1460. {
  1461.   return nsDependentSubstring(str, startPos, length);
  1462. }
  1463. inline
  1464. const nsDependentSubstring
  1465. Substring( const PRUnichar* start, const PRUnichar* end )
  1466. {
  1467.   return nsDependentSubstring(start, end - start);
  1468. }
  1469. inline
  1470. const nsDependentSubstring
  1471. Substring( const PRUnichar* start, PRUint32 length )
  1472. {
  1473.   return nsDependentSubstring(start, length);
  1474. }
  1475. inline
  1476. const nsDependentSubstring
  1477. StringHead( const nsAString& str, PRUint32 count )
  1478. {
  1479.   return nsDependentSubstring(str, 0, count);
  1480. }
  1481. inline
  1482. const nsDependentSubstring
  1483. StringTail( const nsAString& str, PRUint32 count )
  1484. {
  1485.   return nsDependentSubstring(str, str.Length() - count, count);
  1486. }
  1487. // char
  1488. inline
  1489. const nsDependentCSubstring
  1490. Substring( const nsACString& str, PRUint32 startPos )
  1491. {
  1492.   return nsDependentCSubstring(str, startPos);
  1493. }
  1494. inline
  1495. const nsDependentCSubstring
  1496. Substring( const nsACString& str, PRUint32 startPos, PRUint32 length )
  1497. {
  1498.   return nsDependentCSubstring(str, startPos, length);
  1499. }
  1500. inline
  1501. const nsDependentCSubstring
  1502. Substring( const char* start, const char* end )
  1503. {
  1504.   return nsDependentCSubstring(start, end - start);
  1505. }
  1506. inline
  1507. const nsDependentCSubstring
  1508. Substring( const char* start, PRUint32 length )
  1509. {
  1510.   return nsDependentCSubstring(start, length);
  1511. }
  1512. inline
  1513. const nsDependentCSubstring
  1514. StringHead( const nsACString& str, PRUint32 count )
  1515. {
  1516.   return nsDependentCSubstring(str, 0, count);
  1517. }
  1518. inline
  1519. const nsDependentCSubstring
  1520. StringTail( const nsACString& str, PRUint32 count )
  1521. {
  1522.   return nsDependentCSubstring(str, str.Length() - count, count);
  1523. }
  1524. /*
  1525.  * Canonical empty strings
  1526.  */
  1527. #define EmptyCString() nsCString()
  1528. #define EmptyString() nsString()
  1529. #endif // MOZILLA_INTERNAL_API
  1530. #endif // nsStringAPI_h__