bsls_macrorepeat.h

// bsls_macrorepeat.h                                                 -*-C++-*-
#ifndef INCLUDED_BSLS_MACROREPEAT
#define INCLUDED_BSLS_MACROREPEAT

#include <bsls_ident.h>
BSLS_IDENT("$Id: $")

//@PURPOSE: repeat a macro invocation with different numeric arguments.
//
//@CLASSES:
//
//@MACROS:
// BSLS_MACROREPEAT(N, MACRO): Invoke 'MACRO(1) MACRO(2) ... MACRO(N)'
// BSLS_MACROREPEAT_COMMA(N, MACRO): 'N' comma-separated invocations of 'MACRO'
// BSLS_MACROREPEAT_SEP(N, MACRO, S): 'N' invocations of 'MACRO' separated by S
//
//@SEE_ALSO:
//
//@DESCRIPTION: This component provides a set of macros that expand to multiple
// repetitions of a user-specified "repetition phrase".  The repetition phrase
// is specified as macro that is invoked multiple times in each invocation of a
// 'BSLS_MACROREPEAT*' macro.  For example:
//..
//  #define FOO(n) foo ## n
//  doit(BSLS_MACROREPEAT_COMMA(5, FOO));
//..
// will expand FOO(n) with arguments 1 through 5, inserting commas between the
// expansions, resulting in:
//..
//  doit(foo1, foo2, foo3, foo4, foo5);
//..
// Use of these macros is less error-prone and often more compact than manually
// repeating the specified pattern.  In addition, it is sometimes more readable
// than the cut-and-paste alternative because the reader does not need to
// examine each argument to verify that it forms a linear sequence.
//
// Each of these macros can appear within the repetition phrase of another of
// these macros but, because of limitations in the C proprocessor language,
// none of these macros can appear (directly or indirectly) within its own
// repetition phrase.
//
///Usage
///-----
// The following examples demonstrate potential uses of the macros in this
// component.
//
///Example 1: Repeated Template Instantiation
/// - - - - - - - - - - - - - - - - - - - - -
// In this example, we wish to explicitly instantiate a template with a
// sequence of integer values.  First, assume a function template 'foo<V>' that
// adds the (compile-time) value 'V' to a global 'total' each time it is
// called:
//..
//  int total = 0;
//  template <int V> void foo() { total += V; }
//..
// Now, if we instantiate and call 'foo<X>()' once for each 'X' in the range
// '2' to '6'.  To do that, we create a macro, 'FOO_STMNT(X)' which and calls
// 'foo<X+1>' (i.e., 'FOO_STMNT(1)' will call 'foo<2>()').  Then we invoke
// 'FOO_STMNT' 5 times with arguments 1, 2, 3, 4, and 5 using the
// 'BSLS_MACROREPEAT' macro:
//..
//  int main() {
//
//      #define FOO_STMNT(X) foo<X+1>();  // Semicolon at end of each statement
//      BSLS_MACROREPEAT(5, FOO_STMNT)
//      assert(20 == total);
//      return 0;
// }
//..
//
///Example 2: Repeated Function Arguments
/// - - - - - - - - - - - - - - - - - - -
// In this example, we supply as series of identical arguments to a function
// invocation, using 'BSLS_MACROREPEAT_COMMA'.  First, assume a function,
// 'fmtQuartet' that takes four integer arguments and formats them into a
// string:
//..
//  #include <cstring>
//  #include <cstdio>
//
//  void fmtQuartet(char *result, int a, int b, int c, int d) {
//      std::sprintf(result, "%d %d %d %d", a, b, c, d);
//  }
//..
// Now we wish to invoke this function, but in a context where the last three
// arguments are always the same as each other.  For this situation we define a
// macro 'X(x)' that ignores its argument and simply expands to an unchanging
// set of tokens.  If the repeated argument is named 'i', then the expansion of
// 'X(x)' is simply '(i)':
//..
//  int main() {
//      char buffer[20];
//      int i = 8;
//      #define X(x) (i)
//..
// Finally, we invoke macro 'X(x)' three times within the argument list of
// 'fmtQuart'.  We use 'BSLS_MACROREPEAT_COMMA' for these invocations, as it
// inserts a comma between each repetition:
//..
//      fmtQuartet(buffer, "%d %d %d %d", 7, BSLS_MACROREPEAT_COMMA(3, X));
//      assert(0 == std::strcmp(buffer, "7 8 8 8"));
//      return 0;
//  }
//..
//
///Example 3: Bitmask Computation
/// - - - - - - - - - - - - - - -
// In this example, we Compute (at compile time) a 7-bit mask.  First, we
// defined a macro 'BITVAL' that computes the value of a single bit 'B' in the
// mask:
//..
//  #define BITVAL(B) (1 << (B - 1))
//..
// Then we use the 'BSLS_MACROREPEAT_SEP' to invoke 'BITVAL' 7 times,
// separating the repetitions with the bitwise OR operator:
//..
//  const unsigned mask = BSLS_MACROREPEAT_SEP(7, BITVAL, |);
//
//  int main() {
//      assert(127 == mask);
//      return 0;
//  }
//..

