]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/buffer.h
Make storing non-trivial data in wxThreadSpecificInfo possible.
[wxWidgets.git] / interface / wx / buffer.h
... / ...
CommitLineData
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*/
44template <typename T>
45class wxScopedCharTypeBuffer
46{
47public:
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.
115typedef wxScopedCharTypeBuffer<char> wxScopedCharBuffer;
116
117/// Scoped wchar_t buffer.
118typedef 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*/
139template <typename T>
140class wxCharTypeBuffer : public wxScopedCharTypeBuffer<T>
141{
142public:
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*/
231class wxCharBuffer : public wxCharTypeBuffer<char>
232{
233public:
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*/
250class wxWCharBuffer : public wxCharTypeBuffer<wchar_t>
251{
252public:
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*/
273class wxMemoryBuffer
274{
275public:
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