interface/wx/buffer.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        buffer.h
   3 // Purpose:     interface of wxMemoryBuffer
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMemoryBuffer
  11
  12     A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized
  13     blocks of memory. wxMemoryBuffer guarantees deletion of the memory block when
  14     the object is destroyed.
  15
  16     @library{wxbase}
  17     @category{data}
  18 */
  19 class wxMemoryBuffer
  20 {
  21 public:
  22     /**
  23         Copy constructor, refcounting is used for performance, but wxMemoryBuffer
  24         is not a copy-on-write structure so changes made to one buffer effect all
  25         copies made from it.
  26
  27         @see @ref overview_refcount
  28     */
  29     wxMemoryBuffer(const wxMemoryBuffer& src);
  30
  31     /**
  32         Create a new buffer.
  33
  34         @param size
  35             size of the new buffer.
  36     */
  37     wxMemoryBuffer(size_t size);
  38
  39     /**
  40         Append a single byte to the buffer.
  41
  42         @param data
  43             New byte to append to the buffer.
  44     */
  45     void AppendByte(char data);
  46
  47     /**
  48         Ensure that the buffer is big enough and return a pointer to the start
  49         of the empty space in the buffer. This pointer can be used to directly
  50         write data into the buffer, this new data will be appended to the
  51         existing data.
  52
  53         @param sizeNeeded
  54             Amount of extra space required in the buffer for
  55             the append operation
  56     */
  57     void* GetAppendBuf(size_t sizeNeeded);
  58
  59     /**
  60         Returns the size of the buffer.
  61     */
  62     size_t GetBufSize() const;
  63
  64     /**
  65         Return a pointer to the data in the buffer.
  66     */
  67     void* GetData() const;
  68
  69     /**
  70         Returns the length of the valid data in the buffer.
  71     */
  72     size_t GetDataLen() const;
  73
  74     /**
  75         Ensure the buffer is big enough and return a pointer to the
  76         buffer which can be used to directly write into the buffer
  77         up to @a sizeNeeded bytes.
  78     */
  79     void* GetWriteBuf(size_t sizeNeeded);
  80
  81     /**
  82         Ensures the buffer has at least @a size bytes available.
  83     */
  84     void SetBufSize(size_t size);
  85
  86     /**
  87         Sets the length of the data stored in the buffer.
  88         Mainly useful for truncating existing data.
  89
  90         @param size
  91             New length of the valid data in the buffer. This is
  92             distinct from the allocated size
  93     */
  94     void SetDataLen(size_t size);
  95
  96     /**
  97         Update the length after completing a direct append, which
  98         you must have used GetAppendBuf() to initialise.
  99
 100         @param sizeUsed
 101             This is the amount of new data that has been
 102             appended.
 103     */
 104     void UngetAppendBuf(size_t sizeUsed);
 105
 106     /**
 107         Update the buffer after completing a direct write, which
 108         you must have used GetWriteBuf() to initialise.
 109
 110         @param sizeUsed
 111             The amount of data written in to buffer
 112             by the direct write
 113     */
 114     void UngetWriteBuf(size_t sizeUsed);
 115 };
 116