bsla_deprecated Component

Provide compiler-hint macros to indicate deprecated entities. More...

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	1 if both macros are active, 0 if both inactive

See also:: Component 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 to 0 if BSLA_DEPRECATED and BSLA_DEPRECATED_MESSAGE both expand to nothing and 1 if they are both enabled and have the desired effect. Either both of them work or neither works.

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;