Macros
#define	BSLA_DEPRECATED

#define	BSLA_DEPRECATED_MESSAGE(message)

Detailed Description

Outline

Purpose
Macros
Description
- Macro Reference
- Usage
  - Example 1: Various Deprecations

Purpose

Provide compiler-hint macros to indicate deprecated entities.

Macros

BSLA_DEPRECATED: warn if annotated (deprecated) entity is used
BSLA_DEPRECATED_MESSAGE: warn with message if annotated entity is used
BSLA_DEPRECATED_IS_ACTIVE: defined if both macros are active

See also: bsla_annotations

Description

This component provides preprocessor macros that hint to the compiler that a function, variable, type, typedef, struct member, enum type, or template specialization is deprecated. This is useful, for example, when identifying functions that are expected to be removed in a future version of a library.

Macro Reference

BSLA_DEPRECATED: This annotation will, when used, cause a compile-time warning if the so-annotated function, variable, type, typedef, struct member, enum type, or template specialization is used anywhere within the source file. The warning includes the location of the declaration of the deprecated entity to enable users to find further information about the deprecation, or what they should use instead.

BSLA_DEPRECATED_MESSAGE(QUOTED_MESSAGE): This annotation will, when used, cause a compile-time warning if the so-annotated function, variable, type, typedef, struct member, enum type, or template specialization is used anywhere within the source file. The compiler warning will contain the contents of the specified QUOTED_MESSAGE, which must be a double-quoted string. The warning includes the location of the declaration of the deprecated entity to enable users to find further information about the deprecation, and what they should use instead. Note that on some compilers QUOTED_MESSAGE is ignored.

BSLA_DEPRECATED_IS_ACTIVE: The macro BSLA_DEPRECATED_IS_ACTIVE is defined if BSLA_DEPRECATED and BSLA_DEPRECATED_MESSAGE are both active and have the desired effect; otherwise, BSLA_DEPRECATED_IS_ACTIVE is not defined and both other macros expand to nothing.

Usage

This section illustrates intended use of this component.

Example 1: Various Deprecations

First, we define a deprecated type UsageType:

struct BSLA_DEPRECATED UsageType {
    int d_int;
};

Then, we define a function usageFunc that is deprecated:

BSLA_DEPRECATED
void usageFunc();
void usageFunc()
{
    printf("Don't call me.\n");
}

Next, we define a variable usageVar that is deprecated:

BSLA_DEPRECATED extern int usageVar;

int usageVar = 5;

Then, we define a typedef UsageTypedef that is deprecated:

BSLA_DEPRECATED typedef int UsageTypedef;

Next, we define a struct with a member d_y that is deprecated:

struct UsageStruct {
    double                 d_x;
    BSLA_DEPRECATED double d_y;
};

Then, we define an enum UsageEnum that is deprecated:

enum BSLA_DEPRECATED UsageEnum { e_FALSE, e_TRUE };

Next, we define a template this is only deprecated in the case where it is specialized with the int type as a template parameter:

template <class TYPE>
TYPE usageAbs(TYPE x)
{
    return x < 0 ? -x : x;
}
 
template <>
BSLA_DEPRECATED_MESSAGE("'int' specialization not allowed")
int usageAbs<int>(int x)
{
    int ret = x < 0 ? -x : x;
    return ret < 0 ? ~ret : ret;
}

Then, as long as we don't use them, no warnings will be issued.

Next, we use UsageType:

UsageType ut;
ut.d_int = 5;
(void) ut.d_int;