bsla_unused

Macros
#define	BSLA_UNUSED

Detailed Description

Outline

• Purpose
• Macros
• Description
  • Macro Reference
  • Usage
    • Example 1: "Unused" Warnings

Purpose

Provide a macro to suppress "unused" warnings.

Deprecated:

Use bsla_maybeunused instead.

Macros

• BSLA_UNUSED: do not warn if annotated entity is unused
• BSLA_UNUSED_IS_ACTIVE: defined if BSLA_UNUSED is active

See also

bsla_annotations, bsla_maybeunused

Description

This component provides a preprocessor macro that will suppress "unused" warnings on a locally defined function, type, or variable that is not used.

Note that the similar macro, BSLA_MAYBE_UNUSED, aliasing the standard [[maybe_unused]] attribute, may be considered for use instead of this macro.

Macro Reference

BSLA_UNUSED: This annotation indicates that the so-annotated function, variable, or type is possibly unused and the compiler should not generate a warning for the unused identifier.

BSLA_UNUSED_IS_ACTIVE: The macro BSLA_UNUSED_IS_ACTIVE is defined if BSLA_UNUSED expands to something with the desired effect; otherwise BSLA_UNUSED_IS_ACTIVE is not defined and BSLA_UNUSED expands to nothing.

Usage

This section illustrates intended use of this component.

Example 1: "Unused" Warnings

First, we define a namespace, warn, within the unnamed namespace with a type, a function, and a variable in it. They are unused:

namespace {
namespace warn {
 
double x;
 
struct ResultRec {
    double d_x;
    double d_y;
};
 
/// Solve the quadratic function for the specified 'a', 'b', and 'c',
/// where '0 = a * x^2 + b * x + c'.  If the quadratic has no solutions,
/// return a non-zero value, and set the specified 'zeroA' and 'zeroB'
/// to those solutions and return 0 otherwise.  The specified
/// 'cubeFactor' and 'zeroC' are unused for now but will be used in
/// future expansion of the function to handle cubic polynomials.
int quadratic(double *zeroA,
              double *zeroB,
              double *zeroC,
              double cubeFactor,
              double a,
              double b,
              double c)
{
    const double discriminant = b * b - 4 * a * c;
    if (discriminant < 0 || 0.0 == a) {
        *zeroA = *zeroB = 0.0;
        return -1;                                                // RETURN
    }
 
    const double root = ::sqrt(discriminant);
    *zeroA = (-b + root) / (2 * a);
    *zeroB = (-b - root) / (2 * a);
 
    return 0;
}
 
}  // close namespace warn
}  // close unnamed namespace

Then, we observe the warnings:

.../bsla_unused.t.cpp:135:27: warning: unused parameter 'zeroC'
[-Wunused-parameter]
               double *zeroC,
               ~~~~~~~~^~~~~
.../bsla_unused.t.cpp:136:26: warning: unused parameter 'cubeFactor'
[-Wunused-parameter]
               double cubeFactor,
               ~~~~~~~^~~~~~~~~~
.../bsla_unused.t.cpp:133:9: warning: 'int {anonymous}::warn::
quadratic(double*, double*, double*, double, double, double, double)'
defined but not used [-Wunused-function]
 int quadratic(double *zeroA,
     ^~~~~~~~~
.../bsla_unused.t.cpp:126:12: warning: '{anonymous}::warn::x' defined but
not used [-Wunused-variable]
 double x;
        ^

Note that none of the compilers currently in use by the development team issue a warning on the unused warn::ResultRec, but some in the future might. In the meantime, BSLA_UNUSED is tolerated on type declarations without resulting in a syntax error.

Next, we define a namespace, nowarn, within the unused namespace with exactly the same unused entities, using the BSLA_UNUSED annotation to silence the warnings:

namespace {
namespace nowarn {
 
struct ResultRec {
    double d_x;
    double d_y;
} BSLA_UNUSED;
 
double x BSLA_UNUSED;
 
/// Solve the quadratic function for the specified 'a', 'b', and 'c',
/// where '0 = a * x^2 + b * x + c'.  If the quadratic has no solutions,
/// return a non-zero value, and set the specified 'zeroA' and 'zeroB'
/// to those solutions and return 0 otherwise.  The specified
/// 'cubeFactor' and 'zeroC' are unused for now but will be used in
/// future expansion of the function to handle cubic polynomials.
int quadratic(double             *zeroA,
              double             *zeroB,
              BSLA_UNUSED double *zeroC,
              BSLA_UNUSED double  cubeFactor,
              double              a,
              double              b,
              double              c) BSLA_UNUSED;
 
int quadratic(double             *zeroA,
              double             *zeroB,
              BSLA_UNUSED double *zeroC,
              BSLA_UNUSED double  cubeFactor,
              double              a,
              double              b,
              double              c)
{
    const double discriminant = b * b - 4 * a * c;
    if (discriminant < 0 || 0.0 == a) {
        *zeroA = *zeroB = 0.0;
        return -1;                                                // RETURN
    }
 
    const double root = ::sqrt(discriminant);
    *zeroA = (-b + root) / (2 * a);
    *zeroB = (-b - root) / (2 * a);
 
    return 0;
}
 
}  // close namespace nowarn
}  // close unnamed namespace

Finally, we observe that the warnings for the nowarn namespace are suppressed.

Macro Definition Documentation

BSLA_UNUSED

#define BSLA_UNUSED