The Data class encapsulates a buffer of bytes. It is similar in functionality to many common string classes, except that it operates on collections of bytes instead of collections of characters. In particular, Data is meant to operate on buffers that may or may not contain binary data. That said, there are a number of operations on Data which are written with manipulation of text in mind, and many methods go out of their way to ensure that the buffer is often null-terminated. It's a bit schizophrenic that way.
At any given time, a Data is associated with a single buffer which contains the bytes inside the Data. This buffer may be owned by the Data object itself, or owned by an external party. Additionally, data owned by an external party can be considered changeable or unchangeable.
|Sharing Style||Buffer Ownership||Buffer Mutable?|
|Share||External to Data class||Yes|
|Borrow||External to Data class||No|
|Take||Owned by Data class||Yes|
If a Data containing an immutable buffer (i.e. Sharing Mode is Borrow) is changed, then a new buffer is allocated by the Data, the contents of the existing (immutable) buffer are copied into it, and the modification is performed on the new buffer. This newly allocated buffer is owned by the Data.
If a modification is performed on a Data which requires more space than is available in the underlying buffer, then a larger buffer is allocated, the existing data is copied into the new buffer, and the modification is performed on the new buffer. If the old buffer was owned by the Data, it will be deallocated.
Note that all deallocation performed by the Data uses delete; consequently, any data owned by the Data (e.g. Sharing Mode is Take) must be allocated from the normal heap using new, lest you anger the portability gods.
Finally, users of Data should note that a Data created from a buffer with Share or Borrow sharing must outlive the Data itself.
Creating a Data
equal, <, >, prefix, postfix, substr
hash, hex, escaping, md5