#define BSLS_MACROREPEAT(N, MACRO) BSLS_MACROREPEAT_##N(MACRO)
    // Expand to 'N' invocations of 'MACRO(x)', where 'x' in each invocation is
    // the next number in the sequence from '1' to 'N'.  If 'N' is '0', then
    // the expansion is empty.  For example 'BSLS_MACROREPEAT(3, XYZ)' expands
    // to 'XYZ(1) XYZ(2) XYZ(3)'.  The behavior is undefined unless 'N' is a
    // decimal integer (or is a macro that expands to a decimal integer) in the
    // range 0 to 20.  Note that 'MACRO' is typically a macro with one
    // argument, but may also be a function or functor.

#define BSLS_MACROREPEAT_COMMA(N, MACRO) BSLS_MACROREPEAT_C##N(MACRO)
    // Expand to 'N' comma-separated invocations of 'MACRO(x)', where 'x' in
    // each invocation is the next number in the sequence from '1' to 'N'.  If
    // 'N' is '0', then the expansion is empty.  For example
    // 'BSLS_MACROREPEAT_COMMA(3, XYZ)' expands to 'XYZ(1), XYZ(2), XYZ(3)'.
    // The behavior is undefined unless 'N' is a decimal integer (or is a macro
    // that expands to a decimal integer) in the range 0 to 20.  Note that
    // 'MACRO' is typically a macro with one argument, but may also be a
    // function or functor.

#define BSLS_MACROREPEAT_SEP(N, MACRO, S) BSLS_MACROREPEAT_S##N(MACRO, S)
    // Expand to 'N' invocations of 'MACRO(x)' separated by the token sequence
    // 'S', where 'x' in each invocation is the next number in the sequence
    // from '1' to 'N'.  If 'N' is '0', then the expansion is empty.  For
    // example 'BSLS_MACROREPEAT_SEP(3, XYZ, ;)' expands to 'XYZ(1) ; XYZ(2) ;
    // XYZ(3)'.  The behavior is undefined unless 'N' is a decimal integer (or
    // is a macro that expands to a decimal integer) in the range 0 to 20.
    // Note that 'MACRO' is typically a macro with one argument, but may also
    // be a function or functor.

// ============================================================================
//                           IMPLEMENTATION MACROS
// ============================================================================

