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_IPV6_ADDRESS_HPP

#ifndef BOOST_URL_IPV6_ADDRESS_HPP

#define BOOST_URL_IPV6_ADDRESS_HPP

#define BOOST_URL_IPV6_ADDRESS_HPP

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

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

#include <boost/url/error.hpp>

#include <boost/url/error.hpp>

#include <boost/url/error_types.hpp>

#include <boost/url/error_types.hpp>

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

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

#include <boost/url/grammar/string_token.hpp>

#include <boost/url/grammar/string_token.hpp>

#include <array>

#include <array>

#include <cstdint>

#include <cstdint>

#include <iosfwd>

#include <iosfwd>

namespace boost {

namespace boost {

namespace urls {

namespace urls {

class ipv4_address;

class ipv4_address;

/** An IP version 6 style address.

/** An IP version 6 style address.

    Objects of this type are used to construct,

    Objects of this type are used to construct,

    parse, and manipulate IP version 6 addresses.

    parse, and manipulate IP version 6 addresses.

    @par BNF

    @par BNF

    @code

    @code

    IPv6address =                            6( h16 ":" ) ls32

    IPv6address =                            6( h16 ":" ) ls32

                /                       "::" 5( h16 ":" ) ls32

                /                       "::" 5( h16 ":" ) ls32

                / [               h16 ] "::" 4( h16 ":" ) ls32

                / [               h16 ] "::" 4( h16 ":" ) ls32

                / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32

                / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32

                / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32

                / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32

                / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32

                / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32

                / [ *4( h16 ":" ) h16 ] "::"              ls32

                / [ *4( h16 ":" ) h16 ] "::"              ls32

                / [ *5( h16 ":" ) h16 ] "::"              h16

                / [ *5( h16 ":" ) h16 ] "::"              h16

                / [ *6( h16 ":" ) h16 ] "::"

                / [ *6( h16 ":" ) h16 ] "::"

    ls32        = ( h16 ":" h16 ) / IPv4address

    ls32        = ( h16 ":" h16 ) / IPv4address

                ; least-significant 32 bits of address

                ; least-significant 32 bits of address

    h16         = 1*4HEXDIG

    h16         = 1*4HEXDIG

                ; 16 bits of address represented in hexadecimal

                ; 16 bits of address represented in hexadecimal

    @endcode

    @endcode

    @par Specification

    @par Specification

    @li <a href="https://datatracker.ietf.org/doc/html/rfc4291"

    @li <a href="https://datatracker.ietf.org/doc/html/rfc4291"

        >IP Version 6 Addressing Architecture (rfc4291)</a>

        >IP Version 6 Addressing Architecture (rfc4291)</a>

    @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"

    @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"

        >3.2.2. Host (rfc3986)</a>

        >3.2.2. Host (rfc3986)</a>

    @see

    @see

        @ref ipv4_address,

        @ref ipv4_address,

        @ref parse_ipv6_address.

        @ref parse_ipv6_address.

*/

*/

class ipv6_address

class ipv6_address

{

{

public:

public:

    /** The number of characters in the longest possible IPv6 string.

    /** The number of characters in the longest possible IPv6 string.

        The longest IPv6 address is:

        The longest IPv6 address is:

        @code

        @code

        ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff

        ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff

        @endcode

        @endcode

        @see

        @see

            @ref to_buffer.

            @ref to_buffer.

    */

    */

    // ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff

    // ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff

    // ::ffff:255.255.255.255

    // ::ffff:255.255.255.255

    // 12345678901234567890123456789012345678901234567890

    // 12345678901234567890123456789012345678901234567890

    //          1         2         3        4

    //          1         2         3        4

    static

    static

    constexpr

    constexpr

    std::size_t max_str_len = 49;

    std::size_t max_str_len = 49;

    /** The type used to represent an address as an array of bytes.

    /** The type used to represent an address as an array of bytes.

        Octets are stored in network byte order.

        Octets are stored in network byte order.

    */

    */

    using bytes_type = std::array<

    using bytes_type = std::array<

        unsigned char, 16>;

        unsigned char, 16>;

    /** Constructor.

    /** Constructor.

        Default constructed objects represent

        Default constructed objects represent

        the unspecified address.

        the unspecified address.

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.2"

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.2"

            >2.5.2. The Unspecified Address</a>

            >2.5.2. The Unspecified Address</a>

        @see

        @see

            @ref is_unspecified

            @ref is_unspecified

    */

    */

    /** Constructor.

    /** Constructor.

    */

    */

    ipv6_address(

    ipv6_address(

        ipv6_address const&) = default;

        ipv6_address const&) = default;

    /** Copy Assignment

    /** Copy Assignment

        @return `*this`

        @return `*this`

    */

    */

    ipv6_address&

    ipv6_address&

    operator=(

    operator=(

        ipv6_address const&) = default;

        ipv6_address const&) = default;

    /** Construct from an array of bytes.

    /** Construct from an array of bytes.

        This function constructs an address

        This function constructs an address

        from the array in `bytes`, which is

        from the array in `bytes`, which is

        interpreted in big-endian.

        interpreted in big-endian.

        @param bytes The value to construct from.

        @param bytes The value to construct from.

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    ipv6_address(

    ipv6_address(

        bytes_type const& bytes) noexcept;

        bytes_type const& bytes) noexcept;

    /** Construct from an IPv4 address.

    /** Construct from an IPv4 address.

        This function constructs an IPv6 address

        This function constructs an IPv6 address

        from the IPv4 address `addr`. The resulting

        from the IPv4 address `addr`. The resulting

        address is an IPv4-Mapped IPv6 Address.

        address is an IPv4-Mapped IPv6 Address.

        @param addr The address to construct from.

        @param addr The address to construct from.

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2"

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2"

            >2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)</a>

            >2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)</a>

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    ipv6_address(

    ipv6_address(

        ipv4_address const& addr) noexcept;

        ipv4_address const& addr) noexcept;

    /** Construct from a string.

    /** Construct from a string.

        This function constructs an address from

        This function constructs an address from

        the string `s`, which must contain a valid

        the string `s`, which must contain a valid

        IPv6 address string or else an exception

        IPv6 address string or else an exception

        is thrown.

        is thrown.

        @note For a non-throwing parse function,

        @note For a non-throwing parse function,

        use @ref parse_ipv6_address.

        use @ref parse_ipv6_address.

        @par Exception Safety

        @par Exception Safety

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        The input failed to parse correctly.

        The input failed to parse correctly.

        @param s The string to parse.

        @param s The string to parse.

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"

            >3.2.2. Host (rfc3986)</a>

            >3.2.2. Host (rfc3986)</a>

        @see

        @see

            @ref parse_ipv6_address.

            @ref parse_ipv6_address.

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    ipv6_address(

    ipv6_address(

        core::string_view s);

        core::string_view s);

    /** Return the address as bytes, in network byte order

    /** Return the address as bytes, in network byte order

        @return The address as an array of bytes.

        @return The address as an array of bytes.

    */

    */

    bytes_type

    bytes_type

    {

    {

    }

    }

    /** Return the address as a string.

    /** Return the address as a string.

        The returned string does not

        The returned string does not

        contain surrounding square brackets.

        contain surrounding square brackets.

        When called with no arguments, the

        When called with no arguments, the

        return type is `std::string`.

        return type is `std::string`.

        Otherwise, the return type and style

        Otherwise, the return type and style

        of output is determined by which string

        of output is determined by which string

        token is passed.

        token is passed.

        @par Example

        @par Example

        @code

        @code

        ipv6_address::bytes_type b = {{

        ipv6_address::bytes_type b = {{

                0, 1, 0, 2, 0, 3, 0, 4,

                0, 1, 0, 2, 0, 3, 0, 4,

                0, 5, 0, 6, 0, 7, 0, 8 }};

                0, 5, 0, 6, 0, 7, 0, 8 }};

        ipv6_address a(b);

        ipv6_address a(b);

        assert(a.to_string() == "1:2:3:4:5:6:7:8");

        assert(a.to_string() == "1:2:3:4:5:6:7:8");

        assert( ipv4_address(0x01020304).to_string() == "1.2.3.4" );

        assert( ipv4_address(0x01020304).to_string() == "1.2.3.4" );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

        Calls to allocate may throw.

        Calls to allocate may throw.

        String tokens may throw exceptions.

        String tokens may throw exceptions.

        @return The return type of the string token.

        @return The return type of the string token.

        If the token parameter is omitted, then

        If the token parameter is omitted, then

        a new `std::string` is returned.

        a new `std::string` is returned.

        Otherwise, the function return type

        Otherwise, the function return type

        is the result type of the token.

        is the result type of the token.

        @param token An optional string token.

        @param token An optional string token.

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.2">

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.2">

            2.2. Text Representation of Addresses (rfc4291)</a>

            2.2. Text Representation of Addresses (rfc4291)</a>

    */

    */

    template<BOOST_URL_STRTOK_TPARAM>

    template<BOOST_URL_STRTOK_TPARAM>

    BOOST_URL_STRTOK_RETURN

    BOOST_URL_STRTOK_RETURN

        BOOST_URL_STRTOK_ARG(token)) const

