// 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 //======================= struct BslExceptionUtil { // This 'struct' provides a namespace for 'static' utility functions that // throw standard library exceptions. // CLASS METHODS BSLS_ANNOTATION_NORETURN static void throwBadAlloc(); // 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 throwBadCast(); // 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 throwBadException(); // 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 throwBadTypeid(); // 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 throwException(); // 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. }; } // 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 ----------------------------------