bsls_cpp11.h

Go to the documentation of this file.

/// @file bsls_cpp11.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bsls_cpp11.h                                                       -*-C++-*-
#ifndef INCLUDED_BSLS_CPP11
#define INCLUDED_BSLS_CPP11
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bsls_cpp11 bsls_cpp11
/// @brief  Provide macros for C++11 forward compatibility.
/// @addtogroup bsl
/// @{
/// @addtogroup bsls
/// @{
/// @addtogroup bsls_cpp11
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bsls_cpp11-purpose"> Purpose</a>
/// * <a href="#bsls_cpp11-classes"> Classes </a>
/// * <a href="#bsls_cpp11-macros"> Macros </a>
/// * <a href="#bsls_cpp11-description"> Description </a>
///   * <a href="#bsls_cpp11-macro-summary"> Macro Summary </a>
///   * <a href="#bsls_cpp11-usage"> Usage </a>
///     * <a href="#bsls_cpp11-example-1-preparing-c-03-code-for-c-11-features"> Example 1: Preparing C++03 Code for C++11 Features </a>
///
/// # Purpose {#bsls_cpp11-purpose}
/// Provide macros for C++11 forward compatibility.
///
/// @deprecated  Use @ref bsls_keyword  instead.
///
/// # Classes {#bsls_cpp11-classes}
///
///
/// # Macros {#bsls_cpp11-macros}
///
/// -  BSLS_CPP11_CONSTEXPR: C++11 `constexpr` keyword
/// -  BSLS_CPP11_DELETED: C++11 `= delete` function definition
/// -  BSLS_CPP11_EXPLICIT: C++11 `explicit` for conversion operators
/// -  BSLS_CPP11_FINAL: C++11 `final` keyword
/// -  BSLS_CPP11_NOEXCEPT: C++11 `noexcept` keyword
/// -  BSLS_CPP11_NOEXCEPT_AVAILABLE: `C++11` `noexcept` flag
/// -  BSLS_CPP11_NOEXCEPT_SPECIFICATION(...): C++11 `noexcept` function qualifier
/// -  BSLS_CPP11_NOEXCEPT_OPERATOR(expr): C++11 `noexcept` operation
/// -  BSLS_CPP11_OVERRIDE: C++11 `override` keyword
/// -  BSLS_CPP11_PROVISIONALLY_FALSE: C++11 specification placeholder
///
/// # Description {#bsls_cpp11-description}
/// This component provides definitions to use C++11 features in
/// both C++03 and C++11 without using conditional compilation where the
/// features are used.  The goal is to allow implementation of components such
/// that they can take advantage of some C++11 features when compiled with C++11
/// mode enabled while also correctly compiling in C++03 mode.  The
/// functionality of the respective features won't be available in C++03 mode.
///
/// ## Macro Summary {#bsls_cpp11-macro-summary}
///
///
/// The following are the macros provided by this component.
///
///  `BSLS_CPP11_CONSTEXPR`:
///      **DEPRECATED**: Use `BSLS_KEYWORD_CONSTEXPR` instead.  This macro inserts
///      the keyword `constexpr` when compiling with C++11 mode and inserts
///      nothing when compiling with C++03 mode.
/// 
///  `BSLS_CPP11_DELETED`:
///      **DEPRECATED**: Use `BSLS_KEYWORD_DELETED` instead.  This macro inserts
///      the text `= delete` when compiling with C++11 mode and inserts nothing
///      when compiling with C++03 mode.
/// 
///  `BSLS_CPP11_EXPLICIT`:
///      **DEPRECATED**: Use `BSLS_KEYWORD_EXPLICIT` instead.  This macro inserts
///      the keyword `explicit` when compiling with C++11 mode and inserts
///      nothing when compiling with C++03 mode.
/// 
///  `BSLS_CPP11_FINAL`:
///      **DEPRECATED**: Use `BSLS_KEYWORD_FINAL` instead.  This macro inserts the
///      keyword `final` when compiling with C++11 mode and inserts nothing when
///      compiling with C++03 mode.
/// 
///  `BSLS_CPP11_NOEXCEPT`:
///      **DEPRECATED**: Use `BSLS_KEYWORD_NOEXCEPT` instead.  This macro inserts
///      the keyword `noexcept` when compiling with C++11 mode and inserts
///      nothing when compiling with C++03 mode.
/// 
///  `BSLS_CPP11_NOEXCEPT_AVAILABLE`:
///      **DEPRECATED**: Use `BSLS_KEYWORD_NOEXCEPT_AVAILABLE` instead.  This
///      macro expands to `true` when the `noexcept` feature is available and
///      `false` otherwise.
/// 
///  `BSLS_CPP11_NOEXCEPT_SPECIFICATION(BOOL_EXPRESSION)`:
///      **DEPRECATED**: Use `BSLS_KEYWORD_NOEXCEPT_SPECIFICATION` instead.  This
///      macro inserts the exception specification `noexcept(BOOL_EXPRESSION)`
///      when compiling with C++11 mode and inserts nothing when compiling with
///      C++03 mode.  This macro is used to specify which version of `noexcept`
///      is intended when multiple `noexcept`s are used in a single statement.
/// 
///  `BSLS_CPP11_NOEXCEPT_OPERATOR(expr)`:
///      **DEPRECATED**: Use `BSLS_KEYWORD_NOEXCEPT_OPERATOR` instead.  This macro
///      inserts the operation `noexcept(expr)` when compiling with C++11 mode
///      and inserts the literal `false` when compiling with C++03 mode.
/// 
///  `BSLS_CPP11_OVERRIDE`
///      **DEPRECATED**: Use `BSLS_KEYWORD_OVERRIDE` instead.  This macro inserts
///      the keyword `override` when compiling with C++11 mode and inserts
///      nothing when compiling with C++03 mode.
/// 
///  `BSLS_CPP11_PROVISIONALLY_FALSE`:
///      **DEPRECATED**: Use `false` instead.  This macro inserts the keyword
///      `false`.  This macro is intended to be used as a placeholder in the
///      `BSLS_CPP11_NOEXCEPT_SPECIFICATION(BOOL_EXPRESSION)` macro when
///      traits needed for `BOOL_EXPRESSION` have not yet been implemented.
///
/// ## Usage {#bsls_cpp11-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Preparing C++03 Code for C++11 Features {#bsls_cpp11-example-1-preparing-c-03-code-for-c-11-features}
///
///
/// To use these macros, simply insert them where the corresponding C++11
/// keyword would go.  When compiling with C++03 mode there will be no effect
/// but when compiling with C++11 mode additional restrictions will apply.  When
/// compiling with C++11 mode the restriction will be checked providing some
/// additional checking over what is done with C++11.
///
/// C++ uses the `explicit` keyword to indicate that constructors taking just
/// one argument are not considered for implicit conversions.  Instead, they can
/// only be used for explicit conversions.  C++ also provides the ability to
/// define conversion operators but prior to C++11 these conversion operators
/// are considered for implicit conversion.  C++11 allows the use of the
/// `explicit` keyword with conversion operators to avoid its use for implicit
/// conversions.  The macro `BSLS_CPP11_EXPLICIT` can be used to mark
/// conversions as explicit conversions which will be checked when compiling
/// with C++11 mode.  For example, an `Optional` type may have an explicit
/// conversion to `bool` to indicate that the value is set (note the conversion
/// operator):
/// @code
/// template <class TYPE>
/// class Optional
/// {
///     TYPE* d_value;
/// public:
///     Optional(): d_value() {}
///     explicit Optional(const TYPE& value): d_value(new TYPE(value)) {}
///     ~Optional() { delete d_value; }
///     // ...
///
///     BSLS_CPP11_EXPLICIT operator bool() const { return d_value; }
/// };
/// @endcode
/// When using an object of the `Optional` class in a condition it is desirable
/// that it converts to a `bool`:
/// @code
/// Optional<int> value;
/// if (value) { /*... */ }
/// @endcode
/// In places where an implicit conversion takes place it is not desirable that
/// the conversion is used.  When compiling with C++11 mode the conversion
/// operator will not be used, e.g., the following code will result in an error:
/// @code
/// bool flag = value;
/// @endcode
/// When defining conversion operators to `bool` for code which needs to compile
/// with C++03 mode the conversion operator should convert to a member pointer
/// type instead: doing so has a similar effect to making the conversion
/// operator `explicit`.
///
/// Some classes are not intended for use as a base class.  To clearly label
/// these classes and enforce that they can't be derived from C++11 allows using
/// the `final` keyword after the class name in the class definition to label
/// classes which are not intended to be derived from.  The macro
/// `BSLS_CPP11_FINAL` is replaced by `final` when compiling with C++11 causing
/// the compiler to enforce that a class can't be further derived.  The code
/// below defines a class which can't be derived from:
/// @code
/// class FinalClass BSLS_CPP11_FINAL
/// {
///     int d_value;
///   public:
///     explicit FinalClass(int value = 0): d_value(value) {}
///     int value() const { return d_value; }
/// };
/// @endcode
/// An attempt to derive from this class will fail when compiling with C++11
/// mode:
/// @code
/// class FinalClassDerived: public FinalClass {
///     int d_anotherValue;
/// public:
///     explicit FinalClassDerived(int value)
///         : d_anotherValue(2 * value) {
///     }
///     int anotherValue() const { return d_anotherValue; }
/// };
/// @endcode
/// The code will compile successfully when using C++03 mode.
///
/// Sometime it is useful to declare that an overriding function is the final
/// overriding function and further derived classes won't be allowed to further
/// override the function.  One use of this feature could be informing the
/// compiler that it won't need to use virtual dispatch when calling this
/// function on a pointer or a reference of the corresponding type.  C++11
/// allows marking functions as the final overrider using the keyword `final`.
/// The macro `BSLS_CPP11_FINAL` can also be used for this purpose.  To
/// demonstrate the use of this keyword first a base class with a `virtual`
/// function is defined:
/// @code
/// struct FinalFunctionBase
/// {
///     virtual int f() { return 0; }
/// };
/// @endcode
/// When defining a derived class this function `f` can be marked as the final
/// overrider using `BSLS_CPP11_FINAL`:
/// @code
/// struct FinalFunctionDerived: FinalFunctionBase
/// {
///     int f() BSLS_CPP11_FINAL { return 1; }
/// };
/// @endcode
/// The semantics of the overriding function aren't changed but a further
/// derived class can't override the function `f`, i.e., the following code will
/// result in an error when compiling with C++11 mode:
/// @code
/// struct FinalFunctionFailure: FinalFunctionDerived
/// {
///     int f() { return 2; }
/// };
/// @endcode
/// With C++03 mode the code will successfully compile.
///
/// The C++11 keyword `override` is used to identify functions overriding a
/// `virtual` function from a base class.  If a function identified as
/// `override` does not override a `virtual` function from a base class the
/// compilation results in an error.  The macro `BSLS_CPP11_OVERRIDE` is used to
/// insert the `override` keyword when compiling with C++11 mode.  When
/// compiling with C++03 mode it has no effect but it both cases it documents
/// that a function is overriding a `virtual` function from a base class.  To
/// demonstrate the use of the `BSLS_CPP11_OVERRIDE` macro first a base class is
/// defined:
/// @code
/// struct OverrideBase
/// {
///     virtual int f() const { return 0; }
/// };
/// @endcode
/// When overriding `OverrideBase::f` in a derived class the
/// `BSLS_CPP11_OVERRIDE` macro should be used to ascertain that the function in
/// the derived class is indeed overriding a `virtual` function:
/// @code
/// struct OverrideSuccess: OverrideBase
/// {
///     int f() const BSLS_CPP11_OVERRIDE { return 1; }
/// };
/// @endcode
/// The above code compiles successfully with both C++03 mode and C++11.  When
/// the function meant to be an override actually isn't overriding any function
/// the compilation will fail when using C++11 mode as is demonstrated by the
/// following example (note the missing `const` in the function declaration):
/// @code
/// struct OverrideFailure: OverrideBase
/// {
///     int f() BSLS_CPP11_OVERRIDE { return 2; }
/// };
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bsls
 * @{
 */
/** @addtogroup bsls_cpp11
 * @{
 */
 
#include <bsls_keyword.h>
 
#define BSLS_CPP11_CONSTEXPR BSLS_KEYWORD_CONSTEXPR
 
#define BSLS_CPP11_DELETED BSLS_KEYWORD_DELETED
 
#define BSLS_CPP11_NOEXCEPT BSLS_KEYWORD_NOEXCEPT
#define BSLS_CPP11_NOEXCEPT_AVAILABLE BSLS_KEYWORD_NOEXCEPT_AVAILABLE
#define BSLS_CPP11_NOEXCEPT_SPECIFICATION(...) \
                               BSLS_KEYWORD_NOEXCEPT_SPECIFICATION(__VA_ARGS__)
#define BSLS_CPP11_NOEXCEPT_OPERATOR(...) \
                                    BSLS_KEYWORD_NOEXCEPT_OPERATOR(__VA_ARGS__)
#define BSLS_CPP11_PROVISIONALLY_FALSE false
 
#define BSLS_CPP11_EXPLICIT BSLS_KEYWORD_EXPLICIT
 
#define BSLS_CPP11_FINAL BSLS_KEYWORD_FINAL
 
#define BSLS_CPP11_OVERRIDE BSLS_KEYWORD_OVERRIDE
 
// ----------------------------------------------------------------------------
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2015 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */