Component bsls_util [Package bsls]

Provide essential, low-level support for portable generic code. More...

Namespaces
namespace	bsls
Defines
#define	BSLS_UTIL_ADDRESSOF(OBJ)   (&(OBJ))

---

Detailed Description

Outline

• Purpose
• Classes
• Macros
• Description
  • Usage
    • Example 1: Obtain the Address of a class That Defines operator&.

Purpose:

Provide essential, low-level support for portable generic code.

Classes:

bsls::Util

utility class supplying essential, low-level functionality

Macros:

BSLS_UTIL_ADDRESSOF(OBJ)

address of OBJ, even if operator& overloaded

Description:

This component defines a utility struct, bsls::Util, that serves as a namespace for a suite of pure functions that supply essential low-level support for implementing portable generic facilities such as might be found in the C++ standard library.

Usage:

This section illustrates intended use of this component.

Example 1: Obtain the Address of a class That Defines operator&.:

There are times, especially within low-level library functions, where it is necessary to obtain the address of an object even if that object's class overloads operator& to return something other than the object's address.

First, we create a special reference-like type that can refer to a single bit within a byte (inline implementations are provided in class scope for ease of exposition):

  class BitReference {

      // DATA
      char *d_byte_p;
      int   d_bitpos;

    public:
      // CREATORS
      BitReference(char *byteptr = 0, int bitpos = 0)             // IMPLICIT
      : d_byte_p(byteptr)
      , d_bitpos(bitpos)
      {
      }

      // ACCESSORS
      operator bool() const { return (*d_byte_p >> d_bitpos) & 1; }

      char *byteptr() const { return d_byte_p; }
      int bitpos() const { return d_bitpos; }
  };

Then, we create a pointer-like type that can point to a single bit:

  class BitPointer {

      // DATA
      char *d_byte_p;
      int   d_bitpos;

    public:
      // CREATORS
      BitPointer(char *byteptr = 0, int bitpos = 0)               // IMPLICIT
      : d_byte_p(byteptr)
      , d_bitpos(bitpos)
      {
      }

      // ACCESSORS
      BitReference operator*() const
      {
          return BitReference(d_byte_p, d_bitpos);
      }

      // etc.
  };

Next, we overload operator& for BitReference to return a BitPointer instead of a raw pointer, completing the setup:

  inline BitPointer operator&(const BitReference& ref)
  {
      return BitPointer(ref.byteptr(), ref.bitpos());
  }

Then, we note that there are times when it might be desirable to get the true address of a BitReference. Since the above overload prevents the obvious syntax from working, we use bsls::Util::addressOf to accomplish this task.

Next, we create a BitReference object:

  char c[4];
  BitReference br(c, 3);

Now, we invoke bsls::Util::addressOf to obtain and save the address of br:

  BitReference *p = bsls::Util::addressOf(br);  // OK
  // BitReference *p = &br;                     // Won't compile

Notice that the commented line illustrates canonical use of operator& that would not compile in this example.

Finally, we verify that address obtained is the correct one, running some sanity checks:

  assert(0 != p);
  assert(c == p->byteptr());
  assert(3 == p->bitpos());

---

Define Documentation

#define BSLS_UTIL_ADDRESSOF

(

OBJ

)

(&(OBJ))

Referenced by bslalg::ScalarPrimitives_Imp::construct(), bslalg::ScalarPrimitives_Imp::copyConstruct(), bslalg::ScalarPrimitives_Imp::moveConstruct(), and bslalg::ScalarPrimitives_Imp::swap().