Diff coverage report for

//

//

// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)

// Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// 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)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/boostorg/url

// Official repository: https://github.com/boostorg/url

//

//

#ifndef BOOST_URL_SEGMENTS_ENCODED_BASE_HPP

#ifndef BOOST_URL_SEGMENTS_ENCODED_BASE_HPP

#define BOOST_URL_SEGMENTS_ENCODED_BASE_HPP

#define BOOST_URL_SEGMENTS_ENCODED_BASE_HPP

#include <boost/url/detail/config.hpp>

#include <boost/url/detail/config.hpp>

#include <boost/url/ignore_case.hpp>

#include <boost/url/ignore_case.hpp>

#include <boost/url/pct_string_view.hpp>

#include <boost/url/pct_string_view.hpp>

#include <boost/url/detail/url_impl.hpp>

#include <boost/url/detail/url_impl.hpp>

#include <iosfwd>

#include <iosfwd>

namespace boost {

namespace boost {

namespace urls {

namespace urls {

/** Percent-encoded path segment helper base

/** Percent-encoded path segment helper base

    Implements the shared encoded-segment

    Implements the shared encoded-segment

    algorithms reused by @ref segments_encoded_view

    algorithms reused by @ref segments_encoded_view

    and @ref segments_encoded_ref. It is not

    and @ref segments_encoded_ref. It is not

    intended to be instantiated directly; use

    intended to be instantiated directly; use

    one of those concrete containers instead.

    one of those concrete containers instead.

    @par Containers

    @par Containers

    @li @ref segments_ref

    @li @ref segments_ref

    @li @ref segments_view

    @li @ref segments_view

    @li @ref segments_encoded_ref

    @li @ref segments_encoded_ref

    @li @ref segments_encoded_view

    @li @ref segments_encoded_view

*/

*/

class BOOST_SYMBOL_VISIBLE segments_encoded_base

class BOOST_SYMBOL_VISIBLE segments_encoded_base

{

{

    detail::path_ref ref_;

    detail::path_ref ref_;

    friend class url_view_base;

    friend class url_view_base;

    friend class segments_encoded_ref;

    friend class segments_encoded_ref;

    friend class segments_encoded_view;

    friend class segments_encoded_view;

    segments_encoded_base(

    segments_encoded_base(

        detail::path_ref const& ref) noexcept;

        detail::path_ref const& ref) noexcept;

    segments_encoded_base(

    segments_encoded_base(

        segments_encoded_base const&) = default;

        segments_encoded_base const&) = default;

    segments_encoded_base& operator=(

    segments_encoded_base& operator=(

        segments_encoded_base const&) = default;

        segments_encoded_base const&) = default;

public:

public:

    /** A Bidirectional iterator to a path segment

    /** A Bidirectional iterator to a path segment

        Objects of this type allow iteration

        Objects of this type allow iteration

        through the segments in the path.

        through the segments in the path.

        Strings returned by iterators may

        Strings returned by iterators may

        contain percent escapes.

        contain percent escapes.

        The values returned are read-only;

        The values returned are read-only;

        changes to segments must be made

        changes to segments must be made

        through the container instead, if the

        through the container instead, if the

        container supports modification.

        container supports modification.

        <br>

        <br>

        The strings produced when iterators

        The strings produced when iterators

        are dereferenced refer to the underlying

        are dereferenced refer to the underlying

        character buffer.

        character buffer.

        Ownership is not transferred; the caller

        Ownership is not transferred; the caller

        is responsible for ensuring that the

        is responsible for ensuring that the

        lifetime of the buffer extends until

        lifetime of the buffer extends until

        it is no longer referenced by any

        it is no longer referenced by any

        container or iterator.

        container or iterator.

    */

    */

    class iterator;

    class iterator;

    /// @copydoc iterator

    /// @copydoc iterator

    using const_iterator = iterator;

    using const_iterator = iterator;

    /** The value type

    /** The value type

        Values of this type represent a segment

        Values of this type represent a segment

        where unique ownership is retained by

        where unique ownership is retained by

        making a copy.

        making a copy.

        @par Example

        @par Example

        @code

        @code

        segments_encoded_base::value_type ps( url_view( "/path/to/file.txt" ).encoded_segments().back() );

        segments_encoded_base::value_type ps( url_view( "/path/to/file.txt" ).encoded_segments().back() );

        @endcode

        @endcode

    */

    */

    using value_type = std::string;

    using value_type = std::string;

    /** The reference type

    /** The reference type

        This is the type of value returned when

        This is the type of value returned when

        iterators of the view are dereferenced.

        iterators of the view are dereferenced.

    */

    */

    using reference = pct_string_view;

    using reference = pct_string_view;

    /// @copydoc reference

    /// @copydoc reference

    using const_reference = pct_string_view;

    using const_reference = pct_string_view;

    /** An unsigned integer type used to represent size.

    /** An unsigned integer type used to represent size.

    */

    */

    using size_type = std::size_t;

    using size_type = std::size_t;

    /** A signed integer type used to represent differences.

    /** A signed integer type used to represent differences.

    */

    */

    using difference_type = std::ptrdiff_t;

    using difference_type = std::ptrdiff_t;

    //--------------------------------------------

    //--------------------------------------------

    //

    //

    // Observers

    // Observers

    //

    //

    //--------------------------------------------

    //--------------------------------------------

    /** Return the maximum number of characters possible

    /** Return the maximum number of characters possible

        This represents the largest number of

        This represents the largest number of

        characters that are possible in a path,

        characters that are possible in a path,

        not including any null terminator.

        not including any null terminator.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return The maximum number of characters possible.

        @return The maximum number of characters possible.

    */

    */

    static

    static

    constexpr

    constexpr

    std::size_t

    std::size_t

    max_size() noexcept

    max_size() noexcept

    {

    {

        return BOOST_URL_MAX_SIZE;

        return BOOST_URL_MAX_SIZE;

    }

    }

    /** Return the referenced character buffer.

    /** Return the referenced character buffer.

        This function returns the character

        This function returns the character

        buffer referenced by the view.

        buffer referenced by the view.

        The returned string may contain

        The returned string may contain

        percent escapes.

        percent escapes.

        @par Example

        @par Example

        @code

        @code

        assert( url_view( "/path/to/file.txt" ).encoded_segments().buffer() == "/path/to/file.txt" );

        assert( url_view( "/path/to/file.txt" ).encoded_segments().buffer() == "/path/to/file.txt" );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return A string view of the buffer.

        @return A string view of the buffer.

    */

    */

    pct_string_view

    pct_string_view

    buffer() const noexcept;

    buffer() const noexcept;

    /** Returns true if this references an absolute path.

    /** Returns true if this references an absolute path.

        Absolute paths always start with a

        Absolute paths always start with a

        forward slash ('/').

        forward slash ('/').

        @par Example

        @par Example

        @code

        @code

        assert( url_view( "/path/to/file.txt" ).encoded_segments().is_absolute() == true );

        assert( url_view( "/path/to/file.txt" ).encoded_segments().is_absolute() == true );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return `true` if the path is absolute, otherwise `false`.

        @return `true` if the path is absolute, otherwise `false`.

    */

    */

    bool

    bool

    is_absolute() const noexcept;

    is_absolute() const noexcept;

    /** Return true if there are no segments

    /** Return true if there are no segments

        @par Example

        @par Example

        @code

        @code

        assert( ! url_view( "/index.htm" ).encoded_segments().empty() );

        assert( ! url_view( "/index.htm" ).encoded_segments().empty() );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return `true` if there are no segments, otherwise `false`.

        @return `true` if there are no segments, otherwise `false`.

    */

    */

    bool

    bool

    empty() const noexcept;

    empty() const noexcept;

    /** Return the number of segments

    /** Return the number of segments

        @par Example

        @par Example

        @code

        @code

        assert( url_view( "/path/to/file.txt" ).encoded_segments().size() == 3 );

        assert( url_view( "/path/to/file.txt" ).encoded_segments().size() == 3 );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return The number of segments.

        @return The number of segments.

    */

    */

    std::size_t

    std::size_t

    size() const noexcept;

    size() const noexcept;

    /** Return the first segment

    /** Return the first segment

        This function returns a string with the

        This function returns a string with the

        first segment of the path without any

        first segment of the path without any

        leading or trailing '/' separators.

        leading or trailing '/' separators.

        The returned string may contain

        The returned string may contain

        percent escapes.

        percent escapes.

        @par Preconditions

        @par Preconditions

        @code

        @code

        this->empty() == false

        this->empty() == false

        @endcode

        @endcode

        @par Effects

        @par Effects

        @code

        @code

        return *begin();

        return *begin();

        @endcode

        @endcode

        @par Example

        @par Example

        @code

        @code

        assert( url_view( "/path/to/file.txt" ).encoded_segments().front() == "path" );

        assert( url_view( "/path/to/file.txt" ).encoded_segments().front() == "path" );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return The first segment.

        @return The first segment.

    */

    */

    pct_string_view

    pct_string_view

    front() const noexcept;

    front() const noexcept;

    /** Return the last segment

    /** Return the last segment

        This function returns a string with the

        This function returns a string with the

        last segment of the path without any

        last segment of the path without any

        leading or trailing '/' separators.

        leading or trailing '/' separators.

        The returned string may contain

        The returned string may contain

        percent escapes.

        percent escapes.

        @par Preconditions

        @par Preconditions

        @code

        @code

        this->empty() == false

        this->empty() == false

        @endcode

        @endcode

        @par Example

        @par Example

        @code

        @code

        assert( url_view( "/path/to/file.txt" ).encoded_segments().back() == "file.txt" );

        assert( url_view( "/path/to/file.txt" ).encoded_segments().back() == "file.txt" );

        @endcode

        @endcode

        @par Preconditions

        @par Preconditions

        @code

        @code

        this->empty() == false

        this->empty() == false

        @endcode

        @endcode

        @par Effects

        @par Effects

        @code

        @code

        return *--end();

        return *--end();

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return The last segment.

        @return The last segment.

    */

    */

    pct_string_view

    pct_string_view

    back() const noexcept;

    back() const noexcept;

    /** Return an iterator to the beginning

    /** Return an iterator to the beginning

        @par Complexity

        @par Complexity

        Linear in `this->front().size()` or

        Linear in `this->front().size()` or

        constant if `this->empty()`.

        constant if `this->empty()`.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return An iterator to the first segment.

        @return An iterator to the first segment.

    */

    */

    iterator

    iterator

    begin() const noexcept;

    begin() const noexcept;

    /** Return an iterator to the end

    /** Return an iterator to the end

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return An iterator to one past the last segment.

        @return An iterator to one past the last segment.

    */

    */

    iterator

    iterator

    end() const noexcept;

    end() const noexcept;

};

};

//------------------------------------------------

//------------------------------------------------

/** Format to an output stream

/** Format to an output stream

    Any percent-escapes are emitted as-is;

    Any percent-escapes are emitted as-is;

    no decoding is performed.

    no decoding is performed.

    @par Complexity

    @par Complexity

    Linear in `ps.buffer().size()`.

    Linear in `ps.buffer().size()`.

    @par Effects

    @par Effects

    @code

    @code

    return os << ps.buffer();

    return os << ps.buffer();

    @endcode

    @endcode

    @param os The output stream to write to.

    @param os The output stream to write to.

    @param ps The object to format.

    @param ps The object to format.

    @return A reference to the output stream.

    @return A reference to the output stream.

*/

*/

std::ostream&

std::ostream&

operator<<(

operator<<(

    std::ostream& os,

    std::ostream& os,

    segments_encoded_base const& ps);

    segments_encoded_base const& ps);

} // urls

} // urls

} // boost

} // boost

#include <boost/url/impl/segments_encoded_base.hpp>

#include <boost/url/impl/segments_encoded_base.hpp>

#endif

#endif