#define BSLS_MACROREPEAT_0(MACRO)
#define BSLS_MACROREPEAT_1(MACRO) MACRO(1)
#define BSLS_MACROREPEAT_2(MACRO) BSLS_MACROREPEAT_1(MACRO) MACRO(2)
#define BSLS_MACROREPEAT_3(MACRO) BSLS_MACROREPEAT_2(MACRO) MACRO(3)
#define BSLS_MACROREPEAT_4(MACRO) BSLS_MACROREPEAT_3(MACRO) MACRO(4)
#define BSLS_MACROREPEAT_5(MACRO) BSLS_MACROREPEAT_4(MACRO) MACRO(5)
#define BSLS_MACROREPEAT_6(MACRO) BSLS_MACROREPEAT_5(MACRO) MACRO(6)
#define BSLS_MACROREPEAT_7(MACRO) BSLS_MACROREPEAT_6(MACRO) MACRO(7)
#define BSLS_MACROREPEAT_8(MACRO) BSLS_MACROREPEAT_7(MACRO) MACRO(8)
#define BSLS_MACROREPEAT_9(MACRO) BSLS_MACROREPEAT_8(MACRO) MACRO(9)
#define BSLS_MACROREPEAT_10(MACRO) BSLS_MACROREPEAT_9(MACRO) MACRO(10)
#define BSLS_MACROREPEAT_11(MACRO) BSLS_MACROREPEAT_10(MACRO) MACRO(11)
#define BSLS_MACROREPEAT_12(MACRO) BSLS_MACROREPEAT_11(MACRO) MACRO(12)
#define BSLS_MACROREPEAT_13(MACRO) BSLS_MACROREPEAT_12(MACRO) MACRO(13)
#define BSLS_MACROREPEAT_14(MACRO) BSLS_MACROREPEAT_13(MACRO) MACRO(14)
#define BSLS_MACROREPEAT_15(MACRO) BSLS_MACROREPEAT_14(MACRO) MACRO(15)
#define BSLS_MACROREPEAT_16(MACRO) BSLS_MACROREPEAT_15(MACRO) MACRO(16)
#define BSLS_MACROREPEAT_17(MACRO) BSLS_MACROREPEAT_16(MACRO) MACRO(17)
#define BSLS_MACROREPEAT_18(MACRO) BSLS_MACROREPEAT_17(MACRO) MACRO(18)
#define BSLS_MACROREPEAT_19(MACRO) BSLS_MACROREPEAT_18(MACRO) MACRO(19)
#define BSLS_MACROREPEAT_20(MACRO) BSLS_MACROREPEAT_19(MACRO) MACRO(20)

#define BSLS_MACROREPEAT_C0(MACRO)
#define BSLS_MACROREPEAT_C1(MACRO) MACRO(1)
#define BSLS_MACROREPEAT_C2(MACRO) BSLS_MACROREPEAT_C1(MACRO), MACRO(2)
#define BSLS_MACROREPEAT_C3(MACRO) BSLS_MACROREPEAT_C2(MACRO), MACRO(3)
#define BSLS_MACROREPEAT_C4(MACRO) BSLS_MACROREPEAT_C3(MACRO), MACRO(4)
#define BSLS_MACROREPEAT_C5(MACRO) BSLS_MACROREPEAT_C4(MACRO), MACRO(5)
#define BSLS_MACROREPEAT_C6(MACRO) BSLS_MACROREPEAT_C5(MACRO), MACRO(6)
#define BSLS_MACROREPEAT_C7(MACRO) BSLS_MACROREPEAT_C6(MACRO), MACRO(7)
#define BSLS_MACROREPEAT_C8(MACRO) BSLS_MACROREPEAT_C7(MACRO), MACRO(8)
#define BSLS_MACROREPEAT_C9(MACRO) BSLS_MACROREPEAT_C8(MACRO), MACRO(9)
#define BSLS_MACROREPEAT_C10(MACRO) BSLS_MACROREPEAT_C9(MACRO), MACRO(10)
#define BSLS_MACROREPEAT_C11(MACRO) BSLS_MACROREPEAT_C10(MACRO), MACRO(11)
#define BSLS_MACROREPEAT_C12(MACRO) BSLS_MACROREPEAT_C11(MACRO), MACRO(12)
#define BSLS_MACROREPEAT_C13(MACRO) BSLS_MACROREPEAT_C12(MACRO), MACRO(13)
#define BSLS_MACROREPEAT_C14(MACRO) BSLS_MACROREPEAT_C13(MACRO), MACRO(14)
#define BSLS_MACROREPEAT_C15(MACRO) BSLS_MACROREPEAT_C14(MACRO), MACRO(15)
#define BSLS_MACROREPEAT_C16(MACRO) BSLS_MACROREPEAT_C15(MACRO), MACRO(16)
#define BSLS_MACROREPEAT_C17(MACRO) BSLS_MACROREPEAT_C16(MACRO), MACRO(17)
#define BSLS_MACROREPEAT_C18(MACRO) BSLS_MACROREPEAT_C17(MACRO), MACRO(18)
#define BSLS_MACROREPEAT_C19(MACRO) BSLS_MACROREPEAT_C18(MACRO), MACRO(19)
#define BSLS_MACROREPEAT_C20(MACRO) BSLS_MACROREPEAT_C19(MACRO), MACRO(20)

