Component bdlc_compactedarray [Package bdlc]

Provide a compacted array of const user-defined objects. More...

Namespaces
namespace	bdlc

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Storing Daily Schedules

Purpose:

Provide a compacted array of const user-defined objects.

Classes:

bdlc::CompactedArray

compacted array of user-defined objects

Description:

This component provides a space-efficient value-semantic array, bdlc::CompactedArray, and an associated iterator, bdlc::CompactedArray::const_iterator, that provides non-modifiable access to its elements. The interface of this class provides the user with functionality similar to a bsl::vector<T>. The implementation is designed to reduce dynamic memory usage by (1) removing data duplication at the expense of an additional indirection to obtain the stored objects (using the flyweight design pattern) and (2) requiring operator< to be defined for the type of the stored objects. The array supports primitive operations (e.g., insertion, look-up, removal), as well as a complete set of value-semantic operations; however, modifiable reference to individual elements is not available. Users can access the (non-modifiable) value of individual elements by calling the indexing operator or via iterators.

Usage:

This section illustrates intended use of this component.

Example 1: Storing Daily Schedules:

Suppose we are creating a sequence of daily schedules for an employee. Most Mondays (and Tuesdays, Wednesdays, etc.) will have the same schedule, although some may differ. Instead of storing this data in a bsl::vector<my_DailySchedule>, we can use bdlc::CompactedArray<my_DailySchedule> to efficiently store this data.

First, we declare and define a my_DailySchedule class. This class is not overly relevant to the example and is elided for the sake of brevity:

                          // ================
                          // my_DailySchedule
                          // ================

  class my_DailySchedule {
      // A value-semantic class that provides a daily schedule and consumes a
      // significant amount of memory.

      int d_initialLocationId;

      // ...

      // FRIENDS
      friend bool operator<(const my_DailySchedule&,
                            const my_DailySchedule&);

    public:
      // CREATORS
      my_DailySchedule(int               initialLocationId,
                       bslma::Allocator *basicAllocator = 0);
          // Create a 'my_DailySchedule' object having the specified
          // 'initialLocationId'.  Optionally specify a 'basicAllocator' used
          // to supply memory.  If 'basicAllocator' is 0, the currently
          // installed default allocator is used.

      // ...

  };

  bool operator<(const my_DailySchedule& lhs, const my_DailySchedule& rhs);
      // Return 'true' if the specified 'lhs' is lexicographically less than
      // the specified 'rhs' object, and 'false' otherwise.

                           // ----------------
                           // my_DailySchedule
                           // ----------------

  // CREATORS
  inline
  my_DailySchedule::my_DailySchedule(int               initialLocationId,
                                     bslma::Allocator *basicAllocator)
  : d_initialLocationId(initialLocationId)
  {
      (void)basicAllocator;  // suppress unused variable compiler warning

      // ...
  }

  bool operator<(const my_DailySchedule& lhs, const my_DailySchedule& rhs)
  {
      if (lhs.d_initialLocationId < rhs.d_initialLocationId) {
          return true;                                              // RETURN
      }

      // ...

      return false;
  }

Then, we create our schedule, which is an array of my_DailySchedule where the index of each element is the date offset (from an arbitrary epoch measured in days).

  bdlc::CompactedArray<my_DailySchedule> schedule;

Now, we create some daily schedules and append them to the schedule:

  my_DailySchedule evenDays(0);
  my_DailySchedule oddDays(1);

  // Population of the 'my_DailySchedule' objects is elided.

  schedule.push_back(evenDays);
  schedule.push_back(oddDays);
  schedule.push_back(evenDays);
  schedule.push_back(oddDays);
  schedule.push_back(evenDays);

Finally, we verify that the storage is compacted:

  assert(5 == schedule.length());
  assert(2 == schedule.uniqueLength());