29/// * <a href="#bsla_scanf-example-1-populate-a-sequence-of-ints-and-floats-with-random-numbers"> Example 1: Populate a Sequence of ints and floats with Random Numbers </a>
30///
31/// # Purpose {#bsla_scanf-purpose}
32/// Provide a macro for checking `scanf`-style format strings.
33///
34/// # Macros {#bsla_scanf-macros}
35///
36/// - BSLA_SCANF(FMTIDX, STARTIDX): validate `scanf` format and arguments
37/// - BSLA_SCANF_IS_ACTIVE: defined if `BSLA_SCANF` is active
38///
39/// @see bsla_annotations
40///
41/// # Description {#bsla_scanf-description}
42/// This component provides a preprocessor macro that indicates
43/// that one of the arguments to a function is a `scanf`-style format string,
44/// and that the arguments starting at a certain index are to be checked for
64/// The macro `BSLA_SCANF_IS_ACTIVE` is defined if `BSLA_SCANF` expands to
65/// something with the desired effect; otherwise `BSLA_SCANF_IS_ACTIVE` is
66/// not defined and `BSLA_SCANF` expands to nothing.
67///
68/// ## Usage {#bsla_scanf-usage}
69///
70///
71/// This section illustrates intended use of this component.
72///
73/// ### Example 1: Populate a Sequence of ints and floats with Random Numbers {#bsla_scanf-example-1-populate-a-sequence-of-ints-and-floats-with-random-numbers}
74///
75///
76/// Suppose we want to have a function that will populate a list of `int`s and
77/// `float`s with random numbers in the range `[ 0 .. 100 )`.
78///
79/// First, we define our function:
80/// @code
81/// int populateValues(const char *format, ...) BSLA_SCANF(1, 2);
82/// // Use 'rand' to populate 'int's and 'float's, passed by pointer after
83/// // the specified 'format', which will specify the types of the
84/// // variables passed. Return the number of variables populated, or -1
85/// // if the format string is invalid.
86///
87/// int populateValues(const char *format, ...)
88/// {
89/// int ret = 0;
90///
91/// va_list ap;
92/// va_start(ap, format);
93///
94/// for (const char *pc = format; *pc; ++pc) {
95/// if ('%' != *pc) {
96/// continue;
97/// }
98/// const char c = *++pc;
99/// if ('%' == c) {
100/// continue;
101/// }
102/// else if ('d' == c) {
103/// * va_arg(ap, int *) = static_cast<unsigned>(rand()) % 100;
104/// }
105/// else if ('f' == c || 'e' == c || 'g' == c) {
106/// const int characteristic = static_cast<unsigned>(rand()) % 100;
107/// const int mantissa = static_cast<unsigned>(rand()) % 1000;
1.9.8