Component bsls_platformutil [Package bsls]

Provide consistent interface for platform-dependent functionality. More...

Namespaces
namespace	bsls
Defines
#define	BSLS_PLATFORMUTIL_IS_BIG_ENDIAN   BSLS_PLATFORM_IS_BIG_ENDIAN
#define	BSLS_PLATFORMUTIL_HTONL(x)   (x)
#define	BSLS_PLATFORMUTIL_HTONS(x)   (x)
#define	BSLS_PLATFORMUTIL_NTOHL(x)   (x)
#define	BSLS_PLATFORMUTIL_NTOHS(x)   (x)

---

Detailed Description

Outline

• Purpose
• Classes
• Macros
• Description
  • Usage
    • Types
    • Functions and Macros

Purpose:

Provide consistent interface for platform-dependent functionality.

Deprecated:

Use bsls_alignmentutil, bsls_byteorder, bsls_platform, and bsls_types instead.

Classes:

bsls::PlatformUtil

namespace for platform-neutral type names and API

Macros:

BSLS_PLATFORMUTIL_IS_LITTLE_ENDIAN	flag set on little-endian platforms
BSLS_PLATFORMUTIL_IS_BIG_ENDIAN	flag set on big-endian platforms
BSLS_PLATFORMUTIL_HTONS(x)	convert 16-bit from host to network byte order
BSLS_PLATFORMUTIL_HTONL(x)	convert 32-bit from host to network byte order
BSLS_PLATFORMUTIL_NTOHS(x)	convert 16-bit from network to host byte order
BSLS_PLATFORMUTIL_NTOHL(x)	convert 32-bit from network to host byte order

See also:

Component bsls_platform, Component bsls_types

Description:

This component provides a namespace for a set of typedefs and functions that provide a stable, portable interface to platform-dependent functionality. In particular, this component supplies portable typenames for signed and unsigned 64-bit integers, and provides compile-time preprocessor macros that characterize the "endian-ness" of the underlying processor on the current platform. Runtime functionality to return the "endian-ness", and to round up to a multiple of the maximum required alignment for the processor, are also provided.

Usage:

The following illustrates how some of the types and functions supplied by this component might be used.

Types:

bsls::PlatformUtil::Int64 and bsls::PlatformUtil::Uint64 identify the preferred fundamental types denoting signed and unsigned 64-bit integers, respectively:

  bsls::PlatformUtil::Uint64 stimulus = 787000000000ULL;

Clients can use these types in the same way as an int. Clients can also mix usage with other fundamental integral types:

  bsls::PlatformUtil::Uint64 nationalDebt = 1000000000000ULL;
  nationalDebt += stimulus;

  unsigned int deficitReduction = 1000000000;
  nationalDebt -= deficitReduction;

  std::cout << "National Debt Level: " << nationalDebt << std::endl;

bsls::PlatformUtil::size_type identifies the preferred integral type denoting the number of elements in a container, and the number of bytes in a single block of memory supplied by an allocator. For example, a typical use is as a typedef in an STL container:

  class vector {

      // ...

    public:
      typedef bsls::PlatformUtil::size_type size_type;

      // ...
  };

Functions and Macros:

The functions:

  bool bsls::PlatformUtil::isLittleEndian();
  bool bsls::PlatformUtil::isBigEndian();

encapsulate the capability of determining whether a machine is big- or little-endian across all supported platforms. In addition, certain compile-time constants are also provided as preprocessor macros to facilitate conditional compilation:

  BSLS_PLATFORMUTIL_IS_BIG_ENDIAN
  BSLS_PLATFORMUTIL_IS_LITTLE_ENDIAN

These functions and macros are useful for writing platform-independent code, such as a function that converts the bytes in a short to network byte order (which is consistent with big-endian):

  short convertToNetworkByteOrder(short input)
      // Return the specified 'input' in network byte order.
  {
  #ifdef BSLS_PLATFORMUTIL_IS_BIG_ENDIAN
      return input;
  #else
      return static_cast<short>(
                              ((input >> 8) & 0xFF) | ((input & 0xFF) << 8));
  #endif
  }

Note that in the above usage example, either the macros or the functions can be used to test whether a platform is big- or little-endian.

---

Define Documentation

#define BSLS_PLATFORMUTIL_IS_BIG_ENDIAN   BSLS_PLATFORM_IS_BIG_ENDIAN

DEPRECATED: Use preprocessor macro BSLS_PLATFORM_IS_BIG_ENDIAN defined in bsls_platform instead.

#define BSLS_PLATFORMUTIL_HTONL

(

x

)

(x)

#define BSLS_PLATFORMUTIL_HTONS

(

x

)

(x)

#define BSLS_PLATFORMUTIL_NTOHL

(

x

)

(x)

#define BSLS_PLATFORMUTIL_NTOHS

(

x

)

(x)

DEPRECATED: Use preprocessor macros BSLS_BYTEORDER_*TO* defined in bsls_byteorder instead.