Component bdlb_bigendian [Package bdlb]

Provide big-endian integer types. More...

Namespaces
namespace	bdlb

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic Use of bdlb::BigEndian

Purpose:

Provide big-endian integer types.

Classes:

bdlb::BigEndianInt16	signed 16-bit in-core big-endian integer
bdlb::BigEndianUint16	unsigned 16-bit in-core big-endian integer
bdlb::BigEndianInt32	signed 32-bit in-core big-endian integer
bdlb::BigEndianUint32	unsigned 32-bit in-core big-endian integer
bdlb::BigEndianInt64	signed 64-bit in-core big-endian integer
bdlb::BigEndianUint64	unsigned 64-bit in-core big-endian integer

See also:

Component bsls_types

Description:

This component provides generic in-core big-endian integer types bdlb::BigEndianInt16, bdlb::BigEndianUint16, bdlb::BigEndianInt32, bdlb::BigEndianUint32, bdlb::BigEndianInt64 and bdlb::BigEndianUint64 that store integral values that they represent in a big-endian byte order. For example, an integer value 0x01020304 will be internally stored by the bdlb::BigEndianInt32 object as 0x04030201 on little-endian platforms.

Usage:

This section illustrates intended use of this component.

Example 1: Basic Use of bdlb::BigEndian:

This example demonstrates using bdlb::BigEndian types to represent a structure meant to be exchanged over the network ( which historically uses big-endian byte order ) or stored in-core as big-endian integers. First, we define the structure:

  struct ProtocolHeader {
      // This structure represents the header of the protocol.  All integer
      // values are stored in the network byte-order (i.e., big-endian).

      bdlb::BigEndianUint16 d_protocolVersion;
      bdlb::BigEndianUint16 d_messageType;
      bdlb::BigEndianUint32 d_messageLength;
  };

Next, we prepare in-memory representation of the protocol header with protocol version set to 0x1, message type set to 0x02 and message length set to 0x1234 in the big-endian byte order (most significant bytes first):

  const char buffer[8] = { 0x00, 0x01, 0x00, 0x02, 0x00, 0x00, 0x12, 0x34 };

Now, we create an instance of the ProtocolHeader structure and emulate packet reception over the network:

  struct ProtocolHeader header;
  assert(8 == sizeof(header));
  memcpy(static_cast<void*>(&header), buffer, 8);

Next, we verify that actual in-core values depend on the endianess of the underlying platform:

  #ifdef BSLS_PLATFORM_IS_LITTLE_ENDIAN
  assert(0x0100 ==
         static_cast<short>(*(reinterpret_cast<unsigned short*>(
                                               &header.d_protocolVersion))));

  assert(0x0200 ==
         static_cast<short>(*(reinterpret_cast<unsigned short*>(
                                               &header.d_messageType))));

  assert(0x34120000 == *(reinterpret_cast<unsigned int*>(
                                               &header.d_messageLength)));
  #endif // BSLS_PLATFORM_IS_LITTLE_ENDIAN

  #ifdef BSLS_PLATFORM_IS_BIG_ENDIAN
  assert(0x01 ==
         static_cast<short>(*(reinterpret_cast<unsigned short*>(
                                               &header.d_protocolVersion))));

  assert(0x02 ==
         static_cast<short>(*(reinterpret_cast<unsigned short*>(
                                               &header.d_messageType))));

  assert(0x1234 == *(reinterpret_cast<unsigned int*>(
                                               &header.d_messageLength)));
  #endif // BSLS_PLATFORM_IS_BIG_ENDIAN

Finally, we verify that the received protocol header can be validated on platforms of any endianess:

  assert(0x01   == header.d_protocolVersion);
  assert(0x02   == header.d_messageType);
  assert(0x1234 == header.d_messageLength);