LCOV - code coverage report
Current view: directory - objdir/dist/include - nsXPCOMStrings.h (source / functions) Found Hit Coverage
Test: app.info Lines: 5 1 20.0 %
Date: 2012-06-02 Functions: 3 1 33.3 %

       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                 : 
      38                 : #ifndef nsXPCOMStrings_h__
      39                 : #define nsXPCOMStrings_h__
      40                 : 
      41                 : #include <string.h>
      42                 : #include "nscore.h"
      43                 : 
      44                 : /**
      45                 :  * nsXPCOMStrings.h
      46                 :  *
      47                 :  * This file describes a minimal API for working with XPCOM's abstract
      48                 :  * string classes.  It divorces the consumer from having any run-time
      49                 :  * dependency on the implementation details of the abstract string types.
      50                 :  */
      51                 : 
      52                 : // Map frozen functions to private symbol names if not using strict API.
      53                 : #ifdef MOZILLA_INTERNAL_API
      54                 : # define NS_StringContainerInit           NS_StringContainerInit_P
      55                 : # define NS_StringContainerInit2          NS_StringContainerInit2_P
      56                 : # define NS_StringContainerFinish         NS_StringContainerFinish_P
      57                 : # define NS_StringGetData                 NS_StringGetData_P
      58                 : # define NS_StringGetMutableData          NS_StringGetMutableData_P
      59                 : # define NS_StringCloneData               NS_StringCloneData_P
      60                 : # define NS_StringSetData                 NS_StringSetData_P
      61                 : # define NS_StringSetDataRange            NS_StringSetDataRange_P
      62                 : # define NS_StringCopy                    NS_StringCopy_P
      63                 : # define NS_StringSetIsVoid               NS_StringSetIsVoid_P
      64                 : # define NS_StringGetIsVoid               NS_StringGetIsVoid_P
      65                 : # define NS_CStringContainerInit          NS_CStringContainerInit_P
      66                 : # define NS_CStringContainerInit2         NS_CStringContainerInit2_P
      67                 : # define NS_CStringContainerFinish        NS_CStringContainerFinish_P
      68                 : # define NS_CStringGetData                NS_CStringGetData_P
      69                 : # define NS_CStringGetMutableData         NS_CStringGetMutableData_P
      70                 : # define NS_CStringCloneData              NS_CStringCloneData_P
      71                 : # define NS_CStringSetData                NS_CStringSetData_P
      72                 : # define NS_CStringSetDataRange           NS_CStringSetDataRange_P
      73                 : # define NS_CStringCopy                   NS_CStringCopy_P
      74                 : # define NS_CStringSetIsVoid              NS_CStringSetIsVoid_P
      75                 : # define NS_CStringGetIsVoid              NS_CStringGetIsVoid_P
      76                 : # define NS_CStringToUTF16                NS_CStringToUTF16_P
      77                 : # define NS_UTF16ToCString                NS_UTF16ToCString_P
      78                 : #endif
      79                 : 
      80                 : #include "nscore.h"
      81                 : 
      82                 : /* The base string types */
      83                 : class nsAString;
      84                 : class nsACString;
      85                 : 
      86                 : /* ------------------------------------------------------------------------- */
      87                 : 
      88                 : /**
      89                 :  * nsStringContainer
      90                 :  *
      91                 :  * This is an opaque data type that is large enough to hold the canonical
      92                 :  * implementation of nsAString.  The binary structure of this class is an
      93                 :  * implementation detail.
      94                 :  *
      95                 :  * The string data stored in a string container is always single fragment
      96                 :  * and may be null-terminated depending on how it is initialized.
      97                 :  *
      98                 :  * Typically, string containers are allocated on the stack for temporary
      99                 :  * use.  However, they can also be malloc'd if necessary.  In either case,
     100                 :  * a string container is not useful until it has been initialized with a
     101                 :  * call to NS_StringContainerInit.  The following example shows how to use
     102                 :  * a string container to call a function that takes a |nsAString &| out-param.
     103                 :  *
     104                 :  *   NS_METHOD GetBlah(nsAString &aBlah);
     105                 :  *
     106                 :  *   nsresult MyCode()
     107                 :  *   {
     108                 :  *     nsresult rv;
     109                 :  *
     110                 :  *     nsStringContainer sc;
     111                 :  *     rv = NS_StringContainerInit(sc);
     112                 :  *     if (NS_FAILED(rv))
     113                 :  *       return rv;
     114                 :  *
     115                 :  *     rv = GetBlah(sc);
     116                 :  *     if (NS_SUCCEEDED(rv))
     117                 :  *     {
     118                 :  *       const PRUnichar *data;
     119                 :  *       NS_StringGetData(sc, &data);
     120                 :  *       //
     121                 :  *       // |data| now points to the result of the GetBlah function
     122                 :  *       //
     123                 :  *     }
     124                 :  *
     125                 :  *     NS_StringContainerFinish(sc);
     126                 :  *     return rv;
     127                 :  *   }
     128                 :  *
     129                 :  * The following example show how to use a string container to pass a string
     130                 :  * parameter to a function taking a |const nsAString &| in-param.
     131                 :  *
     132                 :  *   NS_METHOD SetBlah(const nsAString &aBlah);
     133                 :  *
     134                 :  *   nsresult MyCode()
     135                 :  *   {
     136                 :  *     nsresult rv;
     137                 :  *
     138                 :  *     nsStringContainer sc;
     139                 :  *     rv = NS_StringContainerInit(sc);
     140                 :  *     if (NS_FAILED(rv))
     141                 :  *       return rv;
     142                 :  *
     143                 :  *     const PRUnichar kData[] = {'x','y','z','\0'};
     144                 :  *     rv = NS_StringSetData(sc, kData, sizeof(kData)/2 - 1);
     145                 :  *     if (NS_SUCCEEDED(rv))
     146                 :  *       rv = SetBlah(sc);
     147                 :  *
     148                 :  *     NS_StringContainerFinish(sc);
     149                 :  *     return rv;
     150                 :  *   }
     151                 :  */
     152                 : class nsStringContainer;
     153                 : 
     154                 : struct nsStringContainer_base
     155           22346 : {
     156                 : private:
     157                 :   void *d1;
     158                 :   PRUint32 d2;
     159                 :   PRUint32 d3;
     160                 : };
     161                 : 
     162                 : /**
     163                 :  * Flags that may be OR'd together to pass to NS_StringContainerInit2:
     164                 :  */
     165                 : enum {
     166                 :   /* Data passed into NS_StringContainerInit2 is not copied; instead, the
     167                 :    * string references the passed in data pointer directly.  The caller must
     168                 :    * ensure that the data is valid for the lifetime of the string container.
     169                 :    * This flag should not be combined with NS_STRING_CONTAINER_INIT_ADOPT. */
     170                 :   NS_STRING_CONTAINER_INIT_DEPEND    = (1 << 1),
     171                 : 
     172                 :   /* Data passed into NS_StringContainerInit2 is not copied; instead, the
     173                 :    * string takes ownership over the data pointer.  The caller must have
     174                 :    * allocated the data array using the XPCOM memory allocator (nsMemory).
     175                 :    * This flag should not be combined with NS_STRING_CONTAINER_INIT_DEPEND. */
     176                 :   NS_STRING_CONTAINER_INIT_ADOPT     = (1 << 2),
     177                 : 
     178                 :   /* Data passed into NS_StringContainerInit2 is a substring that is not
     179                 :    * null-terminated. */
     180                 :   NS_STRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
     181                 : };
     182                 : 
     183                 : /**
     184                 :  * NS_StringContainerInit
     185                 :  *
     186                 :  * @param aContainer    string container reference
     187                 :  * @return              NS_OK if string container successfully initialized
     188                 :  *
     189                 :  * This function may allocate additional memory for aContainer.  When
     190                 :  * aContainer is no longer needed, NS_StringContainerFinish should be called.
     191                 :  */
     192                 : XPCOM_API(nsresult)
     193                 : NS_StringContainerInit(nsStringContainer &aContainer);
     194                 : 
     195                 : /**
     196                 :  * NS_StringContainerInit2
     197                 :  *
     198                 :  * @param aContainer    string container reference
     199                 :  * @param aData         character buffer (may be null)
     200                 :  * @param aDataLength   number of characters stored at aData (may pass
     201                 :  *                      PR_UINT32_MAX if aData is null-terminated)
     202                 :  * @param aFlags        flags affecting how the string container is
     203                 :  *                      initialized.  this parameter is ignored when aData
     204                 :  *                      is null.  otherwise, if this parameter is 0, then
     205                 :  *                      aData is copied into the string.
     206                 :  *
     207                 :  * This function resembles NS_StringContainerInit but provides further
     208                 :  * options that permit more efficient memory usage.  When aContainer is
     209                 :  * no longer needed, NS_StringContainerFinish should be called.
     210                 :  *
     211                 :  * NOTE: NS_StringContainerInit2(container, nsnull, 0, 0) is equivalent to
     212                 :  * NS_StringContainerInit(container).
     213                 :  */
     214                 : XPCOM_API(nsresult)
     215                 : NS_StringContainerInit2
     216                 :   (nsStringContainer &aContainer, const PRUnichar *aData = nsnull,
     217                 :    PRUint32 aDataLength = PR_UINT32_MAX, PRUint32 aFlags = 0);
     218                 : 
     219                 : /**
     220                 :  * NS_StringContainerFinish
     221                 :  *
     222                 :  * @param aContainer    string container reference
     223                 :  *
     224                 :  * This function frees any memory owned by aContainer.
     225                 :  */
     226                 : XPCOM_API(void)
     227                 : NS_StringContainerFinish(nsStringContainer &aContainer);
     228                 : 
     229                 : /* ------------------------------------------------------------------------- */
     230                 : 
     231                 : /**
     232                 :  * NS_StringGetData
     233                 :  *
     234                 :  * This function returns a const character pointer to the string's internal
     235                 :  * buffer, the length of the string, and a boolean value indicating whether
     236                 :  * or not the buffer is null-terminated.
     237                 :  *
     238                 :  * @param aStr          abstract string reference
     239                 :  * @param aData         out param that will hold the address of aStr's
     240                 :  *                      internal buffer
     241                 :  * @param aTerminated   if non-null, this out param will be set to indicate
     242                 :  *                      whether or not aStr's internal buffer is null-
     243                 :  *                      terminated
     244                 :  * @return              length of aStr's internal buffer
     245                 :  */
     246                 : XPCOM_API(PRUint32)
     247                 : NS_StringGetData
     248                 :   (const nsAString &aStr, const PRUnichar **aData,
     249                 :    bool *aTerminated = nsnull);
     250                 : 
     251                 : /**
     252                 :  * NS_StringGetMutableData
     253                 :  *
     254                 :  * This function provides mutable access to a string's internal buffer.  It
     255                 :  * returns a pointer to an array of characters that may be modified.  The
     256                 :  * returned pointer remains valid until the string object is passed to some
     257                 :  * other string function.
     258                 :  *
     259                 :  * Optionally, this function may be used to resize the string's internal
     260                 :  * buffer.  The aDataLength parameter specifies the requested length of the
     261                 :  * string's internal buffer.  By passing some value other than PR_UINT32_MAX,
     262                 :  * the caller can request that the buffer be resized to the specified number of
     263                 :  * characters before returning.  The caller is not responsible for writing a
     264                 :  * null-terminator.
     265                 :  *
     266                 :  * @param aStr          abstract string reference
     267                 :  * @param aDataLength   number of characters to resize the string's internal
     268                 :  *                      buffer to or PR_UINT32_MAX if no resizing is needed
     269                 :  * @param aData         out param that upon return holds the address of aStr's
     270                 :  *                      internal buffer or null if the function failed
     271                 :  * @return              number of characters or zero if the function failed
     272                 :  *
     273                 :  * This function does not necessarily null-terminate aStr after resizing its
     274                 :  * internal buffer.  The behavior depends on the implementation of the abstract
     275                 :  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
     276                 :  * will be null-terminated by this function.
     277                 :  */
     278                 : XPCOM_API(PRUint32)
     279                 : NS_StringGetMutableData
     280                 :   (nsAString &aStr, PRUint32 aDataLength, PRUnichar **aData);
     281                 : 
     282                 : /**
     283                 :  * NS_StringCloneData
     284                 :  *
     285                 :  * This function returns a null-terminated copy of the string's
     286                 :  * internal buffer.
     287                 :  *
     288                 :  * @param aStr          abstract string reference
     289                 :  * @return              null-terminated copy of the string's internal buffer
     290                 :  *                      (it must be free'd using using nsMemory::Free)
     291                 :  */
     292                 : XPCOM_API(PRUnichar *)
     293                 : NS_StringCloneData
     294                 :   (const nsAString &aStr);
     295                 : 
     296                 : /**
     297                 :  * NS_StringSetData
     298                 :  *
     299                 :  * This function copies aData into aStr.
     300                 :  *
     301                 :  * @param aStr          abstract string reference
     302                 :  * @param aData         character buffer
     303                 :  * @param aDataLength   number of characters to copy from source string (pass
     304                 :  *                      PR_UINT32_MAX to copy until end of aData, designated by
     305                 :  *                      a null character)
     306                 :  * @return              NS_OK if function succeeded
     307                 :  *
     308                 :  * This function does not necessarily null-terminate aStr after copying data
     309                 :  * from aData.  The behavior depends on the implementation of the abstract
     310                 :  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
     311                 :  * will be null-terminated by this function.
     312                 :  */
     313                 : XPCOM_API(nsresult)
     314                 : NS_StringSetData
     315                 :   (nsAString &aStr, const PRUnichar *aData,
     316                 :    PRUint32 aDataLength = PR_UINT32_MAX);
     317                 : 
     318                 : /**
     319                 :  * NS_StringSetDataRange
     320                 :  *
     321                 :  * This function copies aData into a section of aStr.  As a result it can be
     322                 :  * used to insert new characters into the string.
     323                 :  *
     324                 :  * @param aStr          abstract string reference
     325                 :  * @param aCutOffset    starting index where the string's existing data
     326                 :  *                      is to be overwritten (pass PR_UINT32_MAX to cause
     327                 :  *                      aData to be appended to the end of aStr, in which
     328                 :  *                      case the value of aCutLength is ignored).
     329                 :  * @param aCutLength    number of characters to overwrite starting at
     330                 :  *                      aCutOffset (pass PR_UINT32_MAX to overwrite until the
     331                 :  *                      end of aStr).
     332                 :  * @param aData         character buffer (pass null to cause this function
     333                 :  *                      to simply remove the "cut" range)
     334                 :  * @param aDataLength   number of characters to copy from source string (pass
     335                 :  *                      PR_UINT32_MAX to copy until end of aData, designated by
     336                 :  *                      a null character)
     337                 :  * @return              NS_OK if function succeeded
     338                 :  *
     339                 :  * This function does not necessarily null-terminate aStr after copying data
     340                 :  * from aData.  The behavior depends on the implementation of the abstract
     341                 :  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
     342                 :  * will be null-terminated by this function.
     343                 :  */
     344                 : XPCOM_API(nsresult)
     345                 : NS_StringSetDataRange
     346                 :   (nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
     347                 :    const PRUnichar *aData, PRUint32 aDataLength = PR_UINT32_MAX);
     348                 : 
     349                 : /**
     350                 :  * NS_StringCopy
     351                 :  *
     352                 :  * This function makes aDestStr have the same value as aSrcStr.  It is
     353                 :  * provided as an optimization.
     354                 :  *
     355                 :  * @param aDestStr      abstract string reference to be modified
     356                 :  * @param aSrcStr       abstract string reference containing source string
     357                 :  * @return              NS_OK if function succeeded
     358                 :  *
     359                 :  * This function does not necessarily null-terminate aDestStr after copying
     360                 :  * data from aSrcStr.  The behavior depends on the implementation of the
     361                 :  * abstract string, aDestStr.  If aDestStr is a reference to a
     362                 :  * nsStringContainer, then its data will be null-terminated by this function.
     363                 :  */
     364                 : XPCOM_API(nsresult)
     365                 : NS_StringCopy
     366                 :   (nsAString &aDestStr, const nsAString &aSrcStr);
     367                 : 
     368                 : /**
     369                 :  * NS_StringAppendData
     370                 :  *
     371                 :  * This function appends data to the existing value of aStr.
     372                 :  *
     373                 :  * @param aStr          abstract string reference to be modified
     374                 :  * @param aData         character buffer
     375                 :  * @param aDataLength   number of characters to append (pass PR_UINT32_MAX to
     376                 :  *                      append until a null-character is encountered)
     377                 :  * @return              NS_OK if function succeeded
     378                 :  *
     379                 :  * This function does not necessarily null-terminate aStr upon completion.
     380                 :  * The behavior depends on the implementation of the abstract string, aStr.
     381                 :  * If aStr is a reference to a nsStringContainer, then its data will be null-
     382                 :  * terminated by this function.
     383                 :  */
     384                 : inline NS_HIDDEN_(nsresult)
     385                 : NS_StringAppendData(nsAString &aStr, const PRUnichar *aData,
     386                 :                     PRUint32 aDataLength = PR_UINT32_MAX)
     387                 : {
     388                 :   return NS_StringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
     389                 : }
     390                 : 
     391                 : /**
     392                 :  * NS_StringInsertData
     393                 :  *
     394                 :  * This function inserts data into the existing value of aStr at the specified
     395                 :  * offset.
     396                 :  *
     397                 :  * @param aStr          abstract string reference to be modified
     398                 :  * @param aOffset       specifies where in the string to insert aData
     399                 :  * @param aData         character buffer
     400                 :  * @param aDataLength   number of characters to append (pass PR_UINT32_MAX to
     401                 :  *                      append until a null-character is encountered)
     402                 :  * @return              NS_OK if function succeeded
     403                 :  *
     404                 :  * This function does not necessarily null-terminate aStr upon completion.
     405                 :  * The behavior depends on the implementation of the abstract string, aStr.
     406                 :  * If aStr is a reference to a nsStringContainer, then its data will be null-
     407                 :  * terminated by this function.
     408                 :  */
     409                 : inline NS_HIDDEN_(nsresult)
     410                 : NS_StringInsertData(nsAString &aStr, PRUint32 aOffset, const PRUnichar *aData,
     411                 :                     PRUint32 aDataLength = PR_UINT32_MAX)
     412                 : {
     413                 :   return NS_StringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
     414                 : }
     415                 : 
     416                 : /**
     417                 :  * NS_StringCutData
     418                 :  *
     419                 :  * This function shortens the existing value of aStr, by removing characters
     420                 :  * at the specified offset.
     421                 :  *
     422                 :  * @param aStr          abstract string reference to be modified
     423                 :  * @param aCutOffset    specifies where in the string to insert aData
     424                 :  * @param aCutLength    number of characters to remove
     425                 :  * @return              NS_OK if function succeeded
     426                 :  */
     427                 : inline NS_HIDDEN_(nsresult)
     428               0 : NS_StringCutData(nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
     429                 : {
     430               0 :   return NS_StringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
     431                 : }
     432                 : 
     433                 : /**
     434                 :  * NS_StringSetIsVoid
     435                 :  *
     436                 :  * This function marks a string as being a "void string".  Any data in the
     437                 :  * string will be lost.
     438                 :  */
     439                 : XPCOM_API(void)
     440                 : NS_StringSetIsVoid(nsAString& aStr, const bool aIsVoid);
     441                 : 
     442                 : /**
     443                 :  * NS_StringGetIsVoid
     444                 :  *
     445                 :  * This function provides a way to test if a string is a "void string", as
     446                 :  * marked by NS_StringSetIsVoid.
     447                 :  */
     448                 : XPCOM_API(bool)
     449                 : NS_StringGetIsVoid(const nsAString& aStr);
     450                 : 
     451                 : /* ------------------------------------------------------------------------- */
     452                 : 
     453                 : /**
     454                 :  * nsCStringContainer
     455                 :  *
     456                 :  * This is an opaque data type that is large enough to hold the canonical
     457                 :  * implementation of nsACString.  The binary structure of this class is an
     458                 :  * implementation detail.
     459                 :  *
     460                 :  * The string data stored in a string container is always single fragment
     461                 :  * and may be null-terminated depending on how it is initialized.
     462                 :  *
     463                 :  * @see nsStringContainer for use cases and further documentation.
     464                 :  */
     465                 : class nsCStringContainer;
     466                 : 
     467                 : /**
     468                 :  * Flags that may be OR'd together to pass to NS_StringContainerInit2:
     469                 :  */
     470                 : enum {
     471                 :   /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
     472                 :    * string references the passed in data pointer directly.  The caller must
     473                 :    * ensure that the data is valid for the lifetime of the string container.
     474                 :    * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_ADOPT. */
     475                 :   NS_CSTRING_CONTAINER_INIT_DEPEND    = (1 << 1),
     476                 : 
     477                 :   /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
     478                 :    * string takes ownership over the data pointer.  The caller must have
     479                 :    * allocated the data array using the XPCOM memory allocator (nsMemory).
     480                 :    * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_DEPEND. */
     481                 :   NS_CSTRING_CONTAINER_INIT_ADOPT     = (1 << 2),
     482                 : 
     483                 :   /* Data passed into NS_CStringContainerInit2 is a substring that is not
     484                 :    * null-terminated. */
     485                 :   NS_CSTRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
     486                 : };
     487                 : 
     488                 : /**
     489                 :  * NS_CStringContainerInit
     490                 :  *
     491                 :  * @param aContainer    string container reference
     492                 :  * @return              NS_OK if string container successfully initialized
     493                 :  *
     494                 :  * This function may allocate additional memory for aContainer.  When
     495                 :  * aContainer is no longer needed, NS_CStringContainerFinish should be called.
     496                 :  */
     497                 : XPCOM_API(nsresult)
     498                 : NS_CStringContainerInit(nsCStringContainer &aContainer);
     499                 : 
     500                 : /**
     501                 :  * NS_CStringContainerInit2
     502                 :  *
     503                 :  * @param aContainer    string container reference
     504                 :  * @param aData         character buffer (may be null)
     505                 :  * @param aDataLength   number of characters stored at aData (may pass
     506                 :  *                      PR_UINT32_MAX if aData is null-terminated)
     507                 :  * @param aFlags        flags affecting how the string container is
     508                 :  *                      initialized.  this parameter is ignored when aData
     509                 :  *                      is null.  otherwise, if this parameter is 0, then
     510                 :  *                      aData is copied into the string.
     511                 :  *
     512                 :  * This function resembles NS_CStringContainerInit but provides further
     513                 :  * options that permit more efficient memory usage.  When aContainer is
     514                 :  * no longer needed, NS_CStringContainerFinish should be called.
     515                 :  *
     516                 :  * NOTE: NS_CStringContainerInit2(container, nsnull, 0, 0) is equivalent to
     517                 :  * NS_CStringContainerInit(container).
     518                 :  */
     519                 : XPCOM_API(nsresult)
     520                 : NS_CStringContainerInit2
     521                 :   (nsCStringContainer &aContainer, const char *aData = nsnull,
     522                 :    PRUint32 aDataLength = PR_UINT32_MAX, PRUint32 aFlags = 0);
     523                 : 
     524                 : /**
     525                 :  * NS_CStringContainerFinish
     526                 :  *
     527                 :  * @param aContainer    string container reference
     528                 :  *
     529                 :  * This function frees any memory owned by aContainer.
     530                 :  */
     531                 : XPCOM_API(void)
     532                 : NS_CStringContainerFinish(nsCStringContainer &aContainer);
     533                 : 
     534                 : /* ------------------------------------------------------------------------- */
     535                 : 
     536                 : /**
     537                 :  * NS_CStringGetData
     538                 :  *
     539                 :  * This function returns a const character pointer to the string's internal
     540                 :  * buffer, the length of the string, and a boolean value indicating whether
     541                 :  * or not the buffer is null-terminated.
     542                 :  *
     543                 :  * @param aStr          abstract string reference
     544                 :  * @param aData         out param that will hold the address of aStr's
     545                 :  *                      internal buffer
     546                 :  * @param aTerminated   if non-null, this out param will be set to indicate
     547                 :  *                      whether or not aStr's internal buffer is null-
     548                 :  *                      terminated
     549                 :  * @return              length of aStr's internal buffer
     550                 :  */
     551                 : XPCOM_API(PRUint32)
     552                 : NS_CStringGetData
     553                 :   (const nsACString &aStr, const char **aData,
     554                 :    bool *aTerminated = nsnull);
     555                 : 
     556                 : /**
     557                 :  * NS_CStringGetMutableData
     558                 :  *
     559                 :  * This function provides mutable access to a string's internal buffer.  It
     560                 :  * returns a pointer to an array of characters that may be modified.  The
     561                 :  * returned pointer remains valid until the string object is passed to some
     562                 :  * other string function.
     563                 :  *
     564                 :  * Optionally, this function may be used to resize the string's internal
     565                 :  * buffer.  The aDataLength parameter specifies the requested length of the
     566                 :  * string's internal buffer.  By passing some value other than PR_UINT32_MAX,
     567                 :  * the caller can request that the buffer be resized to the specified number of
     568                 :  * characters before returning.  The caller is not responsible for writing a
     569                 :  * null-terminator.
     570                 :  *
     571                 :  * @param aStr          abstract string reference
     572                 :  * @param aDataLength   number of characters to resize the string's internal
     573                 :  *                      buffer to or PR_UINT32_MAX if no resizing is needed
     574                 :  * @param aData         out param that upon return holds the address of aStr's
     575                 :  *                      internal buffer or null if the function failed
     576                 :  * @return              number of characters or zero if the function failed
     577                 :  *
     578                 :  * This function does not necessarily null-terminate aStr after resizing its
     579                 :  * internal buffer.  The behavior depends on the implementation of the abstract
     580                 :  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
     581                 :  * will be null-terminated by this function.
     582                 :  */
     583                 : XPCOM_API(PRUint32)
     584                 : NS_CStringGetMutableData
     585                 :   (nsACString &aStr, PRUint32 aDataLength, char **aData);
     586                 : 
     587                 : /**
     588                 :  * NS_CStringCloneData
     589                 :  *
     590                 :  * This function returns a null-terminated copy of the string's
     591                 :  * internal buffer.
     592                 :  *
     593                 :  * @param aStr          abstract string reference
     594                 :  * @return              null-terminated copy of the string's internal buffer
     595                 :  *                      (it must be free'd using using nsMemory::Free)
     596                 :  */
     597                 : XPCOM_API(char *)
     598                 : NS_CStringCloneData
     599                 :   (const nsACString &aStr);
     600                 : 
     601                 : /**
     602                 :  * NS_CStringSetData
     603                 :  *
     604                 :  * This function copies aData into aStr.
     605                 :  *
     606                 :  * @param aStr          abstract string reference
     607                 :  * @param aData         character buffer
     608                 :  * @param aDataLength   number of characters to copy from source string (pass
     609                 :  *                      PR_UINT32_MAX to copy until end of aData, designated by
     610                 :  *                      a null character)
     611                 :  * @return              NS_OK if function succeeded
     612                 :  *
     613                 :  * This function does not necessarily null-terminate aStr after copying data
     614                 :  * from aData.  The behavior depends on the implementation of the abstract
     615                 :  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
     616                 :  * will be null-terminated by this function.
     617                 :  */
     618                 : XPCOM_API(nsresult)
     619                 : NS_CStringSetData
     620                 :   (nsACString &aStr, const char *aData,
     621                 :    PRUint32 aDataLength = PR_UINT32_MAX);
     622                 : 
     623                 : /**
     624                 :  * NS_CStringSetDataRange
     625                 :  *
     626                 :  * This function copies aData into a section of aStr.  As a result it can be
     627                 :  * used to insert new characters into the string.
     628                 :  *
     629                 :  * @param aStr          abstract string reference
     630                 :  * @param aCutOffset    starting index where the string's existing data
     631                 :  *                      is to be overwritten (pass PR_UINT32_MAX to cause
     632                 :  *                      aData to be appended to the end of aStr, in which
     633                 :  *                      case the value of aCutLength is ignored).
     634                 :  * @param aCutLength    number of characters to overwrite starting at
     635                 :  *                      aCutOffset (pass PR_UINT32_MAX to overwrite until the
     636                 :  *                      end of aStr).
     637                 :  * @param aData         character buffer (pass null to cause this function
     638                 :  *                      to simply remove the "cut" range)
     639                 :  * @param aDataLength   number of characters to copy from source string (pass
     640                 :  *                      PR_UINT32_MAX to copy until end of aData, designated by
     641                 :  *                      a null character)
     642                 :  * @return              NS_OK if function succeeded
     643                 :  *
     644                 :  * This function does not necessarily null-terminate aStr after copying data
     645                 :  * from aData.  The behavior depends on the implementation of the abstract
     646                 :  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
     647                 :  * will be null-terminated by this function.
     648                 :  */
     649                 : XPCOM_API(nsresult)
     650                 : NS_CStringSetDataRange
     651                 :   (nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
     652                 :    const char *aData, PRUint32 aDataLength = PR_UINT32_MAX);
     653                 : 
     654                 : /**
     655                 :  * NS_CStringCopy
     656                 :  *
     657                 :  * This function makes aDestStr have the same value as aSrcStr.  It is
     658                 :  * provided as an optimization.
     659                 :  *
     660                 :  * @param aDestStr      abstract string reference to be modified
     661                 :  * @param aSrcStr       abstract string reference containing source string
     662                 :  * @return              NS_OK if function succeeded
     663                 :  *
     664                 :  * This function does not necessarily null-terminate aDestStr after copying
     665                 :  * data from aSrcStr.  The behavior depends on the implementation of the
     666                 :  * abstract string, aDestStr.  If aDestStr is a reference to a
     667                 :  * nsStringContainer, then its data will be null-terminated by this function.
     668                 :  */
     669                 : XPCOM_API(nsresult)
     670                 : NS_CStringCopy
     671                 :   (nsACString &aDestStr, const nsACString &aSrcStr);
     672                 : 
     673                 : /**
     674                 :  * NS_CStringAppendData
     675                 :  *
     676                 :  * This function appends data to the existing value of aStr.
     677                 :  *
     678                 :  * @param aStr          abstract string reference to be modified
     679                 :  * @param aData         character buffer
     680                 :  * @param aDataLength   number of characters to append (pass PR_UINT32_MAX to
     681                 :  *                      append until a null-character is encountered)
     682                 :  * @return              NS_OK if function succeeded
     683                 :  *
     684                 :  * This function does not necessarily null-terminate aStr upon completion.
     685                 :  * The behavior depends on the implementation of the abstract string, aStr.
     686                 :  * If aStr is a reference to a nsStringContainer, then its data will be null-
     687                 :  * terminated by this function.
     688                 :  */
     689                 : inline NS_HIDDEN_(nsresult)
     690                 : NS_CStringAppendData(nsACString &aStr, const char *aData,
     691                 :                     PRUint32 aDataLength = PR_UINT32_MAX)
     692                 : {
     693                 :   return NS_CStringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
     694                 : }
     695                 : 
     696                 : /**
     697                 :  * NS_CStringInsertData
     698                 :  *
     699                 :  * This function inserts data into the existing value of aStr at the specified
     700                 :  * offset.
     701                 :  *
     702                 :  * @param aStr          abstract string reference to be modified
     703                 :  * @param aOffset       specifies where in the string to insert aData
     704                 :  * @param aData         character buffer
     705                 :  * @param aDataLength   number of characters to append (pass PR_UINT32_MAX to
     706                 :  *                      append until a null-character is encountered)
     707                 :  * @return              NS_OK if function succeeded
     708                 :  *
     709                 :  * This function does not necessarily null-terminate aStr upon completion.
     710                 :  * The behavior depends on the implementation of the abstract string, aStr.
     711                 :  * If aStr is a reference to a nsStringContainer, then its data will be null-
     712                 :  * terminated by this function.
     713                 :  */
     714                 : inline NS_HIDDEN_(nsresult)
     715                 : NS_CStringInsertData(nsACString &aStr, PRUint32 aOffset, const char *aData,
     716                 :                     PRUint32 aDataLength = PR_UINT32_MAX)
     717                 : {
     718                 :   return NS_CStringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
     719                 : }
     720                 : 
     721                 : /**
     722                 :  * NS_CStringCutData
     723                 :  *
     724                 :  * This function shortens the existing value of aStr, by removing characters
     725                 :  * at the specified offset.
     726                 :  *
     727                 :  * @param aStr          abstract string reference to be modified
     728                 :  * @param aCutOffset    specifies where in the string to insert aData
     729                 :  * @param aCutLength    number of characters to remove
     730                 :  * @return              NS_OK if function succeeded
     731                 :  */
     732                 : inline NS_HIDDEN_(nsresult)
     733               0 : NS_CStringCutData(nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
     734                 : {
     735               0 :   return NS_CStringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
     736                 : }
     737                 : 
     738                 : /**
     739                 :  * NS_CStringSetIsVoid
     740                 :  *
     741                 :  * This function marks a string as being a "void string".  Any data in the
     742                 :  * string will be lost.
     743                 :  */
     744                 : XPCOM_API(void)
     745                 : NS_CStringSetIsVoid(nsACString& aStr, const bool aIsVoid);
     746                 : 
     747                 : /**
     748                 :  * NS_CStringGetIsVoid
     749                 :  *
     750                 :  * This function provides a way to test if a string is a "void string", as
     751                 :  * marked by NS_CStringSetIsVoid.
     752                 :  */
     753                 : XPCOM_API(bool)
     754                 : NS_CStringGetIsVoid(const nsACString& aStr);
     755                 : 
     756                 : /* ------------------------------------------------------------------------- */
     757                 : 
     758                 : /**
     759                 :  * Encodings that can be used with the following conversion routines.
     760                 :  */
     761                 : enum nsCStringEncoding {
     762                 :   /* Conversion between ASCII and UTF-16 assumes that all bytes in the source
     763                 :    * string are 7-bit ASCII and can be inflated to UTF-16 by inserting null
     764                 :    * bytes.  Reverse conversion is done by truncating every other byte.  The
     765                 :    * conversion may result in loss and/or corruption of information if the
     766                 :    * strings do not strictly contain ASCII data. */
     767                 :   NS_CSTRING_ENCODING_ASCII = 0,
     768                 : 
     769                 :   /* Conversion between UTF-8 and UTF-16 is non-lossy. */
     770                 :   NS_CSTRING_ENCODING_UTF8 = 1,
     771                 : 
     772                 :   /* Conversion from UTF-16 to the native filesystem charset may result in a
     773                 :    * loss of information.  No attempt is made to protect against data loss in
     774                 :    * this case.  The native filesystem charset applies to strings passed to
     775                 :    * the "Native" method variants on nsIFile and nsILocalFile. */
     776                 :   NS_CSTRING_ENCODING_NATIVE_FILESYSTEM = 2
     777                 : };
     778                 : 
     779                 : /**
     780                 :  * NS_CStringToUTF16
     781                 :  *
     782                 :  * This function converts the characters in a nsACString to an array of UTF-16
     783                 :  * characters, in the platform endianness.  The result is stored in a nsAString
     784                 :  * object.
     785                 :  *
     786                 :  * @param aSource       abstract string reference containing source string
     787                 :  * @param aSrcEncoding  character encoding of the source string
     788                 :  * @param aDest         abstract string reference to hold the result
     789                 :  */
     790                 : XPCOM_API(nsresult)
     791                 : NS_CStringToUTF16(const nsACString &aSource, nsCStringEncoding aSrcEncoding,
     792                 :                   nsAString &aDest);
     793                 : 
     794                 : /**
     795                 :  * NS_UTF16ToCString
     796                 :  *
     797                 :  * This function converts the UTF-16 characters in a nsAString to a single-byte
     798                 :  * encoding.  The result is stored in a nsACString object.  In some cases this
     799                 :  * conversion may be lossy.  In such cases, the conversion may succeed with a
     800                 :  * return code indicating loss of information.  The exact behavior is not
     801                 :  * specified at this time.
     802                 :  *
     803                 :  * @param aSource       abstract string reference containing source string
     804                 :  * @param aDestEncoding character encoding of the resulting string
     805                 :  * @param aDest         abstract string reference to hold the result
     806                 :  */
     807                 : XPCOM_API(nsresult)
     808                 : NS_UTF16ToCString(const nsAString &aSource, nsCStringEncoding aDestEncoding,
     809                 :                   nsACString &aDest);
     810                 : 
     811                 : #endif // nsXPCOMStrings_h__

Generated by: LCOV version 1.7