xpcom/string/public/nsStringBuffer.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   3 /* ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Mozilla.
  17  *
  18  * The Initial Developer of the Original Code is IBM Corporation.
  19  * Portions created by IBM Corporation are Copyright (C) 2003
  20  * IBM Corporation. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Darin Fisher <darin@meer.net>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either the GNU General Public License Version 2 or later (the "GPL"), or
  27  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #ifndef nsStringBuffer_h__
  40 #define nsStringBuffer_h__
  41
  42
  43 /**
  44  * This structure precedes the string buffers "we" allocate.  It may be the
  45  * case that nsTAString::mData does not point to one of these special
  46  * buffers.  The mFlags member variable distinguishes the buffer type.
  47  *
  48  * When this header is in use, it enables reference counting, and capacity
  49  * tracking.  NOTE: A string buffer can be modified only if its reference
  50  * count is 1.
  51  */
  52 class nsStringBuffer
  53   {
  54     private:
  55       friend class CheckStaticAtomSizes;
  56
  57       PRInt32  mRefCount;
  58       PRUint32 mStorageSize;
  59
  60     public:
  61
  62       /**
  63        * Allocates a new string buffer, with given size in bytes and a
  64        * reference count of one.  When the string buffer is no longer needed,
  65        * it should be released via Release.
  66        *
  67        * It is up to the caller to set the bytes corresponding to the string
  68        * buffer by calling the Data method to fetch the raw data pointer.  Care
  69        * must be taken to properly null terminate the character array.  The
  70        * storage size can be greater than the length of the actual string
  71        * (i.e., it is not required that the null terminator appear in the last
  72        * storage unit of the string buffer's data).
  73        *
  74        * @return new string buffer or null if out of memory.
  75        */
  76       NS_COM static nsStringBuffer* Alloc(size_t storageSize);
  77
  78       /**
  79        * Resizes the given string buffer to the specified storage size.  This
  80        * method must not be called on a readonly string buffer.  Use this API
  81        * carefully!!
  82        *
  83        * This method behaves like the ANSI-C realloc function.  (i.e., If the
  84        * allocation fails, null will be returned and the given string buffer
  85        * will remain unmodified.)
  86        *
  87        * @see IsReadonly
  88        */
  89       NS_COM static nsStringBuffer* Realloc(nsStringBuffer* buf, size_t storageSize);
  90
  91       /**
  92        * Increment the reference count on this string buffer.
  93        */
  94       NS_COM void NS_FASTCALL AddRef();
  95
  96       /**
  97        * Decrement the reference count on this string buffer.  The string
  98        * buffer will be destroyed when its reference count reaches zero.
  99        */
 100       NS_COM void NS_FASTCALL Release();
 101
 102       /**
 103        * This method returns the string buffer corresponding to the given data
 104        * pointer.  The data pointer must have been returned previously by a
 105        * call to the nsStringBuffer::Data method.
 106        */
 107       static nsStringBuffer* FromData(void* data)
 108         {
 109           return (nsStringBuffer*) ( ((char*) data) - sizeof(nsStringBuffer) );
 110         }
 111
 112       /**
 113        * This method returns the data pointer for this string buffer.
 114        */
 115       void* Data() const
 116         {
 117           return (void*) ( ((char*) this) + sizeof(nsStringBuffer) );
 118         }
 119
 120       /**
 121        * This function returns the storage size of a string buffer in bytes.
 122        * This value is the same value that was originally passed to Alloc (or
 123        * Realloc).
 124        */
 125       PRUint32 StorageSize() const
 126         {
 127           return mStorageSize;
 128         }
 129
 130       /**
 131        * If this method returns false, then the caller can be sure that their
 132        * reference to the string buffer is the only reference to the string
 133        * buffer, and therefore it has exclusive access to the string buffer and
 134        * associated data.  However, if this function returns true, then other
 135        * consumers may rely on the data in this buffer being immutable and
 136        * other threads may access this buffer simultaneously.
 137        */
 138       PRBool IsReadonly() const
 139         {
 140           return mRefCount > 1;
 141         }
 142
 143       /**
 144        * The FromString methods return a string buffer for the given string
 145        * object or null if the string object does not have a string buffer.
 146        * The reference count of the string buffer is NOT incremented by these
 147        * methods.  If the caller wishes to hold onto the returned value, then
 148        * the returned string buffer must have its reference count incremented
 149        * via a call to the AddRef method.
 150        */
 151       NS_COM static nsStringBuffer* FromString(const nsAString &str);
 152       NS_COM static nsStringBuffer* FromString(const nsACString &str);
 153
 154       /**
 155        * The ToString methods assign this string buffer to a given string
 156        * object.  If the string object does not support sharable string
 157        * buffers, then its value will be set to a copy of the given string
 158        * buffer.  Otherwise, these methods increment the reference count of the
 159        * given string buffer.  It is important to specify the length (in
 160        * storage units) of the string contained in the string buffer since the
 161        * length of the string may be less than its storage size.  The string
 162        * must have a null terminator at the offset specified by |len|.
 163        *
 164        * NOTE: storage size is measured in bytes even for wide strings;
 165        *       however, string length is always measured in storage units
 166        *       (2-byte units for wide strings).
 167        */
 168       NS_COM void ToString(PRUint32 len, nsAString &str,
 169                            PRBool aMoveOwnership = PR_FALSE);
 170       NS_COM void ToString(PRUint32 len, nsACString &str,
 171                            PRBool aMoveOwnership = PR_FALSE);
 172   };
 173
 174 #endif /* !defined(nsStringBuffer_h__ */