bslalg_scalardestructionprimitives.h

Go to the documentation of this file.

/// @file bslalg_scalardestructionprimitives.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bslalg_scalardestructionprimitives.h                               -*-C++-*-
#ifndef INCLUDED_BSLALG_SCALARDESTRUCTIONPRIMITIVES
#define INCLUDED_BSLALG_SCALARDESTRUCTIONPRIMITIVES
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bslalg_scalardestructionprimitives bslalg_scalardestructionprimitives
/// @brief  Provide primitive algorithms that destroy scalars.
/// @addtogroup bsl
/// @{
/// @addtogroup bslalg
/// @{
/// @addtogroup bslalg_scalardestructionprimitives
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bslalg_scalardestructionprimitives-purpose"> Purpose</a>
/// * <a href="#bslalg_scalardestructionprimitives-classes"> Classes </a>
/// * <a href="#bslalg_scalardestructionprimitives-description"> Description </a>
///   * <a href="#bslalg_scalardestructionprimitives-usage"> Usage </a>
///     * <a href="#bslalg_scalardestructionprimitives-example-1-destroy-int-and-an-integer-wrapper"> Example 1: Destroy int and an Integer Wrapper </a>
///
/// # Purpose {#bslalg_scalardestructionprimitives-purpose}
/// Provide primitive algorithms that destroy scalars.
///
/// @deprecated  Use @ref bslma_destructionutil  instead.
///
/// # Classes {#bslalg_scalardestructionprimitives-classes}
///
/// -  bslalg::ScalarDestructionPrimitives: namespace for scalar algorithms
///
/// @see  bslalg_scalarprimitives, bslalg_typetraits
///
/// # Description {#bslalg_scalardestructionprimitives-description}
/// This component provides utilities to destroy scalars with a
/// uniform interface, but select a different implementation according to the
/// traits possessed by the underlying type.
///
/// The trait under consideration by this component is:
/// @code
/// Trait                             Note
/// -------------------------------   -------------------------------------
/// bslmf::IsBitwiseCopyable          Expressed in English as "TYPE has the
///                                   bit-wise copyable trait", or "TYPE is
///                                   bit-wise copyable", this trait also
///                                   implies that destructor calls can be
///                                   elided with no effect on observable
///                                   behavior.
///
/// @endcode
///
/// ## Usage {#bslalg_scalardestructionprimitives-usage}
///
///
/// In this section we show intended use of this component.  Note that this
/// component is for use by the `bslstl` package.  Other clients should use the
/// STL algorithms (in header `<algorithm>` and `<memory>`).
///
/// ### Example 1: Destroy int and an Integer Wrapper {#bslalg_scalardestructionprimitives-example-1-destroy-int-and-an-integer-wrapper}
///
///
/// In this example, we will use `bslalg::ScalarDestructionPrimitives` to
/// destroy both a scalar integer and a `MyInteger` type object.  Calling the
/// `destroy` method on a scalar integer is a no-op while calling the `destroy`
/// method on an object of `MyInteger` class invokes the destructor of the
/// object.
///
/// First, we define a `MyInteger` class that represents an integer value:
/// @code
/// class MyInteger {
///     // This class represents an integer value.
///
///     // DATA
///     int d_intValue;  // integer value
///
///   public:
///     // CREATORS
///     MyInteger();
///         // Create a 'MyInteger' object having integer value '0'.
///
///     explicit MyInteger(int value);
///         // Create a 'MyInteger' object having the specified 'value'.
///
///     ~MyInteger();
///         // Destroy this object.
///
///     // ACCESSORS
///     int getValue() const;
/// };
/// @endcode
/// Then, we create an object, `myInteger`, of type `MyInteger`:
/// @code
/// bsls::ObjectBuffer<MyInteger> buffer;
/// MyInteger *myInteger = &buffer.object();
/// new (myInteger) MyInteger(1);
/// @endcode
/// Notice that we use an `ObjectBuffer` to allow us to safely invoke the
/// destructor explicitly.
///
/// Now, we define a primitive integer:
/// @code
/// int scalarInteger = 2;
/// @endcode
/// Finally, we use the uniform `bslalg::ScalarDestructionPrimitives:destroy`
/// method to destroy both `myInteger` and `scalarInteger`:
/// @code
/// bslalg::ScalarDestructionPrimitives::destroy(myInteger);
/// bslalg::ScalarDestructionPrimitives::destroy(&scalarInteger);
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bslalg
 * @{
 */
/** @addtogroup bslalg_scalardestructionprimitives
 * @{
 */
 
#include <bslscm_version.h>
 
#include <bslma_destructionutil.h>
 
#ifndef BDE_DONT_ALLOW_TRANSITIVE_INCLUDES
 
#include <cstring>  // 'memset', 'memcpy', 'memmove'
#endif // BDE_DONT_ALLOW_TRANSITIVE_INCLUDES
 
 
namespace bslalg {
 
/// This alias is defined for backward compatibility.
typedef bslma::DestructionUtil ScalarDestructionPrimitives;
 
}  // close package namespace
 
#ifndef BDE_OPENSOURCE_PUBLICATION  // BACKWARD_COMPATIBILITY
// ============================================================================
//                           BACKWARD COMPATIBILITY
// ============================================================================
 
/// This alias is defined for backward compatibility.
typedef bslalg::ScalarDestructionPrimitives bslalg_ScalarDestructionPrimitives;
#endif  // BDE_OPENSOURCE_PUBLICATION -- BACKWARD_COMPATIBILITY
 
 
 
#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 ----------------------------------
 
/** @} */
/** @} */
/** @} */