        BOOST_URL_STRTOK_ARG(token)) const

    {

    {

    }

    }

    /** Write a dotted decimal string representing the address to a buffer

    /** Write a dotted decimal string representing the address to a buffer

        The resulting buffer is not null-terminated.

        The resulting buffer is not null-terminated.

        @throw std::length_error `dest_size < ipv6_address::max_str_len`

        @throw std::length_error `dest_size < ipv6_address::max_str_len`

        @return The formatted string

        @return The formatted string

        @param dest The buffer in which to write,

        @param dest The buffer in which to write,

        which must have at least `dest_size` space.

        which must have at least `dest_size` space.

        @param dest_size The size of the output buffer.

        @param dest_size The size of the output buffer.

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    core::string_view

    core::string_view

    to_buffer(

    to_buffer(

        char* dest,

        char* dest,

        std::size_t dest_size) const;

        std::size_t dest_size) const;

    /** Return true if the address is unspecified

    /** Return true if the address is unspecified

        The address 0:0:0:0:0:0:0:0 is called the

        The address 0:0:0:0:0:0:0:0 is called the

        unspecified address. It indicates the

        unspecified address. It indicates the

        absence of an address.

        absence of an address.

        @return `true` if the address is unspecified

        @return `true` if the address is unspecified

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.2">

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.2">

            2.5.2. The Unspecified Address (rfc4291)</a>

            2.5.2. The Unspecified Address (rfc4291)</a>

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    bool

    bool

    is_unspecified() const noexcept;

    is_unspecified() const noexcept;

    /** Return true if the address is a loopback address

    /** Return true if the address is a loopback address

        The unicast address 0:0:0:0:0:0:0:1 is called

        The unicast address 0:0:0:0:0:0:0:1 is called

        the loopback address. It may be used by a node

        the loopback address. It may be used by a node

        to send an IPv6 packet to itself.

        to send an IPv6 packet to itself.

        @return `true` if the address is a loopback address

        @return `true` if the address is a loopback address

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.3">

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.3">

            2.5.3. The Loopback Address (rfc4291)</a>

            2.5.3. The Loopback Address (rfc4291)</a>

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    bool

    bool

    is_loopback() const noexcept;

    is_loopback() const noexcept;

    /** Return true if the address is a mapped IPv4 address

    /** Return true if the address is a mapped IPv4 address

        This address type is used to represent the

        This address type is used to represent the

        addresses of IPv4 nodes as IPv6 addresses.

        addresses of IPv4 nodes as IPv6 addresses.

        @return `true` if the address is a mapped IPv4 address

        @return `true` if the address is a mapped IPv4 address

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2">

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2">

            2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)</a>

            2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)</a>

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    bool

    bool

    is_v4_mapped() const noexcept;

    is_v4_mapped() const noexcept;

    /** Return true if two addresses are equal

    /** Return true if two addresses are equal

        @param a1 The first address to compare.

        @param a1 The first address to compare.

        @param a2 The second address to compare.

        @param a2 The second address to compare.

        @return `true` if the addresses are equal

        @return `true` if the addresses are equal

    */

