bdlb_indexspan.h

Go to the documentation of this file.

/// @file bdlb_indexspan.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bdlb_indexspan.h                                                   -*-C++-*-
#ifndef INCLUDED_BDLB_INDEXSPAN
#define INCLUDED_BDLB_INDEXSPAN
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bdlb_indexspan bdlb_indexspan
/// @brief  Provide a value-semantic attribute type for position and length.
/// @addtogroup bdl
/// @{
/// @addtogroup bdlb
/// @{
/// @addtogroup bdlb_indexspan
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bdlb_indexspan-purpose"> Purpose</a>
/// * <a href="#bdlb_indexspan-classes"> Classes </a>
/// * <a href="#bdlb_indexspan-description"> Description </a>
///   * <a href="#bdlb_indexspan-attributes"> Attributes </a>
///   * <a href="#bdlb_indexspan-usage"> Usage </a>
///     * <a href="#bdlb_indexspan-example-1-a-parsed-path"> Example 1: A Parsed Path </a>
///
/// # Purpose {#bdlb_indexspan-purpose}
/// Provide a value-semantic attribute type for position and length.
///
/// # Classes {#bdlb_indexspan-classes}
///
/// -  bdlb::IndexSpan: value-semantic attribute type to represent position/length
///
/// @see  bdlb_indexspanutil, bdlb_indexspanstringutil
///
/// # Description {#bdlb_indexspan-description}
/// This component provides a value-semantic, constrained
/// attribute type `IndexSpan` that stores a position and a length.  The
/// constraint is that the sum of the two attributes must be representable by
/// the type `bsl::size_t`.
///
/// ## Attributes {#bdlb_indexspan-attributes}
///
///
/// @code
/// Name                Type                  Default  Simple Constraints
/// ------------------  --------------------  -------  ------------------
/// position            IndexSpan::size_type  0        none
/// length              IndexSpan::size_type  0        none
/// @endcode
/// * `position`: this span starts at this position in a sequence.
/// * `length`: this span contains this many elements.
///
/// For example, an `IndexSpan` describing the middle name in the string
/// "James Tiberius Kirk" will have the position 6 (the `T` of "Tiberius" is the
/// 7th character of the string) and the length 8 ("Tiberius" is 8 characters
/// long).
///
/// Note that the sum of the two attributes must be representable by the
/// `bsl::size_t` type.
///
/// ## Usage {#bdlb_indexspan-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: A Parsed Path {#bdlb_indexspan-example-1-a-parsed-path}
///
///
/// Suppose that we work with file system paths and we frequently need the path,
/// the base name, the extension, and the filename, as well as the full path
/// itself.  Therefore we want to create a class that stores the full path and a
/// way to quickly access the individual parts.  (To keep things simple we will
/// make the example code work on POSIX-style paths so we do not need to deal
/// with the difference in path separators.)
///
/// If we try the naive solution -- storing a `bsl::string` of the full path and
/// `bslstl::StringRef` for path, basename and extension -- the class
/// `bslstl::StringRef` members will reference back into memory owned by the
/// object, and the result is the compiler-generated (and naively written) move
/// and copy operations will be broken.  In addition, explicitly implementing
/// move and copy operations is quite difficult and error prone.
///
/// The simplest (most readable) solution to the problem is to store a position
/// and a length for the path, basename, and extension (rather than a
/// `bslstl::StringRef`) because that representation is independent of the
/// location of the memory for the string.  `IndexSpan` provides such a
/// representation, and allow us to implement our class using a simple copy and
/// move operations (or in other contexts, compiler supplied operations).
///
/// First, we define the members and interface of the class.
/// @code
/// class ParsedPath {
///   private:
///     // DATA
///     bsl::string     d_full;  // The full path
///     bdlb::IndexSpan d_path;  // The path part if present, otherwise empty
///     bdlb::IndexSpan d_base;  // The base name if present, otherwise empty
///     bdlb::IndexSpan d_ext;   // The extension if present, otherwise empty
///
///   public:
///     // CREATERS
///
///     /// Create a new `ParsedPath` object by storing and parsing the
///     /// specified `full` path.  Use the optionally specified
///     /// `basicAllocator` to allocate memory.  If `basicAllocator` is 0,
///     /// use the currently installed default allocator.
///     explicit ParsedPath(const bslstl::StringRef&  full,
///                         bslma::Allocator         *basicAllocator = 0);
///
///     /// Create a new `ParsedPath` object that stores the same parsed
///     /// path as the specified `original`.  Use the optionally specified
///     /// `basicAllocator` to allocate memory.  Use the currently
///     /// installed default allocator if `basicAllocator` is zero.
///     ParsedPath(const ParsedPath& original,
///                bslma::Allocator *basicAllocator = 0);
///
///     // ACCESSORS
///
///     /// Return a const reference to the full path parsed by this object.
///     const bsl::string& full() const;
///
///     /// Return a string reference to the path part.  Note that it may be
///     /// an empty string reference.
///     bslstl::StringRef path() const;
///
///     /// Return a string reference to the base name part.  Note that it
///     /// may be an empty string reference.
///     bslstl::StringRef base() const;
///
///     /// Return a string reference to the extension part.  Note that it
///     /// may be an empty string reference.
///     bslstl::StringRef ext()  const;
/// };
/// @endcode
///  Next, to make the parsing code short and readable, we implement a helper
///  function to create `IndexSpan` objects from two positions.  (In practice we
///  would use the higher level utility function
///  `IndexSpanStringUtil::createFromPosition`.)
/// @code
/// /// Return an `IndexSpan` describing the specified `[startPos, endPos)`
/// /// positions.
/// bdlb::IndexSpan createFromPositions(bdlb::IndexSpan::size_type startPos,
///                                     bdlb::IndexSpan::size_type endPos)
/// {
///     return bdlb::IndexSpan(startPos, endPos - startPos);
/// }
/// @endcode
///  Then, we implement the parsing constructor using the `create` function.
/// @code
/// // CREATORS
/// ParsedPath::ParsedPath(const bslstl::StringRef&  full,
///                        bslma::Allocator         *basicAllocator)
/// : d_full(full, basicAllocator)
/// {
///     typedef bsl::string::size_type Size;
///
///     static const Size npos = bsl::string::npos;
///
///     const Size slashPos = d_full.rfind('/');
///     const Size dotPos   = d_full.rfind('.');
///
///     const bool dotIsPresent   = (dotPos   != npos);
///     const bool slashIsPresent = (slashPos != npos);
///
///     const bool dotIsInPath = slashIsPresent && (dotPos < slashPos);
///
///     const bool isDotFile = dotIsPresent &&
///                              dotPos == (slashIsPresent ? slashPos + 1 : 0);
///
///     const bool hasExtension = dotIsPresent && !dotIsInPath && !isDotFile;
///     const bool hasPath      = slashIsPresent;
///
///     if (hasPath) {
///         d_path = createFromPositions(0, slashPos + 1);
///     }
///
///     d_base = createFromPositions(slashPos + 1,
///                                  hasExtension ? dotPos : full.length());
///
///     if (hasExtension) {
///         d_ext = createFromPositions(dotPos + 1, full.length());
///     }
/// }
/// @endcode
/// Next, we implement the (now) simple copy constructor:
/// @code
/// ParsedPath::ParsedPath(const ParsedPath& original,
///                        bslma::Allocator *basicAllocator)
/// : d_full(original.d_full, basicAllocator)
/// , d_path(original.d_path)
/// , d_base(original.d_base)
/// , d_ext(original.d_ext)
/// {
/// }
/// @endcode
///  Then, to make the accessors simple (and readable), we implement a helper
///  function that creates a `StringRef` from a `StringRef` and an `IndexSpan`.
///  (In practice we would use the higher level utility function
///  `IndexSpanStringUtil::bind`.)
/// @code
/// /// Return a string reference to the substring of the specified `full`
/// /// string defined by the specified `part`.
/// bslstl::StringRef bindSpan(const bslstl::StringRef& full,
///                            const bdlb::IndexSpan&   part)
/// {
///     BSLS_ASSERT(part.position() <= full.length());
///     BSLS_ASSERT(part.position() + part.length() <= full.length());
///
///     return bslstl::StringRef(full.data() + part.position(), part.length());
/// }
/// @endcode
///  Next, we implement the accessors:
/// @code
/// // ACCESSORS
/// bslstl::StringRef ParsedPath::base() const
/// {
///     return bindSpan(d_full, d_base);
/// }
///
/// bslstl::StringRef ParsedPath::ext() const
/// {
///     return bindSpan(d_full, d_ext);
/// }
///
/// const bsl::string& ParsedPath::full() const
/// {
///     return d_full;
/// }
///
/// bslstl::StringRef ParsedPath::path() const
/// {
///     return bindSpan(d_full, d_path);
/// }
/// @endcode
/// Finally, we verify that the resulting class is copied properly.  We do that
/// by determining that the original and the copy object has equal but distinct
/// strings and that the (other) accessors return references into those strings.
/// @code
/// ParsedPath aPath("path/path/basename.extension");
/// ParsedPath theCopy(aPath);
///
/// assert(aPath.full()        == theCopy.full());
/// assert(aPath.full().data() != theCopy.full().data());
///
/// assert(aPath.path()        == theCopy.path());
/// assert(aPath.path().data() != theCopy.path().data());
/// assert(aPath.path().data() >= aPath.full().data());
/// assert(aPath.path().data() + aPath.path().length() <=
///                               aPath.full().data() + aPath.full().length());
///
/// assert(aPath.base()        == theCopy.base());
/// assert(aPath.base().data() != theCopy.base().data());
/// assert(aPath.base().data() >= aPath.full().data());
/// assert(aPath.base().data() + aPath.base().length() <=
///                               aPath.full().data() + aPath.full().length());
///
/// assert(aPath.ext()        == theCopy.ext());
/// assert(aPath.ext().data() != theCopy.ext().data());
/// assert(aPath.ext().data() >= aPath.full().data());
/// assert(aPath.ext().data() + aPath.ext().length() <=
///                               aPath.full().data() + aPath.full().length());
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bdl
 * @{
 */
/** @addtogroup bdlb
 * @{
 */
/** @addtogroup bdlb_indexspan
 * @{
 */
 
#include <bdlscm_version.h>
 
#include <bdlb_printmethods.h> // 'bdlb::HasPrintMethod'
 
#include <bslh_hash.h>
 
#include <bslmf_istriviallycopyable.h>
#include <bslmf_nestedtraitdeclaration.h>
 
#include <bsls_assert.h>
 
#include <bsl_cstddef.h>
#include <bsl_iosfwd.h>
#include <bsl_limits.h>
 
 
namespace bdlb {
 
                            // ===============
                            // class IndexSpan
                            // ===============
 
/// A constrained attribute type that represents a position and a length.
/// The constraint is that the sum of the position and length attributes
/// must be representable by the `bsl::size_t` type.
///
/// See @ref bdlb_indexspan 
class IndexSpan {
 
  public:
    // TYPES
 
    /// The type of the position and length attributes.
    typedef bsl::size_t size_type;
 
  private:
    // DATA
    size_type d_position;  // The spans starts at this position
    size_type d_length;    // The span has this length
 
  public:
    // TRAITS
    BSLMF_NESTED_TRAIT_DECLARATION(IndexSpan, bsl::is_trivially_copyable);
    BSLMF_NESTED_TRAIT_DECLARATION(IndexSpan, bdlb::HasPrintMethod);
 
    // CREATORS
 
    /// Create an `IndexSpan` object with position and length of 0.
    IndexSpan();
 
    /// Create an `IndexSpan` object with the specified `position` and `length`.  
    /// 
    /// \pre The behavior is undefined   unless
    /// `position <= bsl::numeric_limits<size_t>::max() - length`.
    IndexSpan(size_type position, size_type length);
 
    /// Create an index span having the value of the specified `original` index span.  
    /// 
    /// \note Note that   this trivial copy constructor is generated by
    /// the compiler.
     IndexSpan(const IndexSpan& original) = default;
 
    /// Destroy this index span object.  
    /// \note Note that  this trivial destructor
    /// is generated by the compiler.
     ~IndexSpan() = default;
 
    // MANIPULATORS
 
    /// Assign to this index span the value of the specified `rhs` index
    /// span, and return a reference providing modifiable access to this object.  
    /// 
    /// \note Note that   this trivial assignment operation is generated by
    /// the compiler.
     IndexSpan& operator=(const IndexSpan& rhs) = default;
 
    // ACCESSORS
 
    /// Return `true` if the length attribute is 0; and return `false`
    /// otherwise.
    bool isEmpty() const;
 
    /// Return the length attribute.
    size_type length() const;
 
    /// Return the position attribute.
    size_type position() const;
 
                                  // Aspects
 
    /// 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 `level` is specified, optionally specify
    /// `spacesPerLevel`, the number of spaces per indentation level for
    /// this and all of its nested objects.  If `level` is negative,
    /// suppress indentation of the first line.  If `spacesPerLevel` is
    /// negative, format the entire output on one line, suppressing all but
    /// the initial indentation (as governed by `level`).  If `stream` is
    /// not valid on entry, this operation has no effect.
    bsl::ostream& print(bsl::ostream& stream,
                        int           level          = 0,
                        int           spacesPerLevel = 4) const;
};
 
// FREE OPERATORS
 
/// Return `true` if the specified `lhs` and `rhs` index span objects have
/// the same value, and `false` otherwise.  Two index span objects have the
/// same value if their position and length attributes compare equal.
bool operator==(const IndexSpan& lhs, const IndexSpan& rhs);
 
/// Return `true` if the specified `lhs` and `rhs` index span objects do not
/// have the same value, and `false` otherwise.  Two index span objects do
/// not have the same value if either their position or length attributes
/// do not compare equal.
bool operator!=(const IndexSpan& lhs, const IndexSpan& rhs);
 
/// Write the value of the specified `object` to the specified output
/// `stream` in a single-line format, and return a reference to `stream`.
/// If `stream` is not valid on entry, this operation has no effect.  
/// 
/// \note Note that   this human-readable format is not fully specified, can change
/// without notice, and is logically equivalent to:
/// @code
/// print(stream, 0, -1);
/// @endcode
bsl::ostream& operator<<(bsl::ostream& stream, const IndexSpan& object);
 
/// Invoke the specified `hashAlgorithm` on the attributes of the specified
/// `object`.
template <class HASH_ALGORITHM>
void hashAppend(HASH_ALGORITHM& hashAlgorithm, const IndexSpan& object);
 
// ============================================================================
//                             INLINE DEFINITIONS
// ============================================================================
 
                            // ---------------
                            // class IndexSpan
                            // ---------------
 
// CREATORS
inline
IndexSpan::IndexSpan()
: d_position(0u)
, d_length(0u)
{
}
 
inline
IndexSpan::IndexSpan(size_type position, size_type length)
: d_position(position)
, d_length(length)
{
    BSLS_ASSERT(position <= bsl::numeric_limits<size_t>::max() - length);
}
 
// ACCESSORS
inline
bool IndexSpan::isEmpty() const
{
    return 0 == d_length;
}
 
inline
IndexSpan::size_type IndexSpan::length() const
{
    return d_length;
}
 
inline
IndexSpan::size_type IndexSpan::position() const
{
    return d_position;
}
 
}  // close package namespace
 
// FREE OPERATORS
inline
bool bdlb::operator==(const IndexSpan& lhs, const IndexSpan& rhs)
{
    return lhs.position() == rhs.position()
        && lhs.length()   == rhs.length();
}
 
inline
bool bdlb::operator!=(const IndexSpan& lhs, const IndexSpan& rhs)
{
    return !(lhs == rhs);
}
 
inline
bsl::ostream& bdlb::operator<<(bsl::ostream&    stream,
                               const IndexSpan& object)
{
    return object.print(stream, 0, -1);
}
 
template <class HASH_ALGORITHM>
inline
void bdlb::hashAppend(HASH_ALGORITHM& hashAlgorithm, const IndexSpan& object)
{
    const IndexSpan::size_type pos = object.position();
    const IndexSpan::size_type len = object.length();
 
    using bslh::hashAppend;
    hashAppend(hashAlgorithm, pos);
    hashAppend(hashAlgorithm, len);
}
 
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2018 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */