bdlb_printadapter.h

Go to the documentation of this file.

/// @file bdlb_printadapter.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bdlb_printadapter.h                                                -*-C++-*-
#ifndef INCLUDED_BDLB_PRINTADAPTER
#define INCLUDED_BDLB_PRINTADAPTER
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bdlb_printadapter bdlb_printadapter
/// @brief  Provide object for streaming objects using `bdlb::PrintMethods`.
/// @addtogroup bdl
/// @{
/// @addtogroup bdlb
/// @{
/// @addtogroup bdlb_printadapter
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bdlb_printadapter-purpose"> Purpose</a>
/// * <a href="#bdlb_printadapter-classes"> Classes </a>
/// * <a href="#bdlb_printadapter-description"> Description </a>
///   * <a href="#bdlb_printadapter-usage"> Usage </a>
///     * <a href="#bdlb_printadapter-example-1-use-in-c-03"> Example 1: Use in C++03 </a>
///     * <a href="#bdlb_printadapter-example-2-use-of-printadapterutil-makeadapter"> Example 2: Use of PrintAdapterUtil::makeAdapter </a>
///     * <a href="#bdlb_printadapter-example-3-use-in-c-17-with-ctad"> Example 3: Use in C++17 With CTAD </a>
///
/// # Purpose {#bdlb_printadapter-purpose}
/// Provide object for streaming objects using `bdlb::PrintMethods`.
///
/// # Classes {#bdlb_printadapter-classes}
///
/// -  bdlb::PrintAdapter: class for streaming objects using `bdlb::PrintMethods`.
/// -  bdlb::PrintAdapterUtil: utility for constructing `bdlb::PrintAdapter`.
///
/// # Description {#bdlb_printadapter-description}
/// This component provides a template `class` that will enable any
/// object that can be streamed using `bdlb::PrintMethods` to be streamed via
/// `<<`.
///
/// Through using this `class`, one can stream an object using `operator<<` and
/// at the same time specify `level` and `spacesPerLevel` arguments to
/// appropriately indent and format the output.
///
/// ## Usage {#bdlb_printadapter-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Use in C++03 {#bdlb_printadapter-example-1-use-in-c-03}
///
///
/// Suppose we have a few `bdlb::IdentSpan` objects that we want to print, only
/// we want to stream them with `operator<<` and we want to specify non-default
/// values of `level` and `spacesPerLevel` to their streaming.
/// @code
/// const bdlb::IndexSpan a(3, 7), b(241, 22), c(23, 17);
/// @endcode
/// First, we create a typedef of 'PrintAdapter<IdentSpan>' to use:
/// @code
/// typedef bdlb::PrintAdapter<bdlb::IndexSpan> PAIS;
/// @endcode
/// Then, we create a line of dashes:
/// @code
/// const char * const line = "------------------------------------"
///                           "------------------------------------\n";
/// @endcode
/// Now, we use the `typedef` to construct temporary `PrintAdapter` objects to
/// stream our `IndexSpan` objects:
/// @code
/// cout << "    a: " << line << PAIS(&a, 2, 2)
///      << "    b: " << line << PAIS(&b, 3, 2)
///      << "    c: " << line << PAIS(&c, 4, 2);
/// @endcode
/// Finally, we see the output:
/// @code
///  a: ------------------------------------------------------------------------
///  [
///    position = 3
///    length = 7
///  ]
///  b: ------------------------------------------------------------------------
///    [
///      position = 241
///      length = 22
///    ]
///  c: ------------------------------------------------------------------------
///      [
///        position = 23
///        length = 17
///      ]
/// @endcode
///
/// ### Example 2: Use of PrintAdapterUtil::makeAdapter {#bdlb_printadapter-example-2-use-of-printadapterutil-makeadapter}
///
///
/// Suppose we have a few `bdlb::IdentSpan` objects that we want to print, only
/// we want to stream them with `operator<<` and we want to specify
/// non-default values of `level` and `spacesPerLevel` to their streaming.
/// @code
/// const bdlb::IndexSpan a(3, 7), b(241, 22), c(23, 17);
/// @endcode
/// First, we make a typedef to the namespace `struct`:
/// @code
/// typedef bdlb::PrintAdapterUtil Util;
/// @endcode
/// Then, we create a line of dashes:
/// @code
/// const char * const line = "------------------------------------"
///                           "------------------------------------\n";
/// @endcode
/// Now, we call the static function `PrintAdapterUtil::makeAdapter` on the
/// `IndexSpan` objects to stream which will return streamable `PrintAdapter`
/// objects:
/// @code
/// cout << "    a: " << line << Util::makeAdapter(a, 2, 2)
///      << "    b: " << line << Util::makeAdapter(b, 3, 2)
///      << "    c: " << line << Util::makeAdapter(c, 4, 2);
/// @endcode
/// Finally, we see the output:
/// @code
///  a: ------------------------------------------------------------------------
///  [
///    position = 3
///    length = 7
///  ]
///  b: ------------------------------------------------------------------------
///    [
///      position = 241
///      length = 22
///    ]
///  c: ------------------------------------------------------------------------
///      [
///        position = 23
///        length = 17
///      ]
/// @endcode
///
/// ### Example 3: Use in C++17 With CTAD {#bdlb_printadapter-example-3-use-in-c-17-with-ctad}
///
///
/// Suppose you have a few `bdlb::IdentSpan` objects that you want to print,
/// only you want to stream them with `operator<<` and you want to specify
/// non-default values of `level` and `spacesPerLevel` to their streaming.
/// @code
/// const bdlb::IndexSpan a(3, 7), b(241, 22), c(23, 17);
/// @endcode
/// First, we create a line of dashes:
/// @code
/// const char * const line = "------------------------------------"
///                           "------------------------------------\n";
/// @endcode
/// Now, you call the constructor `PrintAdapter` on the `IndexSpan` objects to
/// stream and CTAD will create the right template specification:
/// @code
/// cout << "    a: " << line << bdlb::PrintAdapter(&a, 2, 2)
///      << "    b: " << line << bdlb::PrintAdapter(&b, 3, 2)
///      << "    c: " << line << bdlb::PrintAdapter(&c, 4, 2);
/// @endcode
/// Finally, we see the output:
/// @code
///  a: ------------------------------------------------------------------------
///  [
///    position = 3
///    length = 7
///  ]
///  b: ------------------------------------------------------------------------
///    [
///      position = 241
///      length = 22
///    ]
///  c: ------------------------------------------------------------------------
///      [
///        position = 23
///        length = 17
///      ]
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bdl
 * @{
 */
/** @addtogroup bdlb
 * @{
 */
/** @addtogroup bdlb_printadapter
 * @{
 */
 
#include <bdlscm_version.h>
 
#include <bdlb_printmethods.h>
 
#include <bsl_ostream.h>
 
 
namespace bdlb {
 
                              // ==================
                              // class PrintAdapter
                              // ==================
 
/// This `class` provides an object that may be streamed with `operator<<`
/// to give full control of the indentation format of the streaming.
///
/// See @ref bdlb_printadapter 
template <class TYPE>
class PrintAdapter {
 
    // DATA
    const TYPE *d_object_p;
    int         d_level;
    int         d_spacesPerLevel;
 
  public:
    // CREATORS
 
    // Create a print adapter object bound to the specified `object`, and
    // with the optionally specified `level` and `spacesPerLevel`
    // attributes, to be used when the `PrintAdapter` object is streamed.
    // Unless `level` is specified, a value of 0 is used, unless
    // `spacesPerLevel` is specified, a value of 4 is used.
    explicit
    PrintAdapter(const TYPE *object,
                 int         level          = 0,
                 int         spacesPerLevel = 4);
 
     PrintAdapter(const PrintAdapter&) = default;
 
    // MANIPULATORS
 
     PrintAdapter& operator=(const PrintAdapter&) = default;
 
    // ACCESSORS
 
    /// Return the `level` attribute.
    int level() const;
 
    /// Return a reference to the object referred to by this print adapter.
    const TYPE& object() const;
 
    /// Return the `spacesPerLevel` attribute.
    int spacesPerLevel() const;
};
 
                            // ======================
                            // class PrintAdapterUtil
                            // ======================
 
// This `struct` provides a namespace for a function template that
// facilitates the construction of a `PrintAdapter` without having to
// explicitly specify template arguments in C++03.  Note that in C++17 and
// later, CTAD may be used instead of this `struct` to call the
// `PrintAdapter` constructor without having to explicitly specify the
// template argument.
struct PrintAdapterUtil {
 
    // CLASS METHOD
 
    /// Create and return a `PrintAdapter` object, passing the constructor
    /// the specified `object`, `level`, and `spacesPerLevel`.
    template <class TYPE>
    static
    PrintAdapter<TYPE> makeAdapter(const TYPE& object,
                                   int         level          = 0,
                                   int         spacesPerLevel = 4);
};
 
// FREE OPERATORS
 
/// Write the value of the specified `object` to the specified output
/// `stream` and return a non-`const` reference to `stream`.  If `stream` is
/// not valid on entry, this operation has no effect.  Note that this
/// human-readable format is not fully specified and can change without
/// notice.
template <class TYPE>
bsl::ostream& operator<<(bsl::ostream&             stream,
                         const PrintAdapter<TYPE>& adapter);
 
// ============================================================================
//                         INLINE FUNCTION DEFINITIONS
// ============================================================================
 
                              // ------------
                              // PrintAdapter
                              // ------------
 
// CREATORS
template <class TYPE>
inline
PrintAdapter<TYPE>::PrintAdapter(const TYPE *object,
                                 int         level,
                                 int         spacesPerLevel)
: d_object_p(object)
, d_level(level)
, d_spacesPerLevel(spacesPerLevel)
{}
 
// ACCESSORS
template <class TYPE>
inline
int PrintAdapter<TYPE>::level() const
{
    return d_level;
}
 
template <class TYPE>
inline
const TYPE& PrintAdapter<TYPE>::object() const
{
    return *d_object_p;
}
 
template <class TYPE>
inline
int PrintAdapter<TYPE>::spacesPerLevel() const
{
    return d_spacesPerLevel;
}
 
// FREE OPERATORS
template <class TYPE>
inline
bsl::ostream& operator<<(bsl::ostream&             stream,
                         const PrintAdapter<TYPE>& adapter)
    // Format this object to the specified output 'stream' at the (absolute
    // value of) the optionally specified indentation 'level' and return a
    // reference to 'stream'.  If 'stream' is not valid on entry, this
    // operation has no effect.
{
    return bdlb::PrintMethods::print(stream,
                                     adapter.object(),
                                     adapter.level(),
                                     adapter.spacesPerLevel());
}
 
                            // ----------------
                            // PrintAdapterUtil
                            // ----------------
 
// CLASS METHOD
template <class TYPE>
inline
PrintAdapter<TYPE> PrintAdapterUtil::makeAdapter(const TYPE& object,
                                                 int         level,
                                                 int         spacesPerLevel)
{
    return PrintAdapter<TYPE>(&object, level, spacesPerLevel);
}
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2022 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */