Diff coverage report for

//

//

// Copyright (c) 2021 Vinnie Falco (vinnie dot falco at gmail dot com)

// Copyright (c) 2021 Vinnie Falco (vinnie dot falco at gmail dot 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_GRAMMAR_STRING_TOKEN_HPP

#ifndef BOOST_URL_GRAMMAR_STRING_TOKEN_HPP

#define BOOST_URL_GRAMMAR_STRING_TOKEN_HPP

#define BOOST_URL_GRAMMAR_STRING_TOKEN_HPP

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

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

#include <boost/core/detail/string_view.hpp>

#include <boost/core/detail/string_view.hpp>

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

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

#include <memory>

#include <memory>

#include <string>

#include <string>

namespace boost {

namespace boost {

namespace urls {

namespace urls {

namespace string_token {

namespace string_token {

/** Base class for string tokens, and algorithm parameters

/** Base class for string tokens, and algorithm parameters

    This abstract interface provides a means

    This abstract interface provides a means

    for an algorithm to generically obtain a

    for an algorithm to generically obtain a

    modifiable, contiguous character buffer

    modifiable, contiguous character buffer

    of prescribed size.

    of prescribed size.

    A @ref StringToken should be derived

    A @ref StringToken should be derived

    from this class. As the author of an

    from this class. As the author of an

    algorithm using a @ref StringToken,

    algorithm using a @ref StringToken,

    simply declare an rvalue reference

    simply declare an rvalue reference

    as a parameter type.

    as a parameter type.

    Instances of this type are intended only

    Instances of this type are intended only

    to be used once and then destroyed.

    to be used once and then destroyed.

    @par Example

    @par Example

    The declared function accepts any

    The declared function accepts any

    temporary instance of `arg` to be

    temporary instance of `arg` to be

    used for writing:

    used for writing:

    @code

    @code

    void algorithm( string_token::arg&& dest );

    void algorithm( string_token::arg&& dest );

    @endcode

    @endcode

    To implement the interface for your type

    To implement the interface for your type

    or use-case, derive from the class and

    or use-case, derive from the class and

    implement the prepare function.

    implement the prepare function.

*/

*/

struct arg

struct arg

{

{

    /** Return a modifiable character buffer

    /** Return a modifiable character buffer

        This function attempts to obtain a

        This function attempts to obtain a

        character buffer with space for at

        character buffer with space for at

        least `n` characters. Upon success,

        least `n` characters. Upon success,

        a pointer to the beginning of the

        a pointer to the beginning of the

        buffer is returned. Ownership is not

        buffer is returned. Ownership is not

        transferred; the caller should not

        transferred; the caller should not

        attempt to free the storage. The

        attempt to free the storage. The

        buffer shall remain valid until

        buffer shall remain valid until

        `this` is destroyed.

        `this` is destroyed.

        @note

        @note

        This function may only be called once.

        This function may only be called once.

        After invoking the function, the only

        After invoking the function, the only

        valid operation is destruction.

        valid operation is destruction.

        @param n The number of characters needed

        @param n The number of characters needed

        @return A pointer to the buffer

        @return A pointer to the buffer

    */

    */

    virtual char* prepare(std::size_t n) = 0;

    virtual char* prepare(std::size_t n) = 0;

    /// Virtual destructor

    /// Virtual destructor

    /// Default constructor

    /// Default constructor

    /// Default move constructor

    /// Default move constructor

    arg(arg&&) = default;

    arg(arg&&) = default;

    /// Deleted copy constructor

    /// Deleted copy constructor

    arg(arg const&) = delete;

    arg(arg const&) = delete;

    /// Deleted move assignment

    /// Deleted move assignment

    arg& operator=(arg&&) = delete;

    arg& operator=(arg&&) = delete;

    /// Deleted copy assignment

    /// Deleted copy assignment

    arg& operator=(arg const&) = delete;

    arg& operator=(arg const&) = delete;

};

};

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

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

namespace implementation_defined {

namespace implementation_defined {

template<class T, class = void>

template<class T, class = void>

struct is_token : std::false_type {};

struct is_token : std::false_type {};

template<class T>

template<class T>

struct is_token<T, void_t<

struct is_token<T, void_t<

