// bsls_bslexceptionutil.h                                            -*-C++-*-
#ifndef INCLUDED_BSLS_BSLEXCEPTIONUTIL
#define INCLUDED_BSLS_BSLEXCEPTIONUTIL

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

//@PURPOSE: Provide functions for use in `bsl` that throw standard exceptions.
//
//@CLASSES:
//  bsls::BslExceptionUtil: namespace for utilities to throw exceptions
//
//@SEE_ALSO: bsl_exception, bsl_new, bsl_typeinfo
//
//@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
///-----
// This section illustrates intended use of this component.
//
///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.
// ```
// #include <bsls_bslexceptionutil.h>
//
// template<typename T>
// void testFunction(int selector)
//     //  Throw a standard exception according to the specified 'selector'.
// {
//   switch (selector) {
// ```
//  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.
// ```
//     case  1: bsls::BslExceptionUtil::throwBadAlloc();
//     case  2: bsls::BslExceptionUtil::throwBadCast();
//     default: bsls::BslExceptionUtil::throwException();
//   }
// }
// ```
// 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.
// ```
// #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) {
//     }
// }
// ```

#include <bsls_annotation.h>
#include <bsls_compilerfeatures.h>
#include <bsls_platform.h>

namespace BloombergLP {

namespace bsls {

                        //=======================
                        // class BslExceptionUtil
                        //=======================

/// This `struct` provides a namespace for `static` utility functions that
/// throw standard library exceptions.
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
}  // close enterprise 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 ----------------------------------
