bsls_macrorepeat.h

Go to the documentation of this file.

/// @file bsls_macrorepeat.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bsls_macrorepeat.h                                                 -*-C++-*-
#ifndef INCLUDED_BSLS_MACROREPEAT
#define INCLUDED_BSLS_MACROREPEAT
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bsls_macrorepeat bsls_macrorepeat
/// @brief  repeat a macro invocation with different numeric arguments.
/// @addtogroup bsl
/// @{
/// @addtogroup bsls
/// @{
/// @addtogroup bsls_macrorepeat
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bsls_macrorepeat-purpose"> Purpose</a>
/// * <a href="#bsls_macrorepeat-classes"> Classes </a>
/// * <a href="#bsls_macrorepeat-macros"> Macros </a>
/// * <a href="#bsls_macrorepeat-description"> Description </a>
///   * <a href="#bsls_macrorepeat-usage"> Usage </a>
///     * <a href="#bsls_macrorepeat-example-1-repeated-template-instantiation"> Example 1: Repeated Template Instantiation </a>
///     * <a href="#bsls_macrorepeat-example-2-repeated-function-arguments"> Example 2: Repeated Function Arguments </a>
///     * <a href="#bsls_macrorepeat-example-3-bitmask-computation"> Example 3: Bitmask Computation </a>
///
/// # Purpose {#bsls_macrorepeat-purpose}
/// repeat a macro invocation with different numeric arguments.
///
/// # Classes {#bsls_macrorepeat-classes}
///
///
/// # Macros {#bsls_macrorepeat-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 
///
/// # Description {#bsls_macrorepeat-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:
/// @code
/// #define FOO(n) foo ## n
/// doit(BSLS_MACROREPEAT_COMMA(5, FOO));
/// @endcode
/// will expand FOO(n) with arguments 1 through 5, inserting commas between the
/// expansions, resulting in:
/// @code
/// doit(foo1, foo2, foo3, foo4, foo5);
/// @endcode
/// 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 {#bsls_macrorepeat-usage}
///
///
/// The following examples demonstrate potential uses of the macros in this
/// component.
///
/// ### Example 1: Repeated Template Instantiation {#bsls_macrorepeat-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:
/// @code
/// int total = 0;
/// template <int V> void foo() { total += V; }
/// @endcode
/// 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:
/// @code
/// 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;
/// }
/// @endcode
///
/// ### Example 2: Repeated Function Arguments {#bsls_macrorepeat-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:
/// @code
/// #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);
/// }
/// @endcode
/// 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)`:
/// @code
/// int main() {
///     char buffer[20];
///     int i = 8;
///     #define X(x) (i)
/// @endcode
/// 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:
/// @code
///     fmtQuartet(buffer, "%d %d %d %d", 7, BSLS_MACROREPEAT_COMMA(3, X));
///     assert(0 == std::strcmp(buffer, "7 8 8 8"));
///     return 0;
/// }
/// @endcode
///
/// ### Example 3: Bitmask Computation {#bsls_macrorepeat-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:
/// @code
/// #define BITVAL(B) (1 << (B - 1))
/// @endcode
/// Then we use the `BSLS_MACROREPEAT_SEP` to invoke `BITVAL` 7 times,
/// separating the repetitions with the bitwise OR operator:
/// @code
/// const unsigned mask = BSLS_MACROREPEAT_SEP(7, BITVAL, |);
///
/// int main() {
///     assert(127 == mask);
///     return 0;
/// }
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bsls
 * @{
 */
/** @addtogroup bsls_macrorepeat
 * @{
 */
 
/// 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(N, MACRO) BSLS_MACROREPEAT_##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_COMMA(N, MACRO) BSLS_MACROREPEAT_C##N(MACRO)
 
/// 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.
#define BSLS_MACROREPEAT_SEP(N, MACRO, S) BSLS_MACROREPEAT_S##N(MACRO, S)
 
// ============================================================================
//                           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 ----------------------------------
 
/** @} */
/** @} */
/** @} */