    decltype(std::declval<T&>().prepare(

    decltype(std::declval<T&>().prepare(

        std::declval<std::size_t>())),

        std::declval<std::size_t>())),

    decltype(std::declval<T&>().result())

    decltype(std::declval<T&>().result())

    > > : std::integral_constant<bool,

    > > : std::integral_constant<bool,

        std::is_convertible<decltype(

        std::is_convertible<decltype(

            std::declval<T&>().result()),

            std::declval<T&>().result()),

            typename T::result_type>::value &&

            typename T::result_type>::value &&

        std::is_same<decltype(

        std::is_same<decltype(

            std::declval<T&>().prepare(0)),

            std::declval<T&>().prepare(0)),

            char*>::value &&

            char*>::value &&

        std::is_base_of<arg, T>::value &&

        std::is_base_of<arg, T>::value &&

        std::is_convertible<T const volatile*,

        std::is_convertible<T const volatile*,

            arg const volatile*>::value

            arg const volatile*>::value

    >

    >

{

{

};

};

} // implementation_defined

} // implementation_defined

/** Trait to determine if a type is a string token

/** Trait to determine if a type is a string token

    This trait returns `true` if `T` is a valid

    This trait returns `true` if `T` is a valid

    @ref StringToken type, and `false` otherwise.

    @ref StringToken type, and `false` otherwise.

    @par Example

    @par Example

    @code

    @code

    static_assert( string_token::is_token<T>::value );

    static_assert( string_token::is_token<T>::value );

    @endcode

    @endcode

 */

 */

template<class T>

template<class T>

using is_token = implementation_defined::is_token<T>;

using is_token = implementation_defined::is_token<T>;

#ifdef BOOST_URL_HAS_CONCEPTS

#ifdef BOOST_URL_HAS_CONCEPTS

/** Concept for a string token

/** Concept for a string token

    This concept is satisfied if `T` is a

    This concept is satisfied if `T` is a

    valid string token type.

    valid string token type.

    A string token is an rvalue passed to a function template

    A string token is an rvalue passed to a function template

    which customizes the return type of the function and also

    which customizes the return type of the function and also

    controls how a modifiable character buffer is obtained and presented.

    controls how a modifiable character buffer is obtained and presented.

    The string token's lifetime extends only for the duration of the

    The string token's lifetime extends only for the duration of the

    function call in which it appears as a parameter.

    function call in which it appears as a parameter.

    A string token cannot be copied, moved, or assigned, and must be

    A string token cannot be copied, moved, or assigned, and must be

    destroyed when the function returns or throws.

    destroyed when the function returns or throws.

    @par Semantics

    @par Semantics

    `T::result_type` determines the return type of functions

    `T::result_type` determines the return type of functions

    that accept a string token.

    that accept a string token.

    The `prepare()` function overrides the virtual function

    The `prepare()` function overrides the virtual function

    in the base class @ref arg. It must return a pointer to

    in the base class @ref arg. It must return a pointer to

    a character buffer of at least size `n`, otherwise

    a character buffer of at least size `n`, otherwise

    throw an exception. This function is called only

    throw an exception. This function is called only

    once or not at all.

    once or not at all.

    The `result()` function is invoked by the algorithm

    The `result()` function is invoked by the algorithm

    to receive the result from the string token.

    to receive the result from the string token.

    It is only invoked if `prepare()` returned

    It is only invoked if `prepare()` returned

    successfully and the string token was not destroyed.

    successfully and the string token was not destroyed.

    It is only called after `prepare()` returns

    It is only called after `prepare()` returns

    successfully, and the string token is destroyed

    successfully, and the string token is destroyed

    when the algorithm completes or if an exception

    when the algorithm completes or if an exception

    is thrown.

    is thrown.

    String tokens cannot be reused.

    String tokens cannot be reused.

    @par Exemplars

    @par Exemplars

    String token prototype:

    String token prototype:

    @code

    @code

    struct StringToken : string_token::arg

    struct StringToken : string_token::arg

    {

    {

        using result_type = std::string;

        using result_type = std::string;

        char* prepare( std::size_t n ) override;

        char* prepare( std::size_t n ) override;

        result_type result();

        result_type result();

    };

    };

    @endcode

    @endcode

    Algorithm prototype:

    Algorithm prototype:

    @code

    @code

    namespace detail {

    namespace detail {

    // Algorithm implementation may be placed

    // Algorithm implementation may be placed

    // out of line, and written as an ordinary

    // out of line, and written as an ordinary

    // function (no template required).

    // function (no template required).

    void algorithm_impl( string_token::arg& token )

    void algorithm_impl( string_token::arg& token )

    {

    {

        std::size_t n = 0;

        std::size_t n = 0;

        // calculate space needed in n

        // calculate space needed in n

        // ...

        // ...

        // acquire a destination buffer

        // acquire a destination buffer

        char* dest = token.prepare( n );

        char* dest = token.prepare( n );

        // write the characters to the buffer

        // write the characters to the buffer

    }

    }

    } // detail

    } // detail

    // public interface is a function template,

    // public interface is a function template,

    // defaulting to return std::string.

    // defaulting to return std::string.

    template< class StringToken = string_token::return_string >

    template< class StringToken = string_token::return_string >

    auto

    auto

    algorithm( StringToken&& token = {} ) ->

    algorithm( StringToken&& token = {} ) ->

        typename StringToken::result_type

        typename StringToken::result_type

    {

    {

        // invoke the algorithm with the token

        // invoke the algorithm with the token

        algorithm_impl( token );

        algorithm_impl( token );

        // return the result from the token

        // return the result from the token

        return token.result();

        return token.result();

    }

    }

    @endcode

    @endcode

    @par Models

    @par Models

    The following classes and functions implement and

    The following classes and functions implement and

    generate string tokens.

    generate string tokens.

    @li @ref return_string

    @li @ref return_string

    @li @ref assign_to

    @li @ref assign_to

    @li @ref preserve_size

    @li @ref preserve_size

 */

