Back to index

lightning-sunbird  0.9+nobinonly
nsStringAPI.h
Go to the documentation of this file.
00001 /* vim:set ts=2 sw=2 et cindent: */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is Mozilla.
00016  *
00017  * The Initial Developer of the Original Code is IBM Corporation.
00018  * Portions created by IBM Corporation are Copyright (C) 2003
00019  * IBM Corporation.  All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *   Darin Fisher <darin@meer.net>
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef nsStringAPI_h__
00039 #define nsStringAPI_h__
00040 
00041 #include <string.h>
00042 
00051 // Map frozen functions to private symbol names if not using strict API.
00052 #ifdef MOZILLA_INTERNAL_API
00053 # define NS_StringContainerInit           NS_StringContainerInit_P
00054 # define NS_StringContainerInit2          NS_StringContainerInit2_P
00055 # define NS_StringContainerFinish         NS_StringContainerFinish_P
00056 # define NS_StringGetData                 NS_StringGetData_P
00057 # define NS_StringGetMutableData          NS_StringGetMutableData_P
00058 # define NS_StringCloneData               NS_StringCloneData_P
00059 # define NS_StringSetData                 NS_StringSetData_P
00060 # define NS_StringSetDataRange            NS_StringSetDataRange_P
00061 # define NS_StringCopy                    NS_StringCopy_P
00062 # define NS_CStringContainerInit          NS_CStringContainerInit_P
00063 # define NS_CStringContainerInit2         NS_CStringContainerInit2_P
00064 # define NS_CStringContainerFinish        NS_CStringContainerFinish_P
00065 # define NS_CStringGetData                NS_CStringGetData_P
00066 # define NS_CStringGetMutableData         NS_CStringGetMutableData_P
00067 # define NS_CStringCloneData              NS_CStringCloneData_P
00068 # define NS_CStringSetData                NS_CStringSetData_P
00069 # define NS_CStringSetDataRange           NS_CStringSetDataRange_P
00070 # define NS_CStringCopy                   NS_CStringCopy_P
00071 # define NS_CStringToUTF16                NS_CStringToUTF16_P
00072 # define NS_UTF16ToCString                NS_UTF16ToCString_P
00073 #endif
00074 
00075 #include "nscore.h"
00076 
00077 #if defined( XPCOM_GLUE )
00078 #define NS_STRINGAPI(type) extern "C" NS_HIDDEN_(type)
00079 #elif defined( _IMPL_NS_STRINGAPI )
00080 #define NS_STRINGAPI(type) extern "C" NS_EXPORT type
00081 #else
00082 #define NS_STRINGAPI(type) extern "C" NS_IMPORT type
00083 #endif
00084 
00085 /* The base string types */
00086 class nsAString;
00087 class nsACString;
00088 
00089 /* ------------------------------------------------------------------------- */
00090 
00155 class nsStringContainer;
00156 
00160 enum {
00161   /* Data passed into NS_StringContainerInit2 is not copied; instead, the
00162    * string references the passed in data pointer directly.  The caller must
00163    * ensure that the data is valid for the lifetime of the string container.
00164    * This flag should not be combined with NS_STRING_CONTAINER_INIT_ADOPT. */
00165   NS_STRING_CONTAINER_INIT_DEPEND    = (1 << 1),
00166 
00167   /* Data passed into NS_StringContainerInit2 is not copied; instead, the
00168    * string takes ownership over the data pointer.  The caller must have
00169    * allocated the data array using the XPCOM memory allocator (nsMemory).
00170    * This flag should not be combined with NS_STRING_CONTAINER_INIT_DEPEND. */
00171   NS_STRING_CONTAINER_INIT_ADOPT     = (1 << 2),
00172 
00173   /* Data passed into NS_StringContainerInit2 is a substring that is not
00174    * null-terminated. */
00175   NS_STRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
00176 };
00177 
00189 NS_STRINGAPI(nsresult)
00190 NS_StringContainerInit(nsStringContainer &aContainer);
00191 
00213 NS_STRINGAPI(nsresult)
00214 NS_StringContainerInit2
00215   (nsStringContainer &aContainer, const PRUnichar *aData = nsnull,
00216    PRUint32 aDataLength = PR_UINT32_MAX, PRUint32 aFlags = 0);
00217 
00227 NS_STRINGAPI(void)
00228 NS_StringContainerFinish(nsStringContainer &aContainer);
00229 
00230 /* ------------------------------------------------------------------------- */
00231 
00249 NS_STRINGAPI(PRUint32)
00250 NS_StringGetData
00251   (const nsAString &aStr, const PRUnichar **aData,
00252    PRBool *aTerminated = nsnull);
00253 
00283 NS_STRINGAPI(PRUint32)
00284 NS_StringGetMutableData
00285   (nsAString &aStr, PRUint32 aDataLength, PRUnichar **aData);
00286 
00299 NS_STRINGAPI(PRUnichar *)
00300 NS_StringCloneData
00301   (const nsAString &aStr);
00302 
00322 NS_STRINGAPI(nsresult)
00323 NS_StringSetData
00324   (nsAString &aStr, const PRUnichar *aData,
00325    PRUint32 aDataLength = PR_UINT32_MAX);
00326 
00355 NS_STRINGAPI(nsresult)
00356 NS_StringSetDataRange
00357   (nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
00358    const PRUnichar *aData, PRUint32 aDataLength = PR_UINT32_MAX);
00359 
00377 NS_STRINGAPI(nsresult)
00378 NS_StringCopy
00379   (nsAString &aDestStr, const nsAString &aSrcStr);
00380 
00397 inline NS_HIDDEN_(nsresult)
00398 NS_StringAppendData(nsAString &aStr, const PRUnichar *aData,
00399                     PRUint32 aDataLength = PR_UINT32_MAX)
00400 {
00401   return NS_StringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
00402 }
00403 
00422 inline NS_HIDDEN_(nsresult)
00423 NS_StringInsertData(nsAString &aStr, PRUint32 aOffset, const PRUnichar *aData,
00424                     PRUint32 aDataLength = PR_UINT32_MAX)
00425 {
00426   return NS_StringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
00427 }
00428 
00440 inline NS_HIDDEN_(nsresult)
00441 NS_StringCutData(nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
00442 {
00443   return NS_StringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
00444 }
00445 
00446 /* ------------------------------------------------------------------------- */
00447 
00460 class nsCStringContainer;
00461 
00465 enum {
00466   /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
00467    * string references the passed in data pointer directly.  The caller must
00468    * ensure that the data is valid for the lifetime of the string container.
00469    * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_ADOPT. */
00470   NS_CSTRING_CONTAINER_INIT_DEPEND    = (1 << 1),
00471 
00472   /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
00473    * string takes ownership over the data pointer.  The caller must have
00474    * allocated the data array using the XPCOM memory allocator (nsMemory).
00475    * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_DEPEND. */
00476   NS_CSTRING_CONTAINER_INIT_ADOPT     = (1 << 2),
00477 
00478   /* Data passed into NS_CStringContainerInit2 is a substring that is not
00479    * null-terminated. */
00480   NS_CSTRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
00481 };
00482 
00494 NS_STRINGAPI(nsresult)
00495 NS_CStringContainerInit(nsCStringContainer &aContainer);
00496 
00518 NS_STRINGAPI(nsresult)
00519 NS_CStringContainerInit2
00520   (nsCStringContainer &aContainer, const char *aData = nsnull,
00521    PRUint32 aDataLength = PR_UINT32_MAX, PRUint32 aFlags = 0);
00522 
00532 NS_STRINGAPI(void)
00533 NS_CStringContainerFinish(nsCStringContainer &aContainer);
00534 
00535 /* ------------------------------------------------------------------------- */
00536 
00554 NS_STRINGAPI(PRUint32)
00555 NS_CStringGetData
00556   (const nsACString &aStr, const char **aData,
00557    PRBool *aTerminated = nsnull);
00558 
00588 NS_STRINGAPI(PRUint32)
00589 NS_CStringGetMutableData
00590   (nsACString &aStr, PRUint32 aDataLength, char **aData);
00591 
00604 NS_STRINGAPI(char *)
00605 NS_CStringCloneData
00606   (const nsACString &aStr);
00607 
00627 NS_STRINGAPI(nsresult)
00628 NS_CStringSetData
00629   (nsACString &aStr, const char *aData,
00630    PRUint32 aDataLength = PR_UINT32_MAX);
00631 
00660 NS_STRINGAPI(nsresult)
00661 NS_CStringSetDataRange
00662   (nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
00663    const char *aData, PRUint32 aDataLength = PR_UINT32_MAX);
00664 
00682 NS_STRINGAPI(nsresult)
00683 NS_CStringCopy
00684   (nsACString &aDestStr, const nsACString &aSrcStr);
00685 
00702 inline NS_HIDDEN_(nsresult)
00703 NS_CStringAppendData(nsACString &aStr, const char *aData,
00704                     PRUint32 aDataLength = PR_UINT32_MAX)
00705 {
00706   return NS_CStringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
00707 }
00708 
00727 inline NS_HIDDEN_(nsresult)
00728 NS_CStringInsertData(nsACString &aStr, PRUint32 aOffset, const char *aData,
00729                     PRUint32 aDataLength = PR_UINT32_MAX)
00730 {
00731   return NS_CStringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
00732 }
00733 
00745 inline NS_HIDDEN_(nsresult)
00746 NS_CStringCutData(nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
00747 {
00748   return NS_CStringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
00749 }
00750 
00751 /* ------------------------------------------------------------------------- */
00752 
00756 enum nsCStringEncoding {
00757   /* Conversion between ASCII and UTF-16 assumes that all bytes in the source
00758    * string are 7-bit ASCII and can be inflated to UTF-16 by inserting null
00759    * bytes.  Reverse conversion is done by truncating every other byte.  The
00760    * conversion may result in loss and/or corruption of information if the
00761    * strings do not strictly contain ASCII data. */
00762   NS_CSTRING_ENCODING_ASCII = 0,
00763 
00764   /* Conversion between UTF-8 and UTF-16 is non-lossy. */
00765   NS_CSTRING_ENCODING_UTF8 = 1,
00766 
00767   /* Conversion from UTF-16 to the native filesystem charset may result in a
00768    * loss of information.  No attempt is made to protect against data loss in
00769    * this case.  The native filesystem charset applies to strings passed to
00770    * the "Native" method variants on nsIFile and nsILocalFile. */
00771   NS_CSTRING_ENCODING_NATIVE_FILESYSTEM = 2
00772 };
00773 
00787 NS_STRINGAPI(nsresult)
00788 NS_CStringToUTF16(const nsACString &aSource, nsCStringEncoding aSrcEncoding,
00789                   nsAString &aDest);
00790 
00806 NS_STRINGAPI(nsresult)
00807 NS_UTF16ToCString(const nsAString &aSource, nsCStringEncoding aDestEncoding,
00808                   nsACString &aDest);
00809 
00810 /* ------------------------------------------------------------------------- */
00811 
00826 #ifndef MOZILLA_INTERNAL_API
00827 #define nsAString_external nsAString
00828 #define nsACString_external nsACString
00829 #endif
00830 
00831 class nsAString_external
00832 {
00833 #ifndef MOZILLA_INTERNAL_API
00834 
00835 public:
00836   typedef PRUnichar             char_type;
00837   typedef nsAString_external    self_type;
00838   typedef PRUint32              size_type;
00839   typedef PRUint32              index_type;
00840 
00841   NS_HIDDEN_(const char_type*) BeginReading() const
00842   {
00843     const char_type *data;
00844     NS_StringGetData(*this, &data);
00845     return data;
00846   }
00847 
00848   NS_HIDDEN_(const char_type*) EndReading() const
00849   {
00850     const char_type *data;
00851     PRUint32 len = NS_StringGetData(*this, &data);
00852     return data + len;
00853   }
00854 
00855   NS_HIDDEN_(char_type*) BeginWriting()
00856   {
00857     char_type *data;
00858     NS_StringGetMutableData(*this, PR_UINT32_MAX, &data);
00859     return data;
00860   }
00861 
00862   NS_HIDDEN_(PRBool) SetLength(PRUint32 aLen)
00863   {
00864     char_type *data;
00865     NS_StringGetMutableData(*this, aLen, &data);
00866     return data != nsnull;
00867   }
00868 
00869   NS_HIDDEN_(size_type) Length() const
00870   {
00871     const char_type* data;
00872     return NS_StringGetData(*this, &data);
00873   }
00874 
00875   NS_HIDDEN_(PRBool) IsEmpty() const
00876   {
00877     return Length() == 0;
00878   }
00879 
00880   NS_HIDDEN_(void) Assign(const self_type& aString)
00881   {
00882     NS_StringCopy(*this, aString);
00883   }
00884   NS_HIDDEN_(void) Assign(const char_type* aData, size_type aLength = PR_UINT32_MAX)
00885   {
00886     NS_StringSetData(*this, aData, aLength);
00887   }
00888   NS_HIDDEN_(void) Assign(char_type aChar)
00889   {
00890     NS_StringSetData(*this, &aChar, 1);
00891   }
00892 
00893   NS_HIDDEN_(self_type&) operator=(const self_type& aString) { Assign(aString);   return *this; }
00894   NS_HIDDEN_(self_type&) operator=(const char_type* aPtr)    { Assign(aPtr);      return *this; }
00895   NS_HIDDEN_(self_type&) operator=(char_type aChar)          { Assign(aChar);     return *this; }
00896 
00897   NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const char_type* data, size_type length = size_type(-1) )
00898   {
00899     NS_StringSetDataRange(*this, cutStart, cutLength, data, length);
00900   }
00901   NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, char_type c )
00902   {
00903     Replace(cutStart, cutLength, &c, 1);
00904   }
00905   NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const self_type& readable )
00906   {
00907     const char_type* data;
00908     PRUint32 dataLen = NS_StringGetData(readable, &data);
00909     NS_StringSetDataRange(*this, cutStart, cutLength, data, dataLen);
00910   }
00911 
00912   NS_HIDDEN_(void) Append( char_type c )                                                              { Replace(size_type(-1), 0, c); }
00913   NS_HIDDEN_(void) Append( const char_type* data, size_type length = size_type(-1) )                  { Replace(size_type(-1), 0, data, length); }
00914   NS_HIDDEN_(void) Append( const self_type& readable )                                                { Replace(size_type(-1), 0, readable); }
00915 
00916   NS_HIDDEN_(self_type&) operator+=( char_type c )                                                    { Append(c);        return *this; }
00917   NS_HIDDEN_(self_type&) operator+=( const char_type* data )                                          { Append(data);     return *this; }
00918   NS_HIDDEN_(self_type&) operator+=( const self_type& readable )                                      { Append(readable); return *this; }
00919 
00920   NS_HIDDEN_(void) Insert( char_type c, index_type pos )                                              { Replace(pos, 0, c); }
00921   NS_HIDDEN_(void) Insert( const char_type* data, index_type pos, size_type length = size_type(-1) )  { Replace(pos, 0, data, length); }
00922   NS_HIDDEN_(void) Insert( const self_type& readable, index_type pos )                                { Replace(pos, 0, readable); }
00923 
00924   NS_HIDDEN_(void) Cut( index_type cutStart, size_type cutLength )                                    { Replace(cutStart, cutLength, nsnull, 0); }
00925 
00926   NS_HIDDEN_(PRBool) Equals( const self_type &other ) const {
00927     const char_type *cself;
00928     const char_type *cother;
00929     PRUint32 selflen = NS_StringGetData(*this, &cself);
00930     PRUint32 otherlen = NS_StringGetData(other, &cother);
00931 
00932     if (selflen != otherlen)
00933       return PR_FALSE;
00934 
00935     return memcmp(cself, cother, selflen * sizeof(char_type)) == 0;
00936   }
00937 
00938 #endif // MOZILLA_INTERNAL_API
00939 
00940 protected:
00941   // Prevent people from allocating a nsAString directly.
00942   ~nsAString_external() {}
00943 
00944 private:
00945   void *v;
00946 };
00947 
00948 class nsACString_external
00949 {
00950 #ifndef MOZILLA_INTERNAL_API
00951 
00952 public:
00953   typedef char                  char_type;
00954   typedef nsACString_external   self_type;
00955   typedef PRUint32              size_type;
00956   typedef PRUint32              index_type;
00957 
00958   NS_HIDDEN_(const char_type*) BeginReading() const
00959   {
00960     const char_type *data;
00961     NS_CStringGetData(*this, &data);
00962     return data;
00963   }
00964 
00965   NS_HIDDEN_(const char_type*) EndReading() const
00966   {
00967     const char_type *data;
00968     PRUint32 len = NS_CStringGetData(*this, &data);
00969     return data + len;
00970   }
00971 
00972   NS_HIDDEN_(char_type*) BeginWriting()
00973   {
00974     char_type *data;
00975     NS_CStringGetMutableData(*this, PR_UINT32_MAX, &data);
00976     return data;
00977   }
00978 
00979   NS_HIDDEN_(PRBool) SetLength(PRUint32 aLen)
00980   {
00981     char_type *data;
00982     NS_CStringGetMutableData(*this, aLen, &data);
00983     return data != nsnull;
00984   }
00985 
00986   NS_HIDDEN_(size_type) Length() const
00987   {
00988     const char_type* data;
00989     return NS_CStringGetData(*this, &data);
00990   }
00991 
00992   NS_HIDDEN_(PRBool) IsEmpty() const
00993   {
00994     return Length() == 0;
00995   }
00996 
00997   NS_HIDDEN_(void) Assign(const self_type& aString)
00998   {
00999     NS_CStringCopy(*this, aString);
01000   }
01001   NS_HIDDEN_(void) Assign(const char_type* aData, size_type aLength = PR_UINT32_MAX)
01002   {
01003     NS_CStringSetData(*this, aData, aLength);
01004   }
01005   NS_HIDDEN_(void) Assign(char_type aChar)
01006   {
01007     NS_CStringSetData(*this, &aChar, 1);
01008   }
01009 
01010   NS_HIDDEN_(self_type&) operator=(const self_type& aString) { Assign(aString);   return *this; }
01011   NS_HIDDEN_(self_type&) operator=(const char_type* aPtr)    { Assign(aPtr);      return *this; }
01012   NS_HIDDEN_(self_type&) operator=(char_type aChar)          { Assign(aChar);     return *this; }
01013 
01014   NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const char_type* data, size_type length = size_type(-1) )
01015   {
01016     NS_CStringSetDataRange(*this, cutStart, cutLength, data, length);
01017   }
01018   NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, char_type c )
01019   {
01020     Replace(cutStart, cutLength, &c, 1);
01021   }
01022   NS_HIDDEN_(void) Replace( index_type cutStart, size_type cutLength, const self_type& readable )
01023   {
01024     const char_type* data;
01025     PRUint32 dataLen = NS_CStringGetData(readable, &data);
01026     NS_CStringSetDataRange(*this, cutStart, cutLength, data, dataLen);
01027   }
01028 
01029   NS_HIDDEN_(void) Append( char_type c )                                                              { Replace(size_type(-1), 0, c); }
01030   NS_HIDDEN_(void) Append( const char_type* data, size_type length = size_type(-1) )                  { Replace(size_type(-1), 0, data, length); }
01031   NS_HIDDEN_(void) Append( const self_type& readable )                                                { Replace(size_type(-1), 0, readable); }
01032 
01033   NS_HIDDEN_(self_type&) operator+=( char_type c )                                                    { Append(c);        return *this; }
01034   NS_HIDDEN_(self_type&) operator+=( const char_type* data )                                          { Append(data);     return *this; }
01035   NS_HIDDEN_(self_type&) operator+=( const self_type& readable )                                      { Append(readable); return *this; }
01036 
01037   NS_HIDDEN_(void) Insert( char_type c, index_type pos )                                              { Replace(pos, 0, c); }
01038   NS_HIDDEN_(void) Insert( const char_type* data, index_type pos, size_type length = size_type(-1) )  { Replace(pos, 0, data, length); }
01039   NS_HIDDEN_(void) Insert( const self_type& readable, index_type pos )                                { Replace(pos, 0, readable); }
01040 
01041   NS_HIDDEN_(void) Cut( index_type cutStart, size_type cutLength )                                    { Replace(cutStart, cutLength, nsnull, 0); }
01042 
01043   NS_HIDDEN_(PRBool) Equals( const self_type &other ) const {
01044     const char_type *cself;
01045     const char_type *cother;
01046     PRUint32 selflen = NS_CStringGetData(*this, &cself);
01047     PRUint32 otherlen = NS_CStringGetData(other, &cother);
01048 
01049     if (selflen != otherlen)
01050       return PR_FALSE;
01051  
01052     return memcmp(cself, cother, selflen * sizeof(char_type)) == 0;
01053   }
01054 
01055 #endif // MOZILLA_INTERNAL_API
01056 
01057 protected:
01058   // Prevent people from allocating a nsACString directly.
01059   ~nsACString_external() {}
01060 
01061 private:
01062   void *v;
01063 };
01064 
01065 /* ------------------------------------------------------------------------- */
01066 
01074 class nsStringContainer : public nsAString_external
01075 {
01076 private:
01077   void     *d1;
01078   PRUint32  d2;
01079   void     *d3;
01080 
01081 public:
01082   nsStringContainer() {} // MSVC6 needs this
01083 };
01084 
01085 class nsCStringContainer : public nsACString_external
01086 {
01087 private:
01088   void    *d1;
01089   PRUint32 d2;
01090   void    *d3;
01091 
01092 public:
01093   nsCStringContainer() {} // MSVC6 needs this
01094 };
01095 
01096 /* ------------------------------------------------------------------------- */
01097 
01103 #ifndef MOZILLA_INTERNAL_API
01104 #include "nsDebug.h"
01105 
01109 #define nsString                       nsString_external
01110 #define nsCString                      nsCString_external
01111 #define nsDependentString              nsDependentString_external
01112 #define nsDependentCString             nsDependentCString_external
01113 #define NS_ConvertASCIItoUTF16         NS_ConvertASCIItoUTF16_external
01114 #define NS_ConvertUTF8toUTF16          NS_ConvertUTF8toUTF16_external
01115 #define NS_ConvertUTF16toUTF8          NS_ConvertUTF16toUTF8_external
01116 #define NS_LossyConvertUTF16toASCII    NS_LossyConvertUTF16toASCII_external
01117 #define nsGetterCopies                 nsGetterCopies_external
01118 #define nsCGetterCopies                nsCGetterCopies_external
01119 #define nsDependentSubstring           nsDependentSubstring_external
01120 #define nsDependentCSubstring          nsDependentCSubstring_external
01121 
01126 class nsString : public nsStringContainer
01127 {
01128 public:
01129   typedef nsString         self_type;
01130   typedef nsAString        abstract_string_type;
01131 
01132   nsString()
01133   {
01134     NS_StringContainerInit(*this);
01135   }
01136 
01137   nsString(const self_type& aString)
01138   {
01139     NS_StringContainerInit(*this);
01140     NS_StringCopy(*this, aString);
01141   }
01142 
01143   explicit
01144   nsString(const abstract_string_type& aReadable)
01145   {
01146     NS_StringContainerInit(*this);
01147     NS_StringCopy(*this, aReadable);
01148   }
01149 
01150   explicit
01151   nsString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
01152   {
01153     NS_StringContainerInit2(*this, aData, aLength, 0);
01154   }
01155   
01156   ~nsString()
01157   {
01158     NS_StringContainerFinish(*this);
01159   }
01160 
01161   const char_type* get() const
01162   {
01163     const char_type* data;
01164     NS_StringGetData(*this, &data);
01165     return data;
01166   }
01167   
01168   self_type& operator=(const self_type& aString)              { Assign(aString);   return *this; }
01169   self_type& operator=(const abstract_string_type& aReadable) { Assign(aReadable); return *this; }
01170   self_type& operator=(const char_type* aPtr)                 { Assign(aPtr);      return *this; }
01171   self_type& operator=(char_type aChar)                       { Assign(aChar);     return *this; }
01172 
01173   void Adopt(const char_type *aData, size_type aLength = PR_UINT32_MAX)
01174   {
01175     NS_StringContainerFinish(*this);
01176     NS_StringContainerInit2(*this, aData, aLength,
01177                             NS_STRING_CONTAINER_INIT_ADOPT);
01178   }
01179 
01180 protected:
01181   
01182   nsString(const char_type* aData, size_type aLength, PRUint32 aFlags)
01183   {
01184     NS_StringContainerInit2(*this, aData, aLength, aFlags);
01185   }
01186 };
01187 
01188 class nsCString : public nsCStringContainer
01189 {
01190 public:
01191   typedef nsCString        self_type;
01192   typedef nsACString       abstract_string_type;
01193 
01194   nsCString()
01195   {
01196     NS_CStringContainerInit(*this);
01197   }
01198 
01199   nsCString(const self_type& aString)
01200   {
01201     NS_CStringContainerInit(*this);
01202     NS_CStringCopy(*this, aString);
01203   }
01204 
01205   explicit
01206   nsCString(const abstract_string_type& aReadable)
01207   {
01208     NS_CStringContainerInit(*this);
01209     NS_CStringCopy(*this, aReadable);
01210   }
01211 
01212   explicit
01213   nsCString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
01214   {
01215     NS_CStringContainerInit(*this);
01216     NS_CStringSetData(*this, aData, aLength);
01217   }
01218   
01219   ~nsCString()
01220   {
01221     NS_CStringContainerFinish(*this);
01222   }
01223 
01224   const char_type* get() const
01225   {
01226     const char_type* data;
01227     NS_CStringGetData(*this, &data);
01228     return data;
01229   }
01230   
01231   self_type& operator=(const self_type& aString)              { Assign(aString);   return *this; }
01232   self_type& operator=(const abstract_string_type& aReadable) { Assign(aReadable); return *this; }
01233   self_type& operator=(const char_type* aPtr)                 { Assign(aPtr);      return *this; }
01234   self_type& operator=(char_type aChar)                       { Assign(aChar);     return *this; }
01235 
01236   void Adopt(const char_type *aData, size_type aLength = PR_UINT32_MAX)
01237   {
01238     NS_CStringContainerFinish(*this);
01239     NS_CStringContainerInit2(*this, aData, aLength,
01240                              NS_CSTRING_CONTAINER_INIT_ADOPT);
01241   }
01242 
01243 protected:
01244   
01245   nsCString(const char_type* aData, size_type aLength, PRUint32 aFlags)
01246   {
01247     NS_CStringContainerInit2(*this, aData, aLength, aFlags);
01248   }
01249 };
01250 
01251 
01256 class nsDependentString : public nsString
01257 {
01258 public:
01259   typedef nsDependentString         self_type;
01260 
01261   nsDependentString() {}
01262 
01263   explicit
01264   nsDependentString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
01265     : nsString(aData, aLength, NS_CSTRING_CONTAINER_INIT_DEPEND)
01266   {}
01267 
01268   void Rebind(const char_type* aData, size_type aLength = PR_UINT32_MAX)
01269   {
01270     NS_StringContainerFinish(*this);
01271     NS_StringContainerInit2(*this, aData, aLength,
01272                             NS_STRING_CONTAINER_INIT_DEPEND);
01273   }
01274   
01275 private:
01276   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
01277 };
01278 
01279 class nsDependentCString : public nsCString
01280 {
01281 public:
01282   typedef nsDependentCString        self_type;
01283 
01284   nsDependentCString() {}
01285 
01286   explicit
01287   nsDependentCString(const char_type* aData, size_type aLength = PR_UINT32_MAX)
01288     : nsCString(aData, aLength, NS_CSTRING_CONTAINER_INIT_DEPEND)
01289   {}
01290 
01291   void Rebind(const char_type* aData, size_type aLength = PR_UINT32_MAX)
01292   {
01293     NS_CStringContainerFinish(*this);
01294     NS_CStringContainerInit2(*this, aData, aLength,
01295                              NS_CSTRING_CONTAINER_INIT_DEPEND);
01296   }
01297   
01298 private:
01299   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
01300 };
01301 
01302 
01307 class NS_ConvertASCIItoUTF16 : public nsString
01308 {
01309 public:
01310   typedef NS_ConvertASCIItoUTF16    self_type;
01311 
01312   explicit
01313   NS_ConvertASCIItoUTF16(const nsACString& aStr)
01314   {
01315     NS_CStringToUTF16(aStr, NS_CSTRING_ENCODING_ASCII, *this);
01316   }
01317 
01318   explicit
01319   NS_ConvertASCIItoUTF16(const char* aData, PRUint32 aLength = PR_UINT32_MAX)
01320   {
01321     NS_CStringToUTF16(nsDependentCString(aData, aLength),
01322                       NS_CSTRING_ENCODING_ASCII, *this);
01323   }
01324 
01325 private:
01326   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
01327 };
01328 
01329 class NS_ConvertUTF8toUTF16 : public nsString
01330 {
01331 public:
01332   typedef NS_ConvertUTF8toUTF16    self_type;
01333 
01334   explicit
01335   NS_ConvertUTF8toUTF16(const nsACString& aStr)
01336   {
01337     NS_CStringToUTF16(aStr, NS_CSTRING_ENCODING_UTF8, *this);
01338   }
01339 
01340   explicit
01341   NS_ConvertUTF8toUTF16(const char* aData, PRUint32 aLength = PR_UINT32_MAX)
01342   {
01343     NS_CStringToUTF16(nsDependentCString(aData, aLength),
01344                       NS_CSTRING_ENCODING_UTF8, *this);
01345   }
01346 
01347 private:
01348   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
01349 };
01350 
01351 class NS_ConvertUTF16toUTF8 : public nsCString
01352 {
01353 public:
01354   typedef NS_ConvertUTF16toUTF8    self_type;
01355 
01356   explicit
01357   NS_ConvertUTF16toUTF8(const nsAString& aStr)
01358   {
01359     NS_UTF16ToCString(aStr, NS_CSTRING_ENCODING_UTF8, *this);
01360   }
01361 
01362   explicit
01363   NS_ConvertUTF16toUTF8(const PRUnichar* aData, PRUint32 aLength = PR_UINT32_MAX)
01364   {
01365     NS_UTF16ToCString(nsDependentString(aData, aLength),
01366                       NS_CSTRING_ENCODING_UTF8, *this);
01367   }
01368 
01369 private:
01370   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
01371 };
01372 
01373 class NS_LossyConvertUTF16toASCII : public nsCString
01374 {
01375 public:
01376   typedef NS_LossyConvertUTF16toASCII    self_type;
01377 
01378   explicit
01379   NS_LossyConvertUTF16toASCII(const nsAString& aStr)
01380   {
01381     NS_UTF16ToCString(aStr, NS_CSTRING_ENCODING_ASCII, *this);
01382   }
01383 
01384   explicit
01385   NS_LossyConvertUTF16toASCII(const PRUnichar* aData, PRUint32 aLength = PR_UINT32_MAX)
01386   {
01387     NS_UTF16ToCString(nsDependentString(aData, aLength),
01388                       NS_CSTRING_ENCODING_ASCII, *this);
01389   }
01390 
01391 private:
01392   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
01393 };
01394 
01395 
01404 #ifdef HAVE_CPP_2BYTE_WCHAR_T
01405   #define NS_LL(s)                                L##s
01406   #define NS_MULTILINE_LITERAL_STRING(s)          nsDependentString(NS_REINTERPRET_CAST(const nsAString::char_type*, s), PRUint32((sizeof(s)/sizeof(wchar_t))-1))
01407   #define NS_MULTILINE_LITERAL_STRING_INIT(n,s)   n(NS_REINTERPRET_CAST(const nsAString::char_type*, s), PRUint32((sizeof(s)/sizeof(wchar_t))-1))
01408   #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))
01409   typedef nsDependentString nsLiteralString;
01410 #else
01411   #define NS_LL(s)                                s
01412   #define NS_MULTILINE_LITERAL_STRING(s)          NS_ConvertASCIItoUTF16(s, PRUint32(sizeof(s)-1))
01413   #define NS_MULTILINE_LITERAL_STRING_INIT(n,s)   n(s, PRUint32(sizeof(s)-1))
01414   #define NS_NAMED_MULTILINE_LITERAL_STRING(n,s)  const NS_ConvertASCIItoUTF16 n(s, PRUint32(sizeof(s)-1))
01415   typedef NS_ConvertASCIItoUTF16 nsLiteralString;
01416 #endif
01417 
01418 /*
01419  * Macro arguments used in concatenation or stringification won't be expanded.
01420  * Therefore, in order for |NS_L(FOO)| to work as expected (which is to expand
01421  * |FOO| before doing whatever |NS_L| needs to do to it) a helper macro needs
01422  * to be inserted in between to allow the macro argument to expand.
01423  * See "3.10.6 Separate Expansion of Macro Arguments" of the CPP manual for a
01424  * more accurate and precise explanation.
01425  */
01426 
01427 #define NS_L(s)                                   NS_LL(s)
01428 
01429 #define NS_LITERAL_STRING(s)                      NS_STATIC_CAST(const nsString&, NS_MULTILINE_LITERAL_STRING(NS_LL(s)))
01430 #define NS_LITERAL_STRING_INIT(n,s)               NS_MULTILINE_LITERAL_STRING_INIT(n, NS_LL(s))
01431 #define NS_NAMED_LITERAL_STRING(n,s)              NS_NAMED_MULTILINE_LITERAL_STRING(n, NS_LL(s))
01432 
01433 #define NS_LITERAL_CSTRING(s)                     NS_STATIC_CAST(const nsDependentCString&, nsDependentCString(s, PRUint32(sizeof(s)-1)))
01434 #define NS_LITERAL_CSTRING_INIT(n,s)              n(s, PRUint32(sizeof(s)-1))
01435 #define NS_NAMED_LITERAL_CSTRING(n,s)             const nsDependentCString n(s, PRUint32(sizeof(s)-1))
01436 
01437 typedef nsDependentCString nsLiteralCString;
01438 
01439 
01453 class nsGetterCopies
01454 {
01455 public:
01456   typedef PRUnichar char_type;
01457 
01458   nsGetterCopies(nsString& aStr)
01459     : mString(aStr), mData(nsnull)
01460   {}
01461 
01462   ~nsGetterCopies()
01463   {
01464     mString.Adopt(mData);
01465   }
01466 
01467   operator char_type**()
01468   {
01469     return &mData;
01470   }
01471 
01472 private:
01473   nsString&  mString;
01474   char_type* mData;
01475 };
01476 
01477 inline nsGetterCopies
01478 getter_Copies(nsString& aString)
01479 {
01480   return nsGetterCopies(aString);
01481 }
01482 
01483 class nsCGetterCopies
01484 {
01485 public:
01486   typedef char char_type;
01487 
01488   nsCGetterCopies(nsCString& aStr)
01489     : mString(aStr), mData(nsnull)
01490   {}
01491 
01492   ~nsCGetterCopies()
01493   {
01494     mString.Adopt(mData);
01495   }
01496 
01497   operator char_type**()
01498   {
01499     return &mData;
01500   }
01501 
01502 private:
01503   nsCString& mString;
01504   char_type* mData;
01505 };
01506 
01507 inline nsCGetterCopies
01508 getter_Copies(nsCString& aString)
01509 {
01510   return nsCGetterCopies(aString);
01511 }
01512 
01513 
01518 class nsDependentSubstring : public nsStringContainer
01519 {
01520 public:
01521   typedef nsDependentSubstring self_type;
01522   typedef nsAString            abstract_string_type;
01523 
01524   ~nsDependentSubstring()
01525   {
01526     NS_StringContainerFinish(*this);
01527   }
01528 
01529   nsDependentSubstring()
01530   {
01531     NS_StringContainerInit(*this);
01532   }
01533 
01534   nsDependentSubstring(const char_type *aStart, PRUint32 aLength)
01535   {
01536     NS_StringContainerInit2(*this, aStart, aLength,
01537                             NS_STRING_CONTAINER_INIT_DEPEND |
01538                             NS_STRING_CONTAINER_INIT_SUBSTRING);
01539   }
01540 
01541   nsDependentSubstring(const abstract_string_type& aStr,
01542                        PRUint32 aStartPos)
01543   {
01544     const PRUnichar* data;
01545     PRUint32 len = NS_StringGetData(aStr, &data);
01546     NS_StringContainerInit2(*this, data + aStartPos, len - aStartPos,
01547                             NS_STRING_CONTAINER_INIT_DEPEND |
01548                             NS_STRING_CONTAINER_INIT_SUBSTRING);
01549   }
01550 
01551   nsDependentSubstring(const abstract_string_type& aStr,
01552                        PRUint32 aStartPos, PRUint32 aLength)
01553   {
01554     const PRUnichar* data;
01555 #ifdef DEBUG
01556     PRUint32 len =
01557 #endif
01558     NS_StringGetData(aStr, &data);
01559     NS_ASSERTION(aStartPos + aLength <= len, "bad length");
01560     NS_StringContainerInit2(*this, data + aStartPos, aLength,
01561                             NS_STRING_CONTAINER_INIT_DEPEND |
01562                             NS_STRING_CONTAINER_INIT_SUBSTRING);
01563   }
01564 
01565   void Rebind(const char_type *aStart, PRUint32 aLength)
01566   {
01567     NS_StringContainerFinish(*this);
01568     NS_StringContainerInit2(*this, aStart, aLength,
01569                             NS_STRING_CONTAINER_INIT_DEPEND |
01570                             NS_STRING_CONTAINER_INIT_SUBSTRING);
01571   }
01572 
01573 private:
01574   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
01575 };
01576 
01577 class nsDependentCSubstring : public nsCStringContainer
01578 {
01579 public:
01580   typedef nsDependentCSubstring self_type;
01581   typedef nsACString            abstract_string_type;
01582 
01583   ~nsDependentCSubstring()
01584   {
01585     NS_CStringContainerFinish(*this);
01586   }
01587 
01588   nsDependentCSubstring()
01589   {
01590     NS_CStringContainerInit(*this);
01591   }
01592 
01593   nsDependentCSubstring(const char_type *aStart, PRUint32 aLength)
01594   {
01595     NS_CStringContainerInit2(*this, aStart, aLength,
01596                              NS_CSTRING_CONTAINER_INIT_DEPEND |
01597                              NS_CSTRING_CONTAINER_INIT_SUBSTRING);
01598   }
01599 
01600   nsDependentCSubstring(const abstract_string_type& aStr,
01601                         PRUint32 aStartPos)
01602   {
01603     const char* data;
01604     PRUint32 len = NS_CStringGetData(aStr, &data);
01605     NS_CStringContainerInit2(*this, data + aStartPos, len - aStartPos,
01606                              NS_CSTRING_CONTAINER_INIT_DEPEND |
01607                              NS_CSTRING_CONTAINER_INIT_SUBSTRING);
01608   }
01609 
01610   nsDependentCSubstring(const abstract_string_type& aStr,
01611                         PRUint32 aStartPos, PRUint32 aLength)
01612   {
01613     const char* data;
01614 #ifdef DEBUG
01615     PRUint32 len =
01616 #endif
01617     NS_CStringGetData(aStr, &data);
01618     NS_ASSERTION(aStartPos + aLength <= len, "bad length");
01619     NS_CStringContainerInit2(*this, data + aStartPos, aLength,
01620                              NS_CSTRING_CONTAINER_INIT_DEPEND |
01621                              NS_CSTRING_CONTAINER_INIT_SUBSTRING);
01622   }
01623 
01624   void Rebind(const char_type *aStart, PRUint32 aLength)
01625   {
01626     NS_CStringContainerFinish(*this);
01627     NS_CStringContainerInit2(*this, aStart, aLength,
01628                              NS_CSTRING_CONTAINER_INIT_DEPEND |
01629                              NS_CSTRING_CONTAINER_INIT_SUBSTRING);
01630   }
01631 
01632 private:
01633   self_type& operator=(const self_type& aString); // NOT IMPLEMENTED
01634 };
01635 
01636 
01641 // PRUnichar
01642 inline
01643 const nsDependentSubstring
01644 Substring( const nsAString& str, PRUint32 startPos )
01645 {
01646   return nsDependentSubstring(str, startPos);
01647 }
01648 
01649 inline
01650 const nsDependentSubstring
01651 Substring( const nsAString& str, PRUint32 startPos, PRUint32 length )
01652 {
01653   return nsDependentSubstring(str, startPos, length);
01654 }
01655 
01656 inline
01657 const nsDependentSubstring
01658 Substring( const PRUnichar* start, const PRUnichar* end )
01659 {
01660   return nsDependentSubstring(start, end - start);
01661 }
01662 
01663 inline
01664 const nsDependentSubstring
01665 Substring( const PRUnichar* start, PRUint32 length )
01666 {
01667   return nsDependentSubstring(start, length);
01668 }
01669 
01670 inline
01671 const nsDependentSubstring
01672 StringHead( const nsAString& str, PRUint32 count )
01673 {
01674   return nsDependentSubstring(str, 0, count);
01675 }
01676 
01677 inline
01678 const nsDependentSubstring
01679 StringTail( const nsAString& str, PRUint32 count )
01680 {
01681   return nsDependentSubstring(str, str.Length() - count, count);
01682 }
01683 
01684 // char
01685 inline
01686 const nsDependentCSubstring
01687 Substring( const nsACString& str, PRUint32 startPos )
01688 {
01689   return nsDependentCSubstring(str, startPos);
01690 }
01691 
01692 inline
01693 const nsDependentCSubstring
01694 Substring( const nsACString& str, PRUint32 startPos, PRUint32 length )
01695 {
01696   return nsDependentCSubstring(str, startPos, length);
01697 }
01698 
01699 inline
01700 const nsDependentCSubstring
01701 Substring( const char* start, const char* end )
01702 {
01703   return nsDependentCSubstring(start, end - start);
01704 }
01705 
01706 inline
01707 const nsDependentCSubstring
01708 Substring( const char* start, PRUint32 length )
01709 {
01710   return nsDependentCSubstring(start, length);
01711 }
01712 
01713 inline
01714 const nsDependentCSubstring
01715 StringHead( const nsACString& str, PRUint32 count )
01716 {
01717   return nsDependentCSubstring(str, 0, count);
01718 }
01719 
01720 inline
01721 const nsDependentCSubstring
01722 StringTail( const nsACString& str, PRUint32 count )
01723 {
01724   return nsDependentCSubstring(str, str.Length() - count, count);
01725 }
01726 
01727 
01728 /*
01729  * Canonical empty strings
01730  */
01731 
01732 #define EmptyCString() nsCString()
01733 #define EmptyString() nsString()
01734 
01735 #endif // MOZILLA_INTERNAL_API
01736 
01737 #endif // nsStringAPI_h__