    */

    friend

    friend

    bool

    bool

        ipv6_address const& a1,

        ipv6_address const& a1,

        ipv6_address const& a2) noexcept

        ipv6_address const& a2) noexcept

    {

    {

    }

    }

    /** Return true if two addresses are not equal

    /** Return true if two addresses are not equal

        @param a1 The first address to compare.

        @param a1 The first address to compare.

        @param a2 The second address to compare.

        @param a2 The second address to compare.

        @return `true` if the addresses are not equal

        @return `true` if the addresses are not equal

    */

    */

    friend

    friend

    bool

    bool

        ipv6_address const& a1,

        ipv6_address const& a1,

        ipv6_address const& a2) noexcept

        ipv6_address const& a2) noexcept

    {

    {

    }

    }

    /** Return an address object that represents the loopback address

    /** Return an address object that represents the loopback address

        The unicast address 0:0:0:0:0:0:0:1 is called

        The unicast address 0:0:0:0:0:0:0:1 is called

        the loopback address. It may be used by a node

        the loopback address. It may be used by a node

        to send an IPv6 packet to itself.

        to send an IPv6 packet to itself.

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.3">

        @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.3">

            2.5.3. The Loopback Address (rfc4291)</a>

            2.5.3. The Loopback Address (rfc4291)</a>

        @return The loopback address.

        @return The loopback address.

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    static

    static

    ipv6_address

    ipv6_address

    loopback() noexcept;

    loopback() noexcept;

    /** Format the address to an output stream

    /** Format the address to an output stream

        This function writes the address to an

        This function writes the address to an

        output stream using standard notation.

        output stream using standard notation.

        @return The output stream, for chaining.

        @return The output stream, for chaining.

        @param os The output stream to write to.

        @param os The output stream to write to.

        @param addr The address to write.

        @param addr The address to write.

    */

    */

    friend

    friend

    std::ostream&

    std::ostream&

        std::ostream& os,

        std::ostream& os,

        ipv6_address const& addr)

        ipv6_address const& addr)

    {

    {

    }

    }