 */

template <class T>

template <class T>

concept StringToken =

concept StringToken =

    std::derived_from<T, string_token::arg> &&

    std::derived_from<T, string_token::arg> &&

    requires (T t, std::size_t n)

    requires (T t, std::size_t n)

{

{

    typename T::result_type;

    typename T::result_type;

    { t.prepare(n) } -> std::same_as<char*>;

    { t.prepare(n) } -> std::same_as<char*>;

    { t.result() } -> std::convertible_to<typename T::result_type>;

    { t.result() } -> std::convertible_to<typename T::result_type>;

};

};

#endif

#endif

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

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

namespace implementation_defined {

namespace implementation_defined {

struct return_string

struct return_string

    : arg

    : arg

{

{

    using result_type = std::string;

    using result_type = std::string;

    char*

    char*

    {

    {

    }

    }

    result_type

    result_type

    {

    {

    }

    }

private:

private:

    result_type s_;

    result_type s_;

};

};

} // implementation_defined

} // implementation_defined

/** A string token for returning a plain string

/** A string token for returning a plain string

    This @ref StringToken is used to customize

    This @ref StringToken is used to customize

    a function to return a plain string.

    a function to return a plain string.

    This is default token type used by

    This is default token type used by

    the methods of @ref url_view_base

    the methods of @ref url_view_base

    that return decoded strings.

    that return decoded strings.

 */

 */

using return_string = implementation_defined::return_string;

using return_string = implementation_defined::return_string;

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

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

namespace implementation_defined {

namespace implementation_defined {

template<class Alloc>

template<class Alloc>

struct append_to_t

struct append_to_t

    : arg

    : arg

{

{

    using string_type = std::basic_string<

    using string_type = std::basic_string<

        char, std::char_traits<char>,

        char, std::char_traits<char>,

            Alloc>;

            Alloc>;

    using result_type = string_type&;

    using result_type = string_type&;

    explicit

    explicit

        string_type& s) noexcept

        string_type& s) noexcept

    {

    {

    char*

    char*

    {

    {

    }

    }

    result_type

    result_type

    {

    {

    }

    }

private:

private:

    string_type& s_;

    string_type& s_;

};

};

} // implementation_defined

} // implementation_defined

/** Create a string token for appending to a plain string

/** Create a string token for appending to a plain string

    This function creates a @ref StringToken

    This function creates a @ref StringToken

    which appends to an existing plain string.

    which appends to an existing plain string.

    Functions using this token will append

    Functions using this token will append

    the result to the existing string and

    the result to the existing string and

    return a reference to it.

    return a reference to it.

    @param s The string to append

    @param s The string to append

    @return A string token

    @return A string token

 */

