// bsls_cpp11.h                                                       -*-C++-*-
#ifndef INCLUDED_BSLS_CPP11
#define INCLUDED_BSLS_CPP11

#include <bsls_ident.h>
BSLS_IDENT("$Id: $")

//@PURPOSE: Provide macros for C++11 forward compatibility.
//
//@DEPRECATED: Use `bsls_keyword` instead.
//
//@CLASSES:
//
//@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: 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
///-------------
// 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
///-----
// This section illustrates intended use of this component.
//
///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):
// ```
// 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; }
// };
// ```
// When using an object of the `Optional` class in a condition it is desirable
// that it converts to a `bool`:
// ```
// Optional<int> value;
// if (value) { /*... */ }
// ```
// 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:
// ```
// bool flag = value;
// ```
// 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:
// ```
// class FinalClass BSLS_CPP11_FINAL
// {
//     int d_value;
//   public:
//     explicit FinalClass(int value = 0): d_value(value) {}
//     int value() const { return d_value; }
// };
// ```
// An attempt to derive from this class will fail when compiling with C++11
// mode:
// ```
// class FinalClassDerived: public FinalClass {
//     int d_anotherValue;
// public:
//     explicit FinalClassDerived(int value)
//         : d_anotherValue(2 * value) {
//     }
//     int anotherValue() const { return d_anotherValue; }
// };
// ```
// 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:
// ```
// struct FinalFunctionBase
// {
//     virtual int f() { return 0; }
// };
// ```
// When defining a derived class this function `f` can be marked as the final
// overrider using `BSLS_CPP11_FINAL`:
// ```
// struct FinalFunctionDerived: FinalFunctionBase
// {
//     int f() BSLS_CPP11_FINAL { return 1; }
// };
// ```
// 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:
// ```
// struct FinalFunctionFailure: FinalFunctionDerived
// {
//     int f() { return 2; }
// };
// ```
// 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:
// ```
// struct OverrideBase
// {
//     virtual int f() const { return 0; }
// };
// ```
// 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:
// ```
// struct OverrideSuccess: OverrideBase
// {
//     int f() const BSLS_CPP11_OVERRIDE { return 1; }
// };
// ```
// 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):
// ```
// struct OverrideFailure: OverrideBase
// {
//     int f() BSLS_CPP11_OVERRIDE { return 2; }
// };
// ```

#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 ----------------------------------
