Detailed Description

Provide a compile-time switch meta-function.

Outline

Purpose
Classes
Description
- Usage

Purpose

Provide a compile-time switch meta-function.

Classes

bslmf::Switch: switch meta-function (variable number of types)
bslmf::Switch2: switch meta-function (among two types)
bslmf::Switch3: switch meta-function (among three types)
bslmf::Switch4: switch meta-function (among four types)
bslmf::Switch5: switch meta-function (among five types)
bslmf::Switch6: switch meta-function (among six types)
bslmf::Switch7: switch meta-function (among seven types)
bslmf::Switch8: switch meta-function (among eight types)
bslmf::Switch9: switch meta-function (among nine types)

See also: bslmf_typelist

Description

This component provides a compile-time switch meta-function. Its main class, bslmf::Switch, parameterized by an integral t_SWITCH_SELECTOR and a variable number N of types, t_T0 up to T{N - 1}, contains a single type named Type, which is the result of the meta-function and is an alias to T{t_SWITCH_SELECTOR} or to bslmf::Nil if t_SWITCH_SELECTOR is outside the range [ 0 .. N - 1 ]. The analogy between the following "meta-code" and its valid C++ version using bslmf::Switch may serve as a useful mental picture to understand and memorize the usage of this component.

"Meta-code" (not C++)               Valid C++ using 'bslmf::Switch'
---------------------               ------------------------------
typedef                             typedef typename
  switch (t_SWITCH_SELECTOR) {             bslmf::Switch<t_SWITCH_SELECTOR,
    case 0:     t_T0;                                      t_T0,
    case 1:     t_T1;                                      t_T1,
    // . . .                                             // . . .
    case N - 1: T{N - 1};                                T{N - 1}
    default:    bslmf::Nil;                              >
  }                                                      ::
                Type;                                      Type;

Note the use of the keyword typename, necessary only if one or more of the t_SWITCH_SELECTOR or t_T0 up to T{N - 1} is dependent on a template parameter of the local context (i.e., that of the block using bslmf::Switch). In particular, it should be omitted if the bslmf::Switch is not used within a class or function template, as in the usage example below.

For most situations, the number N of template type arguments is known and the bslmf::SwitchN meta-functions, which take exactly the indicated number of arguments, should be preferred. Their usage leads to shorter mangled symbol names in object files (e.g., no extra defaulted template type arguments are included in the name), and shorter compilation times, as well.

Usage

Assume an external server API for storing and retrieving data:

class data_Server {
    // Dummy implementation of data server
 
    int d_data;
 
  public:
     void store(char  data) { d_data = data | 0Xefface00; }
     void store(short data) { d_data = data | 0Xdead0000; }
     void store(int   data) { d_data = data; }
 
     void retrieve(char  *data) {
        *data = static_cast<char>(d_data & 0x000000ff);
     }
     void retrieve(short *data) {
        *data = static_cast<short>(d_data & 0x0000ffff);
     }
     void retrieve(int   *data) { *data = d_data; }
};

In our application, we need some very small (1, 2, and 4-byte), special-purpose string types, so we create the following ShortString class template:

template <int LEN>
class ShortString {
    // Store a short, fixed-length string.
 
    char d_buffer[LEN];
 
  public:
    ShortString(const char *s = "") { std::strncpy(d_buffer, s, LEN); }
        // Construct a 'ShortString' from a NTCS.
 
    void retrieve(data_Server *server);
        // Retrieve this string from a data server.
 
    void store(data_Server *server) const;
        // Store this string to a data server.
 
    char operator[](int n) const { return d_buffer[n]; }
        // Return the nth byte in this string.
};
 
template <int LEN>
bool operator==(const ShortString<LEN>& lhs, const ShortString<LEN>& rhs)
    // Return true if a 'lhs' is equal to 'rhs'
{
    return 0 == std::memcmp(&lhs, &rhs, LEN);
}
 
template <int LEN>
bool operator==(const ShortString<LEN>& lhs, const char *rhs)
    // Return true if a 'ShortString' 'lhs' is equal to a NTCS 'rhs'.
{
    int i;
    for (i = 0; LEN > i && lhs[i]; ++i) {
        if (lhs[i] != rhs[i]) {
            return false;
        }
    }
 
    return ('\0' == rhs[i]);
}

We would like to store our short strings in the data server, but the data server only handles char, short and int types. Since our strings fit into these simple types, we can transform ShortString into these integral types when calling store and retrieve, using bslmf::Switch to choose which integral type to use for each ShortString type:

template <int LEN>
void ShortString<LEN>::retrieve(data_Server *server)
{
    // 'transferType will be 'char' if 'LEN' is 1, 'short' if 'LEN' is 2,
    // and 'int' if 'LEN' 4.  Will choose 'void' and thus not compile if
    // 'LEN' is 0 or 3.
 
    typedef typename
       bslmf::Switch<LEN, void, char, short, void, int>::Type transferType;
 
    transferType x = 0;
    server->retrieve(&x);
    std::memcpy(d_buffer, &x, LEN);
}
 
template <int LEN>
void ShortString<LEN>::store(data_Server *server) const
{
    // 'transferType will be 'char' if 'LEN' is 1, 'short' if 'LEN' is 2,
    // and 'int' if 'LEN' 4.  Will choose 'void' and thus not compile if
    // 'LEN' is 0 or 3.
    typedef typename
       bslmf::Switch<LEN, void, char, short, void, int>::Type transferType;
 
    transferType x = 0;
    std::memcpy(&x, d_buffer, LEN);
    server->store(x);
}

In our main program, we first assert our basic assumptions, then we store and retrieve strings using our ShortString template.

int main()
{
    assert(2 == sizeof(short));
    assert(4 == sizeof(int));
 
    data_Server server;
 
    ShortString<1> a("A");
    ShortString<1> b("B");
    assert(a == "A");
    assert(b == "B");
    assert(! (a == b));
 
    a.store(&server);
    b.retrieve(&server);
    assert(a == "A");
    assert(b == "A");
    assert(a == b);
 
    ShortString<2> cd("CD");
    ShortString<2> ef("EF");
    assert(cd == "CD");
    assert(ef == "EF");
    assert(! (cd == ef));
 
    cd.store(&server);
    ef.retrieve(&server);
    assert(cd == "CD");
    assert(ef == "CD");
    assert(cd == ef);
 
    ShortString<4> ghij("GHIJ");
    ShortString<4> klmn("KLMN");
    assert(ghij == "GHIJ");
    assert(klmn == "KLMN");
    assert(! (ghij == klmn));
 
    ghij.store(&server);
    klmn.retrieve(&server);
    assert(ghij == "GHIJ");
    assert(klmn == "GHIJ");
    assert(ghij == klmn);
 
    return 0;
}