 */

template<

template<

    class Alloc =

    class Alloc =

        std::allocator<char>>

        std::allocator<char>>

implementation_defined::append_to_t<Alloc>

implementation_defined::append_to_t<Alloc>

    std::basic_string<

    std::basic_string<

        char,

        char,

        std::char_traits<char>,

        std::char_traits<char>,

        Alloc>& s)

        Alloc>& s)

{

{

}

}

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

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

namespace implementation_defined {

namespace implementation_defined {

template<class Alloc>

template<class Alloc>

struct assign_to_t

struct assign_to_t

    : arg

    : arg

{

{

    using string_type = std::basic_string<

    using string_type = std::basic_string<

        char, std::char_traits<char>,

        char, std::char_traits<char>,

            Alloc>;

            Alloc>;

    using result_type = string_type&;

    using result_type = string_type&;

    explicit

    explicit

        string_type& s) noexcept

        string_type& s) noexcept

    {

    {

    char*

    char*

    {

    {

    }

    }

    result_type

    result_type

    {

    {

    }

    }

private:

private:

    string_type& s_;

    string_type& s_;

};

};

} // implementation_defined

} // implementation_defined

/** Create a string token for assigning to a plain string

/** Create a string token for assigning to a plain string

    This function creates a @ref StringToken

    This function creates a @ref StringToken

    which assigns to an existing plain string.

    which assigns to an existing plain string.

    Functions using this token will assign

    Functions using this token will assign

    the result to the existing string and

    the result to the existing string and

    return a reference to it.

    return a reference to it.

    @param s The string to assign

    @param s The string to assign

    @return A string token

    @return A string token

 */

 */

template<

template<

    class Alloc =

    class Alloc =

        std::allocator<char>>

        std::allocator<char>>

implementation_defined::assign_to_t<Alloc>

implementation_defined::assign_to_t<Alloc>

    std::basic_string<

    std::basic_string<

        char,

        char,

        std::char_traits<char>,

        std::char_traits<char>,

        Alloc>& s)

        Alloc>& s)

{

{

}

}

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

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

namespace implementation_defined {

namespace implementation_defined {

template<class Alloc>

template<class Alloc>

struct preserve_size_t

struct preserve_size_t

    : arg

    : arg

{

{

    using result_type = core::string_view;

    using result_type = core::string_view;

    using string_type = std::basic_string<

    using string_type = std::basic_string<

        char, std::char_traits<char>,

        char, std::char_traits<char>,

            Alloc>;

            Alloc>;

    explicit

    explicit

        string_type& s) noexcept

        string_type& s) noexcept

    {

    {

    char*

    char*

    {

    {

        // preserve size() to

        // preserve size() to

        // avoid value-init

        // avoid value-init

    }

    }

    result_type

    result_type

    {

    {

    }

    }

private:

private:

    string_type& s_;

    string_type& s_;

    std::size_t n_ = 0;

    std::size_t n_ = 0;

};

};

} // implementation_defined

} // implementation_defined

/** Create a string token for a durable core::string_view

/** Create a string token for a durable core::string_view

    This function creates a @ref StringToken

    This function creates a @ref StringToken

    which assigns to an existing plain string.

    which assigns to an existing plain string.

    Functions using this token will assign

    Functions using this token will assign

    the result to the existing string and

    the result to the existing string and

    return a `core::string_view` to it.

    return a `core::string_view` to it.

    @param s The string to preserve

    @param s The string to preserve

    @return A string token

    @return A string token

 */

 */

template<

template<

    class Alloc =

    class Alloc =

        std::allocator<char>>

        std::allocator<char>>

implementation_defined::preserve_size_t<Alloc>

implementation_defined::preserve_size_t<Alloc>

    std::basic_string<

    std::basic_string<

        char,

        char,

        std::char_traits<char>,

        std::char_traits<char>,

        Alloc>& s)

        Alloc>& s)

{

{

}

}

} // string_token

} // string_token

namespace grammar {

namespace grammar {

namespace string_token = ::boost::urls::string_token;

namespace string_token = ::boost::urls::string_token;

} // grammar

} // grammar

} // urls

} // urls

} // boost

} // boost

#endif

#endif