Difference between revisions of "Using Data"

From reSIProcate
Jump to navigation Jump to search
 
Line 3: Line 3:
 
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.
 
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.
  
<table>
+
<center><table border=1>
 
<tr><th>Sharing Style</th><th>Buffer Ownership</th><th>Buffer Mutable?</th></tr>
 
<tr><th>Sharing Style</th><th>Buffer Ownership</th><th>Buffer Mutable?</th></tr>
 
<tr><td>Share</td><td>External to Data class</td><td>Yes</td></tr>
 
<tr><td>Share</td><td>External to Data class</td><td>Yes</td></tr>
 
<tr><td>Borrow</td><td>External to Data class</td><td>No</td></tr>
 
<tr><td>Borrow</td><td>External to Data class</td><td>No</td></tr>
 
<tr><td>Take</td><td>Owned by Data class</td><td>Yes</td></tr>
 
<tr><td>Take</td><td>Owned by Data class</td><td>Yes</td></tr>
</table>
+
</table></center>
 +
 
 +
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[].
 +
 
 +
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=
 
=Creating a Data=

Revision as of 14:39, 16 June 2005

The Data class encapsulates a buffer of bytes.

Buffer Management

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 StyleBuffer OwnershipBuffer Mutable?
ShareExternal to Data classYes
BorrowExternal to Data classNo
TakeOwned by Data classYes

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[].

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

Data Comparisons

equal, <, >, prefix, postfix, substr

Data Manipulations

concat, xor,

Data Transformations

hash, hex, escaping, md5

Data Conversion