LCOV - app.info - objdir/dist/include/nsXPCOMStrings.h

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