#define BSLS_MACROREPEAT_S0(MACRO,S)
#define BSLS_MACROREPEAT_S1(MACRO,S) MACRO(1)
#define BSLS_MACROREPEAT_S2(MACRO,S) BSLS_MACROREPEAT_S1(MACRO,S) S MACRO(2)
#define BSLS_MACROREPEAT_S3(MACRO,S) BSLS_MACROREPEAT_S2(MACRO,S) S MACRO(3)
#define BSLS_MACROREPEAT_S4(MACRO,S) BSLS_MACROREPEAT_S3(MACRO,S) S MACRO(4)
#define BSLS_MACROREPEAT_S5(MACRO,S) BSLS_MACROREPEAT_S4(MACRO,S) S MACRO(5)
#define BSLS_MACROREPEAT_S6(MACRO,S) BSLS_MACROREPEAT_S5(MACRO,S) S MACRO(6)
#define BSLS_MACROREPEAT_S7(MACRO,S) BSLS_MACROREPEAT_S6(MACRO,S) S MACRO(7)
#define BSLS_MACROREPEAT_S8(MACRO,S) BSLS_MACROREPEAT_S7(MACRO,S) S MACRO(8)
#define BSLS_MACROREPEAT_S9(MACRO,S) BSLS_MACROREPEAT_S8(MACRO,S) S MACRO(9)
#define BSLS_MACROREPEAT_S10(MACRO,S) BSLS_MACROREPEAT_S9(MACRO,S) S MACRO(10)
#define BSLS_MACROREPEAT_S11(MACRO,S) BSLS_MACROREPEAT_S10(MACRO,S) S MACRO(11)
#define BSLS_MACROREPEAT_S12(MACRO,S) BSLS_MACROREPEAT_S11(MACRO,S) S MACRO(12)
#define BSLS_MACROREPEAT_S13(MACRO,S) BSLS_MACROREPEAT_S12(MACRO,S) S MACRO(13)
#define BSLS_MACROREPEAT_S14(MACRO,S) BSLS_MACROREPEAT_S13(MACRO,S) S MACRO(14)
#define BSLS_MACROREPEAT_S15(MACRO,S) BSLS_MACROREPEAT_S14(MACRO,S) S MACRO(15)
#define BSLS_MACROREPEAT_S16(MACRO,S) BSLS_MACROREPEAT_S15(MACRO,S) S MACRO(16)
#define BSLS_MACROREPEAT_S17(MACRO,S) BSLS_MACROREPEAT_S16(MACRO,S) S MACRO(17)
#define BSLS_MACROREPEAT_S18(MACRO,S) BSLS_MACROREPEAT_S17(MACRO,S) S MACRO(18)
#define BSLS_MACROREPEAT_S19(MACRO,S) BSLS_MACROREPEAT_S18(MACRO,S) S MACRO(19)
#define BSLS_MACROREPEAT_S20(MACRO,S) BSLS_MACROREPEAT_S19(MACRO,S) S MACRO(20)

#endif // ! defined(INCLUDED_BSLS_MACROREPEAT)

// ----------------------------------------------------------------------------
// Copyright 2013 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------