private:

private:

    BOOST_URL_DECL void write_ostream(std::ostream&) const;

    BOOST_URL_DECL void write_ostream(std::ostream&) const;

    BOOST_URL_DECL

    BOOST_URL_DECL

    std::size_t

    std::size_t

    print_impl(

    print_impl(

        char* dest) const noexcept;

        char* dest) const noexcept;

    BOOST_URL_DECL

    BOOST_URL_DECL

    void

    void

    to_string_impl(

    to_string_impl(

        string_token::arg& t) const;

        string_token::arg& t) const;

    bytes_type addr_{{}};

    bytes_type addr_{{}};

};

};

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

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

/** Parse a string containing an IPv6 address.

/** Parse a string containing an IPv6 address.

    This function attempts to parse the string

    This function attempts to parse the string

    as an IPv6 address and returns a result

    as an IPv6 address and returns a result

    containing the address upon success, or

    containing the address upon success, or

    an error code if the string does not contain

    an error code if the string does not contain

    a valid IPv6 address.

    a valid IPv6 address.

    @par Exception Safety

    @par Exception Safety

    Throws nothing.

    Throws nothing.

    @return A result containing the address.

    @return A result containing the address.

    @param s The string to parse.

    @param s The string to parse.

*/

*/

BOOST_URL_DECL

BOOST_URL_DECL

system::result<ipv6_address>

system::result<ipv6_address>

parse_ipv6_address(

parse_ipv6_address(

    core::string_view s) noexcept;

    core::string_view s) noexcept;

} // urls

} // urls

} // boost

} // boost

#endif

#endif