bsls_bslexceptionutil.h

Go to the documentation of this file.

/// @file bsls_bslexceptionutil.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bsls_bslexceptionutil.h                                            -*-C++-*-
#ifndef INCLUDED_BSLS_BSLEXCEPTIONUTIL
#define INCLUDED_BSLS_BSLEXCEPTIONUTIL
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bsls_bslexceptionutil bsls_bslexceptionutil
/// @brief  Provide functions for use in `bsl` that throw standard exceptions.
/// @addtogroup bsl
/// @{
/// @addtogroup bsls
/// @{
/// @addtogroup bsls_bslexceptionutil
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bsls_bslexceptionutil-purpose"> Purpose</a>
/// * <a href="#bsls_bslexceptionutil-classes"> Classes </a>
/// * <a href="#bsls_bslexceptionutil-description"> Description </a>
///   * <a href="#bsls_bslexceptionutil-usage"> Usage </a>
///     * <a href="#bsls_bslexceptionutil-example-1-throwing-a-standard-exception"> Example 1: Throwing a standard exception </a>
///
/// # Purpose {#bsls_bslexceptionutil-purpose}
/// Provide functions for use in `bsl` that throw standard exceptions.
///
/// # Classes {#bsls_bslexceptionutil-classes}
///
/// -  bsls::BslExceptionUtil: namespace for utilities to throw exceptions
///
/// @see  bsl_exception, bsl_new, bsl_typeinfo
///
/// # Description {#bsls_bslexceptionutil-description}
/// This component provides a means to throw standard exceptions
/// without introducing a compile-time dependency on the standard exception
/// classes.  This is valuable where header files define function templates or
/// inline functions that may throw these types as exceptions.
///
/// ## Usage {#bsls_bslexceptionutil-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Throwing a standard exception {#bsls_bslexceptionutil-example-1-throwing-a-standard-exception}
///
///
/// Suppose we are implementing a class that must conform to the requirements of
/// the C++ Standard.  There are several clauses that dictate throwing an
/// exception of a standard type to indicate failure.  However, we do not want
/// to expose the standard exception header to our clients, which would be
/// typical when implementing function templates inline, and we want to have a
/// consistent behavior when building with a compiler in a non-standard mode
/// that does not support exceptions.
///
/// First we declare a function template that wants to throw a standard
/// exception.  Note that the `exception` header is not included at this point.
/// @code
/// #include <bsls_bslexceptionutil.h>
///
/// template<typename T>
/// void testFunction(int selector)
///     //  Throw a standard exception according to the specified 'selector'.
/// {
///   switch (selector) {
/// @endcode
///  Now we can use the utilities in this component to throw the desired
///  exception, even though the standard exception classes are not visible to
///  this code.
/// @code
///     case  1: bsls::BslExceptionUtil::throwBadAlloc();
///     case  2: bsls::BslExceptionUtil::throwBadCast();
///     default: bsls::BslExceptionUtil::throwException();
///   }
/// }
/// @endcode
/// Finally, we can write some client code that calls our function, and wishes
/// to catch the thrown exception.  Observe that this file must #include the
/// corresponding standard header in order to catch the exception.
/// @code
/// #include <exception>
/// #include <new>
/// #include <typeinfo>
///
/// void callTestFunction()
/// {
///     try {
///         testFunction<int>(1);
///         assert(0 == "Should throw before reaching here.");
///     }
///     catch (const std::bad_alloc& ex) {
///     }
///
///     try {
///         testFunction<double>(2);
///         assert(0 == "Should throw before reaching here.");
///     }
///     catch (const std::bad_cast& ex) {
///     }
/// }
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bsls
 * @{
 */
/** @addtogroup bsls_bslexceptionutil
 * @{
 */
 
#include <bsls_annotation.h>
#include <bsls_compilerfeatures.h>
#include <bsls_platform.h>
 
 
 
namespace bsls {
 
                        //=======================
                        // class BslExceptionUtil
                        //=======================
 
/// This `struct` provides a namespace for `static` utility functions that
/// throw standard library exceptions.
///
/// See @ref bsls_bslexceptionutil 
struct BslExceptionUtil {
 
    // CLASS METHODS
 
    /// Throw a `bsl::bad_alloc` exception if exceptions are enabled in the
    /// current build mode, otherwise abort the program.  `bsl::bad_alloc`
    /// will be an alias for the platform's `std::bad_alloc` class, to
    /// ensure both ABI and API compatibility with non-BDE code relying on
    /// the standard exception hierarchy.
    BSLS_ANNOTATION_NORETURN
    static void throwBadAlloc();
 
    /// Throw a `bsl::bad_cast` exception if exceptions are enabled in the
    /// current build mode, otherwise abort the program.  `bsl::bad_cast`
    /// will be an alias for the platform's `std::bad_cast` class, to ensure
    /// both ABI and API compatibility with non-BDE code relying on the
    /// standard exception hierarchy.
    BSLS_ANNOTATION_NORETURN
    static void throwBadCast();
 
    /// Throw a `bsl::bad_exception` exception if exceptions are enabled in
    /// the current build mode, otherwise abort the program.
    /// `bsl::bad_exception` will be an alias for the platform's
    /// `std::bad_exception` class, to ensure both ABI and API compatibility
    /// with non-BDE code relying on the standard exception hierarchy.
    BSLS_ANNOTATION_NORETURN
    static void throwBadException();
 
    /// Throw a `bsl::bad_typeid` exception if exceptions are enabled in the
    /// current build mode, otherwise abort the program.  `bsl::bad_typeid`
    /// will be an alias for the platform's `std::bad_typeid` class, to
    /// ensure both ABI and API compatibility with non-BDE code relying on
    /// the standard exception hierarchy.
    BSLS_ANNOTATION_NORETURN
    static void throwBadTypeid();
 
    /// Throw a `bsl::exception` exception if exceptions are enabled in the
    /// current build mode, otherwise abort the program.  `bsl::exception`
    /// will be an alias for the platform's `std::exception` class, to
    /// ensure both ABI and API compatibility with non-BDE code relying on
    /// the standard exception hierarchy.
    BSLS_ANNOTATION_NORETURN
    static void throwException();
};
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2013 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */