Component bdld_datumbinaryref [Package bdld]

Provide a type to represent binary data and its size. More...

Namespaces
namespace	bdld

---

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:

Component bdld_datum, Component bdld_datumerror, Component 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:

  bdld::DatumBinaryRef obtainData(size_t size)
      // Allocate array of the specified 'size' and initialize it with some
      // values.
  {
      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);
  }

  int processData(const bdld::DatumBinaryRef& binaryData)
      // Process data, held by the specified 'binaryData' object.
  {
      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;
  }

  void releaseData(const bdld::DatumBinaryRef& binaryData)
      // Release memory, held by the specified 'binaryData' object.
  {
      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);