]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: buffer.h | |
3 | // Purpose: interface of wxMemoryBuffer | |
4 | // Author: wxWidgets team | |
5 | // Licence: wxWindows licence | |
6 | ///////////////////////////////////////////////////////////////////////////// | |
7 | ||
8 | ||
9 | /** | |
10 | wxScopedCharTypeBuffer<T> is a template class for storing characters. | |
11 | ||
12 | Data are stored in reference-counted buffer. In other words, making a copy | |
13 | of wxScopedCharTypeBuffer<T> will @em not make another copy of the stored | |
14 | string data, it will still point to the same location in memory. | |
15 | ||
16 | wxScopedCharTypeBuffer<T> supports two storage modes: owned and non-owned. | |
17 | "Owned" data buffer (created with CreateOwned() or wxCharTypeBuffer<T> | |
18 | derived class) owns the data and frees them when the last buffer pointing | |
19 | to them is destroyed. | |
20 | ||
21 | "Non-owned" buffer (created with CreateNonOwned()), on the other hand, | |
22 | references data owned by somebody else -- typical use is by | |
23 | wxString::mb_str() or wxString::wc_str(), which may return non-owned buffer | |
24 | pointing to wxString's internal store. | |
25 | ||
26 | Because of this, the validity of data stored in wxScopedCharTypeBuffer<T> | |
27 | is limited by the lifetime of the "parent" object that created the | |
28 | buffer (e.g. the wxString on which mb_str() was called). | |
29 | ||
30 | If you need to preserve the data for longer, assign it to | |
31 | wxCharTypeBuffer<T> instead of wxScopedCharTypeBuffer<T>. On the other | |
32 | hand, use wxScopedCharTypeBuffer<T> if the buffer is to be destroyed before | |
33 | the "parent" object -- typical use would be creating it on the stack and | |
34 | destroying when it goes out of scope (hence the class' name). | |
35 | ||
36 | @tparam T | |
37 | The type of the characters stored in this class. | |
38 | ||
39 | @since 2.9.0 | |
40 | ||
41 | @nolibrary | |
42 | @category{data} | |
43 | */ | |
44 | template <typename T> | |
45 | class wxScopedCharTypeBuffer | |
46 | { | |
47 | public: | |
48 | /// Stored characters type. | |
49 | typedef T CharType; | |
50 | ||
51 | /// Default constructor, creates NULL buffer. | |
52 | wxScopedCharTypeBuffer(); | |
53 | ||
54 | /** | |
55 | Creates non-owned buffer from string data @a str. | |
56 | ||
57 | The buffer's destructor will not destroy @a str. The returned buffer's | |
58 | data is valid only as long as @a str is valid. | |
59 | ||
60 | @param str String data. | |
61 | @param len If specified, length of the string, otherwise the string | |
62 | is considered to be NUL-terminated. | |
63 | */ | |
64 | static const wxScopedCharTypeBuffer CreateNonOwned(const CharType *str, size_t len = wxNO_LEN); | |
65 | ||
66 | /** | |
67 | Creates owned buffer from @a str and takes ownership of it. | |
68 | ||
69 | The buffer's destructor will free @a str when its reference count | |
70 | reaches zero (initial count is 1). | |
71 | ||
72 | @param str String data. | |
73 | @param len If specified, length of the string, otherwise the string | |
74 | is considered to be NUL-terminated. | |
75 | */ | |
76 | static const wxScopedCharTypeBuffer CreateOwned(CharType *str, size_t len = wxNO_LEN); | |
77 | ||
78 | /** | |
79 | Copy constructor. | |
80 | ||
81 | Increases reference count on the data, does @em not make wxStrdup() | |
82 | copy of the data. | |
83 | */ | |
84 | wxScopedCharTypeBuffer(const wxScopedCharTypeBuffer& src); | |
85 | ||
86 | /// Assignment operator behaves in the same way as the copy constructor. | |
87 | wxScopedCharTypeBuffer& operator=(const wxScopedCharTypeBuffer& src); | |
88 | ||
89 | /** | |
90 | Destructor. Frees stored data if it is in "owned" mode and data's | |
91 | reference count reaches zero. | |
92 | */ | |
93 | ~wxScopedCharTypeBuffer(); | |
94 | ||
95 | /// Resets the buffer to NULL, freeing the data if necessary. | |
96 | void reset(); | |
97 | ||
98 | /// Returns pointer to the stored data. | |
99 | CharType *data(); | |
100 | ||
101 | /// Returns const pointer to the stored data. | |
102 | const CharType *data() const; | |
103 | ||
104 | /// Returns length of the string stored. | |
105 | size_t length() const; | |
106 | ||
107 | /// Implicit conversion to C string. | |
108 | operator const CharType *() const; | |
109 | ||
110 | /// Random access to the stored C string. | |
111 | CharType operator[](size_t n) const; | |
112 | }; | |
113 | ||
114 | /// Scoped char buffer. | |
115 | typedef wxScopedCharTypeBuffer<char> wxScopedCharBuffer; | |
116 | ||
117 | /// Scoped wchar_t buffer. | |
118 | typedef wxScopedCharTypeBuffer<wchar_t> wxScopedWCharBuffer; | |
119 | ||
120 | /** | |
121 | wxCharTypeBuffer<T> is a template class for storing characters. | |
122 | ||
123 | The difference from wxScopedCharTypeBuffer<T> is that this class | |
124 | doesn't have non-owned mode and the data stored in it are valid for | |
125 | as long as the buffer instance exists. Other than that, this class' | |
126 | behaviour is the same as wxScopedCharTypeBuffer<T>'s -- in particular, | |
127 | the data are reference-counted and copying the buffer is cheap. | |
128 | ||
129 | wxScopedCharTypeBuffer<T> buffers can be converted into wxCharTypeBuffer<T>. | |
130 | ||
131 | @tparam T | |
132 | The type of the characters stored in this class. | |
133 | ||
134 | @since 2.9.0 | |
135 | ||
136 | @nolibrary | |
137 | @category{data} | |
138 | */ | |
139 | template <typename T> | |
140 | class wxCharTypeBuffer : public wxScopedCharTypeBuffer<T> | |
141 | { | |
142 | public: | |
143 | /** | |
144 | Creates (owned) buffer from @a str and takes ownership of it. | |
145 | ||
146 | @param str String data. | |
147 | @param len If specified, length of the string, otherwise the string | |
148 | is considered to be NUL-terminated. | |
149 | ||
150 | @see wxScopedCharTypeBuffer<T>::CreateOwned() | |
151 | */ | |
152 | wxCharTypeBuffer(const CharType *str = NULL, size_t len = wxNO_LEN); | |
153 | ||
154 | ||
155 | /** | |
156 | Creates (owned) buffer of size @a len. | |
157 | ||
158 | @see wxScopedCharTypeBuffer<T>::CreateOwned() | |
159 | */ | |
160 | wxCharTypeBuffer(size_t len); | |
161 | ||
162 | /** | |
163 | Copy constructor. | |
164 | ||
165 | Increases reference count on the data, does @em not make wxStrdup() | |
166 | copy of the data. | |
167 | */ | |
168 | wxCharTypeBuffer(const wxCharTypeBuffer& src); | |
169 | ||
170 | /** | |
171 | Makes a copy of scoped buffer @a src. | |
172 | ||
173 | If @a src is a non-owned buffer, a copy of its data is made using | |
174 | wxStrdup(). If @a src is an owned buffer, this constructor behaves | |
175 | in the usual way (reference count on buffer data is incremented). | |
176 | */ | |
177 | wxCharTypeBuffer(const wxScopedCharTypeBuffer<T>& src); | |
178 | ||
179 | /** | |
180 | Assigns @a str to this buffer and takes ownership of it (i.e.\ the | |
181 | buffer becomes "owned"). | |
182 | */ | |
183 | wxCharTypeBuffer& operator=(const CharType *str); | |
184 | ||
185 | /// Assignment operator behaves in the same way as the copy constructor. | |
186 | wxCharTypeBuffer& operator=(const wxCharTypeBuffer& src); | |
187 | ||
188 | /** | |
189 | Assigns a scoped buffer to this buffer. | |
190 | ||
191 | If @a src is a non-owned buffer, a copy of its data is made using | |
192 | wxStrdup(). If @a src is an owned buffer, the assignment behaves | |
193 | in the usual way (reference count on buffer data is incremented). | |
194 | */ | |
195 | wxCharTypeBuffer& operator=(const wxScopedCharTypeBuffer<T>& src); | |
196 | ||
197 | /** | |
198 | Extends the buffer to have size @a len. | |
199 | ||
200 | Can only be called on buffers that don't share data with another | |
201 | buffer (i.e. reference count of the data is 1). | |
202 | ||
203 | @see shrink() | |
204 | */ | |
205 | bool extend(size_t len); | |
206 | ||
207 | /** | |
208 | Shrinks the buffer to have size @a len and NUL-terminates the string | |
209 | at this length. | |
210 | ||
211 | Can only be called on buffers that don't share data with another | |
212 | buffer (i.e. reference count of the data is 1). | |
213 | ||
214 | @param len Length to shrink to. Must not be larger than current length. | |
215 | ||
216 | @note The string is not reallocated to take less memory. | |
217 | ||
218 | @since 2.9.0 | |
219 | ||
220 | @see extend() | |
221 | */ | |
222 | bool shrink(size_t len); | |
223 | }; | |
224 | ||
225 | /** | |
226 | This is a specialization of wxCharTypeBuffer<T> for @c char type. | |
227 | ||
228 | @nolibrary | |
229 | @category{data} | |
230 | */ | |
231 | class wxCharBuffer : public wxCharTypeBuffer<char> | |
232 | { | |
233 | public: | |
234 | typedef wxCharTypeBuffer<char> wxCharTypeBufferBase; | |
235 | typedef wxScopedCharTypeBuffer<char> wxScopedCharTypeBufferBase; | |
236 | ||
237 | wxCharBuffer(const wxCharTypeBufferBase& buf); | |
238 | wxCharBuffer(const wxScopedCharTypeBufferBase& buf); | |
239 | wxCharBuffer(const CharType *str = NULL); | |
240 | wxCharBuffer(size_t len); | |
241 | wxCharBuffer(const wxCStrData& cstr); | |
242 | }; | |
243 | ||
244 | /** | |
245 | This is a specialization of wxCharTypeBuffer<T> for @c wchar_t type. | |
246 | ||
247 | @nolibrary | |
248 | @category{data} | |
249 | */ | |
250 | class wxWCharBuffer : public wxCharTypeBuffer<wchar_t> | |
251 | { | |
252 | public: | |
253 | typedef wxCharTypeBuffer<wchar_t> wxCharTypeBufferBase; | |
254 | typedef wxScopedCharTypeBuffer<wchar_t> wxScopedCharTypeBufferBase; | |
255 | ||
256 | wxWCharBuffer(const wxCharTypeBufferBase& buf); | |
257 | wxWCharBuffer(const wxScopedCharTypeBufferBase& buf); | |
258 | wxWCharBuffer(const CharType *str = NULL); | |
259 | wxWCharBuffer(size_t len); | |
260 | wxWCharBuffer(const wxCStrData& cstr); | |
261 | }; | |
262 | ||
263 | /** | |
264 | @class wxMemoryBuffer | |
265 | ||
266 | A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized | |
267 | blocks of memory. wxMemoryBuffer guarantees deletion of the memory block when | |
268 | the object is destroyed. | |
269 | ||
270 | @library{wxbase} | |
271 | @category{data} | |
272 | */ | |
273 | class wxMemoryBuffer | |
274 | { | |
275 | public: | |
276 | /** | |
277 | Copy constructor, refcounting is used for performance, but wxMemoryBuffer | |
278 | is not a copy-on-write structure so changes made to one buffer effect all | |
279 | copies made from it. | |
280 | ||
281 | @see @ref overview_refcount | |
282 | */ | |
283 | wxMemoryBuffer(const wxMemoryBuffer& src); | |
284 | ||
285 | /** | |
286 | Create a new buffer. | |
287 | ||
288 | @param size | |
289 | size of the new buffer, 1KiB by default. | |
290 | */ | |
291 | wxMemoryBuffer(size_t size = 1024); | |
292 | ||
293 | /** | |
294 | Append a single byte to the buffer. | |
295 | ||
296 | @param data | |
297 | New byte to append to the buffer. | |
298 | */ | |
299 | void AppendByte(char data); | |
300 | ||
301 | /** | |
302 | Single call to append a data block to the buffer. | |
303 | ||
304 | @param data | |
305 | Pointer to block to append to the buffer. | |
306 | @param len | |
307 | Length of data to append. | |
308 | */ | |
309 | void AppendData(const void *data, size_t len); | |
310 | ||
311 | /** | |
312 | Clear the buffer contents. | |
313 | ||
314 | The buffer won't contain any data after this method is called. | |
315 | ||
316 | @see IsEmpty() | |
317 | ||
318 | @since 2.9.4 | |
319 | */ | |
320 | void Clear(); | |
321 | ||
322 | /** | |
323 | Ensure that the buffer is big enough and return a pointer to the start | |
324 | of the empty space in the buffer. This pointer can be used to directly | |
325 | write data into the buffer, this new data will be appended to the | |
326 | existing data. | |
327 | ||
328 | @param sizeNeeded | |
329 | Amount of extra space required in the buffer for | |
330 | the append operation | |
331 | */ | |
332 | void* GetAppendBuf(size_t sizeNeeded); | |
333 | ||
334 | /** | |
335 | Returns the size of the buffer. | |
336 | */ | |
337 | size_t GetBufSize() const; | |
338 | ||
339 | /** | |
340 | Return a pointer to the data in the buffer. | |
341 | */ | |
342 | void* GetData() const; | |
343 | ||
344 | /** | |
345 | Returns the length of the valid data in the buffer. | |
346 | */ | |
347 | size_t GetDataLen() const; | |
348 | ||
349 | /** | |
350 | Ensure the buffer is big enough and return a pointer to the | |
351 | buffer which can be used to directly write into the buffer | |
352 | up to @a sizeNeeded bytes. | |
353 | */ | |
354 | void* GetWriteBuf(size_t sizeNeeded); | |
355 | ||
356 | /** | |
357 | Returns true if the buffer contains no data. | |
358 | ||
359 | @see Clear() | |
360 | ||
361 | @since 2.9.4 | |
362 | */ | |
363 | bool IsEmpty() const; | |
364 | ||
365 | /** | |
366 | Ensures the buffer has at least @a size bytes available. | |
367 | */ | |
368 | void SetBufSize(size_t size); | |
369 | ||
370 | /** | |
371 | Sets the length of the data stored in the buffer. | |
372 | Mainly useful for truncating existing data. | |
373 | ||
374 | @param size | |
375 | New length of the valid data in the buffer. This is | |
376 | distinct from the allocated size | |
377 | */ | |
378 | void SetDataLen(size_t size); | |
379 | ||
380 | /** | |
381 | Update the length after completing a direct append, which | |
382 | you must have used GetAppendBuf() to initialise. | |
383 | ||
384 | @param sizeUsed | |
385 | This is the amount of new data that has been | |
386 | appended. | |
387 | */ | |
388 | void UngetAppendBuf(size_t sizeUsed); | |
389 | ||
390 | /** | |
391 | Update the buffer after completing a direct write, which | |
392 | you must have used GetWriteBuf() to initialise. | |
393 | ||
394 | @param sizeUsed | |
395 | The amount of data written in to buffer | |
396 | by the direct write | |
397 | */ | |
398 | void UngetWriteBuf(size_t sizeUsed); | |
399 | }; | |
400 |