// bsla_annotations.h -*-C++-*-
#ifndef INCLUDED_BSLA_ANNOTATIONS
#define INCLUDED_BSLA_ANNOTATIONS
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
//@PURPOSE: Provide support for compiler annotations for compile-time safety.
//
//@MACROS:
// BSLA_DEPRECATED: warn if annotated (deprecated) entity is used
// BSLA_ERROR(QUOTED_MESSAGE): emit error message and fail compilation
// BSLA_FALLTHROUGH: do not warn if 'switch' 'case' falls through
// BSLA_FORMAT(FMT_IDX): validate 'printf'-style format spec in 'n'th argument
// BSLA_MAYBE_UNUSED: suppress compiler warnings on unused entities
// BSLA_NODISCARD: warn if annotated function result is not used
// BSLA_NONNULLARG(...): warn if indexed arguments are NULL
// BSLA_NONNULLARGS: warn if any arguments are NULL
// BSLA_NORETURN: issue a compiler warning if function returns normally
// BSLA_NULLTERMINATED: warn if last argument is non-NULL
// BSLA_NULLTERMINATEDAT(ARG_IDX): warn if argument at 'ARG_IDX' is non-NULL
// BSLA_PRINTF(FMTIDX, STARTIDX): validate 'printf' format and arguments
// BSLA_SCANF(FMTIDX, STARTIDX): validate 'scanf' format and arguments
// BSLA_UNUSED: do not warn if annotated entity is unused
// BSLA_USED: emit annotated entity even if not referenced
// BSLA_WARNING(QUOTED_MESSAGE): emit warning message during compilation
//
// BSLA_DEPRECATED_IS_ACTIVE: 1 if 'BSLA_DEPRECATED is active, 0 otherwise
// BSLA_ERROR_IS_ACTIVE: 1 if 'BSLA_ERROR' is active and 0 otherwise
// BSLA_FALLTHROUGH_IS_ACTIVE: 1 if 'BSLA_FALLTHROUGH' is active, else 0
// BSLA_FORMAT_IS_ACTIVE: 1 if 'BSLA_FORMAT' is active and 0 otherwise
// BSLA_MAYBE_UNUSED_IS_ACTIVE: 1 if 'BSLA_MAYBE_UNUSED' is active, else 0
// BSLA_NODISCARD_IS_ACTIVE: 1 if 'BSLA_NODISCARD' is active and 0 otherwise
// BSLA_NONNULLARG_IS_ACTIVE: 1 if 'BSLA_NONNULLARG' is active, 0 otherwise
// BSLA_NONNULLARGS_IS_ACTIVE: 1 if 'BSLA_NONNULLARGS' is active, 0 otherwise
// BSLA_NORETURN_IS_ACTIVE: 1 if 'BSLA_NORETURN' is active and 0 otherwise
// BSLA_NULLTERMINATED_IS_ACTIVE: 1 if BSLA_NULLTERMINATED is active
// BSLA_NULLTERMINATEDAT_IS_ACTIVE: 1 if BSLA_NULLTERMINATEDAT is active
// BSLA_PRINTF_IS_ACTIVE: 1 if 'BSLA_PRINTF' is active and 0 otherwise
// BSLA_SCANF_IS_ACTIVE: 0 if 'BSLA_SCANF' expands to nothing and 1 otherwise
// BSLA_UNUSED_IS_ACTIVE: 0 if 'BSLA_UNUSED' expands to nothing, else 1
// BSLA_USED_IS_ACTIVE: 0 if 'BSLA_USED' expands to nothing and 1 otherwise
// BSLA_WARNING_IS_ACTIVE: 0 if 'BSLA_WARNING' expands to nothing else 1
//
//@DESCRIPTION: This component exists to provide a single component whose
// header can be included to transitively include all of the annotation macros
// defined in the 'bsla' package. The macros that are transitively included by
// this component correspond to various compiler features, and can be used to
// annotate code for specific compile-time safety checks.
//
// For the most part, these compile-time annotations are supported only when
// the 'BSLS_PLATFORM_CMP_GNU' or 'BSLS_PLATFORM_CMP_CLANG' preprocessor macros
// are defined. Other compilers may implement a few annotations, but the
// macros should be expected to work only with compilers for which
// 'BSLS_PLATFORM_CMP_GNU' or 'BSLS_PLATFORM_CMP_CLANG' is defined.
//
///Macro Reference
///---------------
//: 'BSLA_DEPRECATED'
//: This annotation will, when used, cause a compile-time warning if the
//: so-annotated function, variable, or type is used anywhere within the
//: source file. This is useful, for example, when identifying functions
//: that are expected to be removed in a future version of a library. 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_ERROR(QUOTED_MESSAGE)'
//: This annotation, when used, will cause a compile-time error when a call
//: to the so-annotated function is not removed through dead-code
//: elimination or other optimizations. While it is possible to leave the
//: function undefined, thus incurring a link-time failure, with the use of
//: this macro the invalid call will be diagnosed earlier (i.e., at compile
//: time), and the diagnostic will include the location of the function
//: call. The message 'QUOTED_MESSAGE', which should be a double-quoted
//: string, will appear in the error message.
//
//: 'BSLA_FALLTHROUGH'
//: This annotation should be placed in a 'case' clause as the last
//: statement within a flow of control that is expected to allow control to
//: fall through instead of ending with a 'break', 'continue', or 'return'.
//: This will prevent compilers from warning about fall-through. The
//: 'BSLA_FALLTHROUGH' must be followed by a semicolon and may be nested
//: within blocks, 'if's, or 'else's.
//
//: 'BSLA_FORMAT(FMT_IDX)'
//: This annotation specifies that the so-annotated function takes an
//: argument that is a valid format string for a 'printf'-style function
//: and returns a format string that is consistent with that format. This
//: allows format strings manipulated by translation functions to be
//: checked against arguments. Without this annotation, attempting to
//: manipulate the format string via this kind of function might generate
//: warnings about non-literal formats, or fail to generate warnings about
//: mismatched arguments.
//
//: 'BSLA_MAYBE_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_NODISCARD'
//: This annotation causes a warning to be emitted if the caller of a
//: so-annotated function does not use its return value. This is useful
//: for functions where not checking the result is either a security
//: problem or always a bug, such as with the 'realloc' function.
//
//: 'BSLA_NONNULLARGS'
//: This annotation indicates that a compiler warning is to be issued if
//: any of the pointer arguments to this function are passed null.
//
//: 'BSLA_NONNULLARG(...)'
//: This annotation, passed a variable-length list of positive integers,
//: indicates that a compiler warning is to be issued if null is passed to
//: a pointer argument at any of the specified indices, where the first
//: argument of the annotated function has an index of 1.
//
//: 'BSLA_NORETURN'
//: This annotation is used to tell the compiler that a specified function
//: will not return in a normal fashion. The function can still exit via
//: other means such as throwing an exception or aborting the process.
//
//: 'BSLA_NULLTERMINATED'
//: This annotation on a variadic macro indicates that a warning should be
//: issued unless the last argument to the function is explicitly 'NULL'.
//
//: 'BSLA_NULLTERMINATEDAT(ARG_IDX)'
//: This annotation on a variadic function indicates that a warning should
//: be issued unless the argument at 'ARG_IDX' is 'NULL', where 'ARG_IDX'
//: is the number of arguments from the last, the last argument having
//: 'ARG_IDX == 0'. Thus, 'BSLA_NULLTERMINATED' is equivalent to
//: 'BSLA_NULLTERMINATEDAT(0)'.
//
//: 'BSLA_PRINTF(FMTIDX, STARTIDX)'
//: This annotation instructs the compiler to perform additional
//: compile-time checks on so-annotated functions that take 'printf'-style
//: arguments, which should be type-checked against a format string. The
//: 'FMTIDX' parameter is the one-based index to the 'const char *' format
//: string. The 'STARTIDX' parameter is the one-based index to the first
//: variable argument to type-check against that format string. For
//: example:
//..
// extern int my_printf(void *obj, const char *format, ...) BSLA_PRINTF(2, 3);
//..
//
//: 'BSLA_SCANF(FMTIDX, STARTIDX)'
//: This annotation instructs the compiler to perform additional checks on
//: so-annotated functions that take 'scanf'-style arguments, which should
//: be type-checked against a format string.
//:
//: The 'FMTIDX' parameter is the one-based index to the 'const' format
//: string. The 'STARTIDX' parameter is the one-based index to the first
//: variable argument to type-check against that format string. For
//: example:
//..
// extern int my_scanf(void *obj, const char *format, ...) BSLA_SCANF(2, 3);
//..
//
//: 'BSLA_UNREACHABLE'
//: This annotation will, when used, indicate that a given statement in a
//: code path is intended to be unreachable, causing compilers, where
//: supported, to issue warnings if there is actually a way that the code
//: can be reached. Note that the behavior is undefined if control
//: actually reaches a 'BSLA_UNREACHABLE' statement.
//
//: '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_USED'
//: This annotation indicates that the so-annotated function, variable, or
//: type must be emitted even if it appears that the variable is not
//: referenced.
//
//: 'BSLA_WARNING(QUOTED_MESSAGE)'
//: This annotation, when used, will cause a compile-time warning
//: containing the specified 'QUOTED_MESSAGE', which must be a string
//: contained in double quotes, when a call to the so-annotated function is
//: not removed through dead-code elimination or other optimizations.
//: While it is possible to leave the function undefined, thus incurring a
//: link-time failure, with the use of this macro the invalid call will be
//: diagnosed earlier (i.e., at compile time), and the diagnostic will
//: include the location of the function call.
//
//: 'BSLA_DEPRECATED_IS_ACTIVE'
//: 'BSLA_ERROR_IS_ACTIVE'
//: 'BSLA_FALLTHROUGH_IS_ACTIVE'
//: 'BSLA_FORMAT_IS_ACTIVE'
//: 'BSLA_MAYBE_UNUSED_IS_ACTIVE'
//: 'BSLA_NODISCARD_IS_ACTIVE'
//: 'BSLA_NONNULLARG_IS_ACTIVE'
//: 'BSLS_NONNULLARGS_IS_ACTIVE'
//: 'BSLA_NORETURN_IS_ACTIVE'
//: 'BSLA_NULLTERMINATED_IS_ACTIVE'
//: 'BSLA_NULLTERMINATEDAT_IS_ACTIVE'
//: 'BSLA_PRINTF_IS_ACTIVE'
//: 'BSLA_SCANF_IS_ACTIVE'
//: 'BSLA_UNREACHABLE_IS_ACTIVE'
//: 'BSLA_UNUSED_IS_ACTIVE'
//: 'BSLA_USED_IS_ACTIVE'
//: 'BSLA_WARNING_IS_ACTIVE'
//: In all cases where there is a 'BSLA_{X}' macro, there is a macro
//: 'BSLA_{X}_IS_ACTIVE' that is defined to 0 if 'BSLA_{X}' expands to
//: nothing and defined to 1 if 'BSLA_{X}' expands to something and works.
//
///Usage
///-----
// See the other 'bsla' components for usage examples for the macros offered
// (transitively) by this component.
#include <bsla_deprecated.h>
#include <bsla_error.h>
#include <bsla_fallthrough.h>
#include <bsla_format.h>
#include <bsla_maybeunused.h>
#include <bsla_nodiscard.h>
#include <bsla_nonnullarg.h>
#include <bsla_noreturn.h>
#include <bsla_nullterminated.h>
#include <bsla_printf.h>
#include <bsla_scanf.h>
#include <bsla_unreachable.h>
#include <bsla_unused.h>
#include <bsla_used.h>
#include <bsla_warning.h>
// BDE_VERIFY pragma: re-export <bsla_deprecated.h>
// BDE_VERIFY pragma: re-export <bsla_error.h>
// BDE_VERIFY pragma: re-export <bsla_fallthrough.h>
// BDE_VERIFY pragma: re-export <bsla_format.h>
// BDE_VERIFY pragma: re-export <bsla_maybeunused.h>
// BDE_VERIFY pragma: re-export <bsla_nodiscard.h>
// BDE_VERIFY pragma: re-export <bsla_nonnullarg.h>
// BDE_VERIFY pragma: re-export <bsla_noreturn.h>
// BDE_VERIFY pragma: re-export <bsla_nullterminated.h>
// BDE_VERIFY pragma: re-export <bsla_printf.h>
// BDE_VERIFY pragma: re-export <bsla_scanf.h>
// BDE_VERIFY pragma: re-export <bsla_unreachable.h>
// BDE_VERIFY pragma: re-export <bsla_unused.h>
// BDE_VERIFY pragma: re-export <bsla_used.h>
// BDE_VERIFY pragma: re-export <bsla_warning.h>
#endif
// ----------------------------------------------------------------------------
// Copyright 2019 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 ----------------------------------