Component bdlat_arrayutil [Package bdlat]

Provide utilities for operating on bdlat "array" types. More...

Namespaces
namespace	bdlat

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Primitive and Derived Functions of Arrays
  • Usage
    • Example 1: Accessing an Array Element And Its Category

Purpose:

Provide utilities for operating on bdlat "array" types.

Classes:

bdlat::ArrayUtil

namespace for utility functions on "array" types

See also:

Component bdlat_arrayfunctions, Component bdlat_typecategory

Description:

This component provides a utility struct, bdlat::ArrayUtil, which serves as a namespace for a collection of function templates providing derived operations for "array" types. See bdlat_arrayfunctions for the set of requirements of "array" types in the bdlat framework. See bdlat_typecategory for more general information about this framework.

Primitive and Derived Functions of Arrays:

In order to be "plugged in" to the bdlat framework as an "array", a type must meet a set of requirements including providing certain function overloads (customization points) and specifying certain type traits, as specified by the bdlat_arrayfunctions component. We call the required function overloads the "primitive" operations of "array" types. This component provides "derived" operations, which are operations that are exclusively defined in terms of primitive operations, and as such can be used with any "array" type.

Usage:

In this section we show intended usage of this component.

Example 1: Accessing an Array Element And Its Category:

Suppose we would like to define a function that detects whether an element of an array is itself an array, in order to more generally detect nested arrays.

First, we need to define an accessor functor per bdlat_typecategory'|'ACCESSOR Functors that will be used to detect whether an array element is itself an array:

  class MyArrayDetector {
      // DATA
      bool d_didVisitArray;

    public:
      // CREATORS
      MyArrayDetector()
      : d_didVisitArray(false)
      {
      }

      // MANIPULATORS
      template <class TYPE>
      int operator()(const TYPE& object, bdlat_TypeCategory::Array)
      {
          d_didVisitArray = true;
          return 0;
      }

      template <class TYPE, class OTHER_CATEGORY>
      int operator()(const TYPE&, OTHER_CATEGORY)
      {
          d_didVisitArray = false;
          return 0;
      }

      // ACCESSORS
      bool didVisitArray()
      {
          return d_didVisitArray;
      }
  };

Then, we can define a utility struct, MyArrayUtil, that provides a function for detecting whether or not an array has an element that is itself an array:

  struct MyArrayUtil {

      // CLASS METHODS
      template <class TYPE>
      static int isElementAnArray(bool        *isArray,
                                  const TYPE&  array,
                                  int          index)
          // Load the value 'true' to the specified 'isArray' if the element
          // at the specified 'index' of the specified 'array' has the
          // "array" type category, and load the value 'false' otherwise.
          // Return 0 on success, and a non-zero value otherwise.  If a
          // non-zero value is returned, the value loaded to 'isArray' is
          // unspecified.  The behavior is undefined unless the specified
          // 'array' has the "array" type category, '0 <= index', and
          // 'index < bdlat_ArrayFunctions::size(array)'.
      {
          BSLS_ASSERT(bdlat_TypeCategoryFunctions::select(array) ==
                      bdlat_TypeCategory::e_ARRAY_CATEGORY);
          BSLS_ASSERT(0 <= index);
          BSLS_ASSERT(static_cast<bsl::size_t>(index) <
                      bdlat_ArrayFunctions::size(array));

          MyArrayDetector detector;
          int rc = bdlat::ArrayUtil::accessElementByCategory(array,
                                                             detector,
                                                             index);
          if (0 != rc) {
              return -1;                                            // RETURN
          }

          *isArray = detector.didVisitArray();
          return 0;
      }
  };

Finally, we can use this utility to detect whether elements of array types are themselves arrays:

  void example()
  {
      bsl::vector<int> vectorA;
      vectorA.push_back(42);

      bool isArray = false;
      int rc = MyArrayUtil::isElementAnArray(&isArray, vectorA, 0);

      assert(0 == rc);
      assert(! isArray);

      bsl::vector<bsl::vector<int> > vectorB;
      vectorB.push_back(bsl::vector<int>());

      rc = MyArrayUtil::isElementAnArray(&isArray, vectorB, 0);

      assert(0 == rc);
      assert(isArray);
  }