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