← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to interface/wx/buffer.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

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