1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/string/public/nsStringBuffer.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,168 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* vim:set ts=2 sw=2 sts=2 et cindent: */
1.6 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#ifndef nsStringBuffer_h__
1.11 +#define nsStringBuffer_h__
1.12 +
1.13 +#include "mozilla/Atomics.h"
1.14 +#include "mozilla/MemoryReporting.h"
1.15 +
1.16 +template<class T> struct already_AddRefed;
1.17 +
1.18 +/**
1.19 + * This structure precedes the string buffers "we" allocate. It may be the
1.20 + * case that nsTAString::mData does not point to one of these special
1.21 + * buffers. The mFlags member variable distinguishes the buffer type.
1.22 + *
1.23 + * When this header is in use, it enables reference counting, and capacity
1.24 + * tracking. NOTE: A string buffer can be modified only if its reference
1.25 + * count is 1.
1.26 + */
1.27 +class nsStringBuffer
1.28 + {
1.29 + private:
1.30 + friend class CheckStaticAtomSizes;
1.31 +
1.32 + mozilla::Atomic<int32_t> mRefCount;
1.33 + uint32_t mStorageSize;
1.34 +
1.35 + public:
1.36 +
1.37 + /**
1.38 + * Allocates a new string buffer, with given size in bytes and a
1.39 + * reference count of one. When the string buffer is no longer needed,
1.40 + * it should be released via Release.
1.41 + *
1.42 + * It is up to the caller to set the bytes corresponding to the string
1.43 + * buffer by calling the Data method to fetch the raw data pointer. Care
1.44 + * must be taken to properly null terminate the character array. The
1.45 + * storage size can be greater than the length of the actual string
1.46 + * (i.e., it is not required that the null terminator appear in the last
1.47 + * storage unit of the string buffer's data).
1.48 + *
1.49 + * @return new string buffer or null if out of memory.
1.50 + */
1.51 + static already_AddRefed<nsStringBuffer> Alloc(size_t storageSize);
1.52 +
1.53 + /**
1.54 + * Resizes the given string buffer to the specified storage size. This
1.55 + * method must not be called on a readonly string buffer. Use this API
1.56 + * carefully!!
1.57 + *
1.58 + * This method behaves like the ANSI-C realloc function. (i.e., If the
1.59 + * allocation fails, null will be returned and the given string buffer
1.60 + * will remain unmodified.)
1.61 + *
1.62 + * @see IsReadonly
1.63 + */
1.64 + static nsStringBuffer* Realloc(nsStringBuffer* buf, size_t storageSize);
1.65 +
1.66 + /**
1.67 + * Increment the reference count on this string buffer.
1.68 + */
1.69 + void NS_FASTCALL AddRef();
1.70 +
1.71 + /**
1.72 + * Decrement the reference count on this string buffer. The string
1.73 + * buffer will be destroyed when its reference count reaches zero.
1.74 + */
1.75 + void NS_FASTCALL Release();
1.76 +
1.77 + /**
1.78 + * This method returns the string buffer corresponding to the given data
1.79 + * pointer. The data pointer must have been returned previously by a
1.80 + * call to the nsStringBuffer::Data method.
1.81 + */
1.82 + static nsStringBuffer* FromData(void* data)
1.83 + {
1.84 + return reinterpret_cast<nsStringBuffer*> (data) - 1;
1.85 + }
1.86 +
1.87 + /**
1.88 + * This method returns the data pointer for this string buffer.
1.89 + */
1.90 + void* Data() const
1.91 + {
1.92 + return const_cast<char*> (reinterpret_cast<const char*> (this + 1));
1.93 + }
1.94 +
1.95 + /**
1.96 + * This function returns the storage size of a string buffer in bytes.
1.97 + * This value is the same value that was originally passed to Alloc (or
1.98 + * Realloc).
1.99 + */
1.100 + uint32_t StorageSize() const
1.101 + {
1.102 + return mStorageSize;
1.103 + }
1.104 +
1.105 + /**
1.106 + * If this method returns false, then the caller can be sure that their
1.107 + * reference to the string buffer is the only reference to the string
1.108 + * buffer, and therefore it has exclusive access to the string buffer and
1.109 + * associated data. However, if this function returns true, then other
1.110 + * consumers may rely on the data in this buffer being immutable and
1.111 + * other threads may access this buffer simultaneously.
1.112 + */
1.113 + bool IsReadonly() const
1.114 + {
1.115 + return mRefCount > 1;
1.116 + }
1.117 +
1.118 + /**
1.119 + * The FromString methods return a string buffer for the given string
1.120 + * object or null if the string object does not have a string buffer.
1.121 + * The reference count of the string buffer is NOT incremented by these
1.122 + * methods. If the caller wishes to hold onto the returned value, then
1.123 + * the returned string buffer must have its reference count incremented
1.124 + * via a call to the AddRef method.
1.125 + */
1.126 + static nsStringBuffer* FromString(const nsAString &str);
1.127 + static nsStringBuffer* FromString(const nsACString &str);
1.128 +
1.129 + /**
1.130 + * The ToString methods assign this string buffer to a given string
1.131 + * object. If the string object does not support sharable string
1.132 + * buffers, then its value will be set to a copy of the given string
1.133 + * buffer. Otherwise, these methods increment the reference count of the
1.134 + * given string buffer. It is important to specify the length (in
1.135 + * storage units) of the string contained in the string buffer since the
1.136 + * length of the string may be less than its storage size. The string
1.137 + * must have a null terminator at the offset specified by |len|.
1.138 + *
1.139 + * NOTE: storage size is measured in bytes even for wide strings;
1.140 + * however, string length is always measured in storage units
1.141 + * (2-byte units for wide strings).
1.142 + */
1.143 + void ToString(uint32_t len, nsAString &str,
1.144 + bool aMoveOwnership = false);
1.145 + void ToString(uint32_t len, nsACString &str,
1.146 + bool aMoveOwnership = false);
1.147 +
1.148 + /**
1.149 + * This measures the size. It should only be used if the StringBuffer is
1.150 + * unshared. This is checked.
1.151 + */
1.152 + size_t SizeOfIncludingThisMustBeUnshared(mozilla::MallocSizeOf aMallocSizeOf) const;
1.153 +
1.154 + /**
1.155 + * This measures the size only if the StringBuffer is unshared.
1.156 + */
1.157 + size_t SizeOfIncludingThisIfUnshared(mozilla::MallocSizeOf aMallocSizeOf) const;
1.158 +
1.159 + /**
1.160 + * This measures the size regardless of whether the StringBuffer is
1.161 + * unshared.
1.162 + *
1.163 + * WARNING: Only use this if you really know what you are doing, because
1.164 + * it can easily lead to double-counting strings. If you do use them,
1.165 + * please explain clearly in a comment why it's safe and won't lead to
1.166 + * double-counting.
1.167 + */
1.168 + size_t SizeOfIncludingThisEvenIfShared(mozilla::MallocSizeOf aMallocSizeOf) const;
1.169 + };
1.170 +
1.171 +#endif /* !defined(nsStringBuffer_h__ */
