The Tor Browser: xpcom/string/public/nsStringBuffer.h@b8a032363ba2

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

     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 /* This Source Code Form is subject to the terms of the Mozilla Public

     4  * License, v. 2.0. If a copy of the MPL was not distributed with this

     5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

     7 #ifndef nsStringBuffer_h__

     8 #define nsStringBuffer_h__

    10 #include "mozilla/Atomics.h"

    11 #include "mozilla/MemoryReporting.h"

    13 template<class T> struct already_AddRefed;

    15 /**

    16  * This structure precedes the string buffers "we" allocate.  It may be the

    17  * case that nsTAString::mData does not point to one of these special

    18  * buffers.  The mFlags member variable distinguishes the buffer type.

    19  *

    20  * When this header is in use, it enables reference counting, and capacity

    21  * tracking.  NOTE: A string buffer can be modified only if its reference

    22  * count is 1.

    23  */

    24 class nsStringBuffer

    25   {

    26     private:

    27       friend class CheckStaticAtomSizes;

    29       mozilla::Atomic<int32_t> mRefCount;

    30       uint32_t mStorageSize;

    32     public:

    34       /**

    35        * Allocates a new string buffer, with given size in bytes and a

    36        * reference count of one.  When the string buffer is no longer needed,

    37        * it should be released via Release.

    38        *

    39        * It is up to the caller to set the bytes corresponding to the string

    40        * buffer by calling the Data method to fetch the raw data pointer.  Care

    41        * must be taken to properly null terminate the character array.  The

    42        * storage size can be greater than the length of the actual string

    43        * (i.e., it is not required that the null terminator appear in the last

    44        * storage unit of the string buffer's data).

    45        *

    46        * @return new string buffer or null if out of memory.

    47        */

    48       static already_AddRefed<nsStringBuffer> Alloc(size_t storageSize);

    50       /**

    51        * Resizes the given string buffer to the specified storage size.  This

    52        * method must not be called on a readonly string buffer.  Use this API

    53        * carefully!!

    54        *

    55        * This method behaves like the ANSI-C realloc function.  (i.e., If the

    56        * allocation fails, null will be returned and the given string buffer

    57        * will remain unmodified.)

    58        *

    59        * @see IsReadonly

    60        */

    61       static nsStringBuffer* Realloc(nsStringBuffer* buf, size_t storageSize);

    63       /**

    64        * Increment the reference count on this string buffer.

    65        */

    66       void NS_FASTCALL AddRef();

    68       /**

    69        * Decrement the reference count on this string buffer.  The string

    70        * buffer will be destroyed when its reference count reaches zero.

    71        */

    72       void NS_FASTCALL Release();

    74       /**

    75        * This method returns the string buffer corresponding to the given data

    76        * pointer.  The data pointer must have been returned previously by a

    77        * call to the nsStringBuffer::Data method.

    78        */

    79       static nsStringBuffer* FromData(void* data)

    80         {

    81           return reinterpret_cast<nsStringBuffer*> (data) - 1;

    82         }

    84       /**

    85        * This method returns the data pointer for this string buffer.

    86        */

    87       void* Data() const

    88         {

    89           return const_cast<char*> (reinterpret_cast<const char*> (this + 1));

    90         }

    92       /**

    93        * This function returns the storage size of a string buffer in bytes.

    94        * This value is the same value that was originally passed to Alloc (or

    95        * Realloc).

    96        */

    97       uint32_t StorageSize() const

    98         {

    99           return mStorageSize;

   100         }

   102       /**

   103        * If this method returns false, then the caller can be sure that their

   104        * reference to the string buffer is the only reference to the string

   105        * buffer, and therefore it has exclusive access to the string buffer and

   106        * associated data.  However, if this function returns true, then other

   107        * consumers may rely on the data in this buffer being immutable and

   108        * other threads may access this buffer simultaneously.

   109        */

   110       bool IsReadonly() const

   111         {

   112           return mRefCount > 1;

   113         }

   115       /**

   116        * The FromString methods return a string buffer for the given string

   117        * object or null if the string object does not have a string buffer.

   118        * The reference count of the string buffer is NOT incremented by these

   119        * methods.  If the caller wishes to hold onto the returned value, then

   120        * the returned string buffer must have its reference count incremented

   121        * via a call to the AddRef method.

   122        */

   123       static nsStringBuffer* FromString(const nsAString &str);

   124       static nsStringBuffer* FromString(const nsACString &str);

   126       /**

   127        * The ToString methods assign this string buffer to a given string

   128        * object.  If the string object does not support sharable string

   129        * buffers, then its value will be set to a copy of the given string

   130        * buffer.  Otherwise, these methods increment the reference count of the

   131        * given string buffer.  It is important to specify the length (in

   132        * storage units) of the string contained in the string buffer since the

   133        * length of the string may be less than its storage size.  The string

   134        * must have a null terminator at the offset specified by |len|.

   135        *

   136        * NOTE: storage size is measured in bytes even for wide strings;

   137        *       however, string length is always measured in storage units

   138        *       (2-byte units for wide strings).

   139        */

   140       void ToString(uint32_t len, nsAString &str,

   141                            bool aMoveOwnership = false);

   142       void ToString(uint32_t len, nsACString &str,

   143                            bool aMoveOwnership = false);

   145       /**

   146        * This measures the size.  It should only be used if the StringBuffer is

   147        * unshared.  This is checked.

   148        */

   149       size_t SizeOfIncludingThisMustBeUnshared(mozilla::MallocSizeOf aMallocSizeOf) const;

   151       /**

   152        * This measures the size only if the StringBuffer is unshared.

   153        */

   154       size_t SizeOfIncludingThisIfUnshared(mozilla::MallocSizeOf aMallocSizeOf) const;

   156       /**

   157        * This measures the size regardless of whether the StringBuffer is

   158        * unshared.

   159        *

   160        * WARNING: Only use this if you really know what you are doing, because

   161        * it can easily lead to double-counting strings.  If you do use them,

   162        * please explain clearly in a comment why it's safe and won't lead to

   163        * double-counting.

   164        */

   165       size_t SizeOfIncludingThisEvenIfShared(mozilla::MallocSizeOf aMallocSizeOf) const;

   166   };

   168 #endif /* !defined(nsStringBuffer_h__ */

The Tor Browser / file revision