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 : 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 : static nsStringBuffer* Realloc(nsStringBuffer* buf, size_t storageSize);
90 :
91 : /**
92 : * Increment the reference count on this string buffer.
93 : */
94 : 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 : 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 34056118 : static nsStringBuffer* FromData(void* data)
108 : {
109 34056118 : return reinterpret_cast<nsStringBuffer*> (data) - 1;
110 : }
111 :
112 : /**
113 : * This method returns the data pointer for this string buffer.
114 : */
115 24013960 : void* Data() const
116 : {
117 24013960 : return const_cast<char*> (reinterpret_cast<const char*> (this + 1));
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 11040777 : PRUint32 StorageSize() const
126 : {
127 11040777 : 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 7182668 : bool IsReadonly() const
139 : {
140 7182668 : 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 : static nsStringBuffer* FromString(const nsAString &str);
152 : 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 : void ToString(PRUint32 len, nsAString &str,
169 : bool aMoveOwnership = false);
170 : void ToString(PRUint32 len, nsACString &str,
171 : bool aMoveOwnership = false);
172 :
173 : /**
174 : * This measures the size. It should only be used if the StringBuffer is
175 : * unshared. This is checked.
176 : */
177 : size_t SizeOfIncludingThisMustBeUnshared(nsMallocSizeOfFun aMallocSizeOf) const;
178 :
179 : /**
180 : * This measures the size only if the StringBuffer is unshared.
181 : */
182 : size_t SizeOfIncludingThisIfUnshared(nsMallocSizeOfFun aMallocSizeOf) const;
183 : };
184 :
185 : #endif /* !defined(nsStringBuffer_h__ */
|