bdld_datumbinaryref

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic DatumBinaryRef usage

Purpose

Provide a type to represent binary data and its size.

Classes

• bdld::DatumBinaryRef: a type representing binary data and its size

See also

bdld_datum, bdld_datumerror, bdld_datumudt

Description

This component implements a class, bdld::DatumBinaryRef, that represents a pointer to a non-modifiable binary data (as a void *) and an integral size value. Note, that bdld::DatumBinaryRef is nether a value-semantic type, nor is it an in-core value-semantic type (see bsldoc_glossary ). The bdld::DatumBinaryRef notion of value is expressed by its equality-operator - two bdld::DatumBinaryRef compare equal if the binary data they refer to is identical (both by size and by content). Accessors inside Datum class that need to return a binary data, return an instance of bdld::DatumBinaryRef.

Usage

This section illustrates intended use of this component.

Example 1: Basic DatumBinaryRef usage

Suppose we have three functions. Data are obtained in the first one (with memory allocation), processed in the second one and released (with memory deallocation) in the third one. The following code illustrates how to use bdld::DatumBinaryRef to pass information about memory storage between them.

First, we write all three functions:

// Allocate array of the specified `size` and initialize it with some
// values.
bdld::DatumBinaryRef obtainData(size_t size)
{
    if (0 == size) {
        return bdld::DatumBinaryRef();                            // RETURN
    }
    int *buffer = new int[size];
    for (size_t i = 0; i < size; ++i) {
        buffer[i] = static_cast<int>(i);
    }
    return bdld::DatumBinaryRef(static_cast<void *>(buffer), size);
}
 
/// Process data, held by the specified `binaryData` object.
int processData(const bdld::DatumBinaryRef& binaryData)
{
    ostringstream out;
    binaryData.print(out);
 
    if (binaryData == bdld::DatumBinaryRef()) {
        return 0;                                                 // RETURN
    }
 
    int        result = 0;
    const int *array = static_cast<const int *>(binaryData.data());
    for (size_t i = 0; i < binaryData.size(); ++i) {
        result += array[i];
    }
    return result;
}
 
/// Release memory, held by the specified `binaryData` object.
void releaseData(const bdld::DatumBinaryRef& binaryData)
{
    const int *array = static_cast<const int *>(binaryData.data());
    delete [] array;
}

Next, we call first one to obtain data:

bdld::DatumBinaryRef binaryData = obtainData(5);

Then we verify the results of second one's call:

assert(10 == processData(binaryData));

Finally, we release allocated memory:

releaseData(binaryData);