3rdparty/boost_1_81_0/boost/url/segments_base.hpp

//
// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
// Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
//
// Official repository: https://github.com/boostorg/url
//
#ifndef BOOST_URL_SEGMENTS_BASE_HPP
#define BOOST_URL_SEGMENTS_BASE_HPP
#include <boost/url/detail/config.hpp>
#include <boost/url/ignore_case.hpp>
#include <boost/url/detail/url_impl.hpp>
#include <iosfwd>
#include <string>
namespace boost {
namespace urls {
/** Common functionality for containers
    This base class is used by the library
    to provide common member functions for
    containers. This cannot be instantiated
    directly; Instead, use one of the
    containers or functions:
    @par Containers
    @li @ref segments_ref
    @li @ref segments_view
    @li @ref segments_encoded_ref
    @li @ref segments_encoded_view
*/
class segments_base
{
    detail::path_ref ref_;
    friend class url_view_base;
    friend class segments_ref;
    friend class segments_view;
    segments_base(
        detail::path_ref const& ref) noexcept;
    segments_base() = default;
    segments_base(
        segments_base const&) = default;
    segments_base& operator=(
        segments_base const&) = default;
public:
    /** A Bidirectional iterator to a path segment
        Objects of this type allow iteration
        through the segments in the path.
        Any percent-escapes in returned strings
        are decoded first.
        The values returned are read-only;
        changes to segments must be made
        through the container instead, if the
        container supports modification.
        <br>
        The strings produced when iterators are
        dereferenced belong to the iterator and
        become invalidated when that particular
        iterator is incremented, decremented,
        or destroyed.
    */
#ifdef BOOST_URL_DOCS
    using iterator = __see_below__;
#else
    class iterator;
#endif
    /// @copydoc iterator
    using const_iterator = iterator;
    /** The value type
        Values of this type represent a segment
        where unique ownership is retained by
        making a copy.
        @par Example
        @code
        segments_base::value_type ps( url_view( "/path/to/file.txt" ).segments().back() );
        @endcode
    */
    using value_type = std::string;
    /** The reference type
        This is the type of value returned when
        iterators of the view are dereferenced.
    */
    using reference = std::string;
    /// @copydoc reference
    using const_reference = std::string;
    /** An unsigned integer type used to represent size.
    */
    using size_type = std::size_t;
    /** A signed integer type used to represent differences.
    */
    using difference_type = std::ptrdiff_t;
    //--------------------------------------------
    //
    // Observers
    //
    //--------------------------------------------
    /** Return the maximum number of characters possible
        This represents the largest number of
        characters that are possible in a path,
        not including any null terminator.
        @par Exception Safety
        Throws nothing.
    */
    static
    constexpr
    std::size_t
    max_size() noexcept
    {
        return BOOST_URL_MAX_SIZE;
    }
    /** Return the referenced character buffer.
        This function returns the character
        buffer referenced by the view.
        The returned string may contain
        percent escapes.
        @par Example
        @code
        assert( url_view( "/path/to/file.txt" ).segments().buffer() == "/path/to/file.txt" );
        @endcode
        @par Complexity
        Constant.
        @par Exception Safety
        Throws nothing.
    */
    BOOST_URL_DECL
    pct_string_view
    buffer() const noexcept;
    /** Returns true if this references an absolute path.
        Absolute paths always start with a
        forward slash ('/').
        @par Example
        @code
        assert( url_view( "/path/to/file.txt" ).segments().is_absolute() == true );
        @endcode
        @par Complexity
        Constant.
        @par Exception Safety
        Throws nothing.
    */
    BOOST_URL_DECL
    bool
    is_absolute() const noexcept;
    /** Return true if there are no segments
        @par Example
        @code
        assert( ! url_view( "/index.htm" ).segments().empty() );
        @endcode
        @par Complexity
        Constant.
        @par Exception Safety
        Throws nothing.
    */
    BOOST_URL_DECL
    bool
    empty() const noexcept;
    /** Return the number of segments
    
        @par Example
        @code
        assert( url_view( "/path/to/file.txt" ).segments().size() == 3 );
        @endcode
        @par Complexity
        Constant.
        @par Exception Safety
        Throws nothing.
    */
    BOOST_URL_DECL
    std::size_t
    size() const noexcept;
    /** Return the first segment
        This function returns a string with the
        first segment of the path without any
        leading or trailing '/' separators.
        Any percent-escapes in the string are
        decoded first.
        @par Preconditions
        @code
        this->empty() == false
        @endcode
        @par Effects
        @code
        return *begin();
        @endcode
        @par Example
        @code
        assert( url_view( "/path/to/file.txt" ).segments().front() == "path" );
        @endcode
        @par Complexity
        Linear in `this->front().size()`.
        @par Exception Safety
        Calls to allocate may throw.
    */
    std::string
    front() const noexcept;
    /** Return the last segment
        @par Preconditions
        @code
        this->empty() == false
        @endcode
        @par Example
        @code
        assert( url_view( "/path/to/file.txt" ).segments().back() == "file.txt" );
        @endcode
        @par Preconditions
        @code
        this->empty() == false
        @endcode
        @par Effects
        @code
        return *--end();
        @endcode
        @par Complexity
        Linear in `this->back().size()`.
        @par Exception Safety
        Calls to allocate may throw.
    */
    std::string
    back() const noexcept;
    /** Return an iterator to the beginning
        @par Complexity
        Linear in `this->front().size()` or
        constant if `this->empty()`.
        @par Exception Safety
        Throws nothing.
    */
    BOOST_URL_DECL
    iterator
    begin() const noexcept;
    /** Return an iterator to the end
        @par Complexity
        Constant.
        @par Exception Safety
        Throws nothing.
    */
    BOOST_URL_DECL
    iterator
    end() const noexcept;
};
//------------------------------------------------
/** Format to an output stream
    Any percent-escapes are emitted as-is;
    no decoding is performed.
    @par Complexity
    Linear in `ps.buffer().size()`.
    @par Effects
    @code
    return os << ps.buffer();
    @endcode
*/
BOOST_URL_DECL
std::ostream&
operator<<(
    std::ostream& os,
    segments_base const& ps);
} // urls
} // boost
#include <boost/url/impl/segments_base.hpp>
#endif