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_IPV4_ADDRESS_HPP

#ifndef BOOST_URL_IPV4_ADDRESS_HPP

#define BOOST_URL_IPV4_ADDRESS_HPP

#define BOOST_URL_IPV4_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 <string>

#include <string>

#include <array>

#include <array>

#include <cstdint>

#include <cstdint>

#include <iosfwd>

#include <iosfwd>

namespace boost {

namespace boost {

namespace urls {

namespace urls {

/** An IP version 4 style address.

/** An IP version 4 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

    IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

    IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

    dec-octet   = DIGIT                 ; 0-9

    dec-octet   = DIGIT                 ; 0-9

                / %x31-39 DIGIT         ; 10-99

                / %x31-39 DIGIT         ; 10-99

                / "1" 2DIGIT            ; 100-199

                / "1" 2DIGIT            ; 100-199

                / "2" %x30-34 DIGIT     ; 200-249

                / "2" %x30-34 DIGIT     ; 200-249

                / "25" %x30-35          ; 250-255

                / "25" %x30-35          ; 250-255

    @endcode

    @endcode

    @par Specification

    @par Specification

    @li <a href="https://en.wikipedia.org/wiki/IPv4"

    @li <a href="https://en.wikipedia.org/wiki/IPv4"

        >IPv4 (Wikipedia)</a>

        >IPv4 (Wikipedia)</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 parse_ipv4_address,

        @ref parse_ipv4_address,

        @ref ipv6_address.

        @ref ipv6_address.

*/

*/

class ipv4_address

class ipv4_address

{

{

public:

public:

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

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

        The longest ipv4 address string is "255.255.255.255".

        The longest ipv4 address string is "255.255.255.255".

    */

    */

    static

    static

    constexpr

    constexpr

    std::size_t max_str_len = 15;

    std::size_t max_str_len = 15;

    /** The type used to represent an address as an unsigned integer

    /** The type used to represent an address as an unsigned integer

    */

    */

    using uint_type =

    using uint_type =

        std::uint_least32_t;

        std::uint_least32_t;

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

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

    */

    */

    using bytes_type =

    using bytes_type =

        std::array<unsigned char, 4>;

        std::array<unsigned char, 4>;

    /** Constructor.

    /** Constructor.

    */

    */

    /** Constructor.

    /** Constructor.

    */

    */

    ipv4_address(

    ipv4_address(

        ipv4_address const&) = default;

        ipv4_address const&) = default;

    /** Copy Assignment.

    /** Copy Assignment.

        @param other The object to copy.

        @param other The object to copy.

        @return A reference to this object.

        @return A reference to this object.

    */

    */

    ipv4_address&

    ipv4_address&

    operator=(

    operator=(

        ipv4_address const& other) = default;

        ipv4_address const& other) = default;

    //

    //

    //---

    //---

    //

    //

    /** Construct from an unsigned integer.

    /** Construct from an unsigned integer.

        This function constructs an address from

        This function constructs an address from

        the unsigned integer `u`, where the most

        the unsigned integer `u`, where the most

        significant byte forms the first octet

        significant byte forms the first octet

        of the resulting address.

        of the resulting address.

        @param u The integer to construct from.

        @param u The integer to construct from.

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    explicit

    explicit

    ipv4_address(

    ipv4_address(

        uint_type u) noexcept;

        uint_type u) noexcept;

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

    explicit

    explicit

    ipv4_address(

    ipv4_address(

        bytes_type const& bytes) noexcept;

        bytes_type const& bytes) 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

        IPv4 address string or else an exception

        IPv4 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_ipv4_address.

        use @ref parse_ipv4_address.

        @par Exception Safety

        @par Exception Safety

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error The input failed to parse correctly.

        @throw system_error 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_ipv4_address.

            @ref parse_ipv4_address.

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    explicit

    explicit

    ipv4_address(

    ipv4_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.

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    bytes_type

    bytes_type

    to_bytes() const noexcept;

    to_bytes() const noexcept;

    /** Return the address as an unsigned integer.

    /** Return the address as an unsigned integer.

        @return The address as an unsigned integer.

        @return The address as an unsigned integer.

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    uint_type

    uint_type

    to_uint() const noexcept;

    to_uint() const noexcept;

    /** Return the address as a string in dotted decimal format

    /** Return the address as a string in dotted decimal format

        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

        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

    {

    {

    }

    }

    /** 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 < ipv4_address::max_str_len`

        @throw std::length_error `dest_size < ipv4_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 a loopback address

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

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

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

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    bool

    bool

    is_loopback() const noexcept;

    is_loopback() const noexcept;

    /** Return true if the address is unspecified

    /** Return true if the address is unspecified

        @return `true` if the address is unspecified

        @return `true` if the address is unspecified

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    bool

    bool

    is_unspecified() const noexcept;

    is_unspecified() const noexcept;

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

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

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

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

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    bool

    bool

    is_multicast() const noexcept;

    is_multicast() 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, otherwise `false`.

        @return `true` if the addresses are equal, otherwise `false`.

    */

    */

    friend

    friend

    bool

    bool

        ipv4_address const& a1,

        ipv4_address const& a1,

        ipv4_address const& a2) noexcept

        ipv4_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, otherwise `false`.

        @return `true` if the addresses are not equal, otherwise `false`.

    */

    */

    friend

    friend

    bool

    bool

        ipv4_address const& a1,

        ipv4_address const& a1,

        ipv4_address const& a2) noexcept

        ipv4_address const& a2) noexcept

    {

    {

    }

    }

    /** Return an address object that represents any address

    /** Return an address object that represents any address

        @return The any address.

        @return The any address.

    */

    */

    static

    static

    ipv4_address

    ipv4_address

    {

    {

    }

    }

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

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

        @return The loopback address.

        @return The loopback address.

    */

    */

    static

    static

    ipv4_address

    ipv4_address

    {

    {

    }

    }

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

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

        @return The broadcast address.

        @return The broadcast address.

    */

    */

    static

    static

    ipv4_address

    ipv4_address

    {

    {

    }

    }

/** Format the address to an output stream.

/** Format the address to an output stream.

    IPv4 addresses written to output streams

    IPv4 addresses written to output streams

    are written in their dotted decimal format.

    are written in their dotted decimal format.

    @param os The output stream.

    @param os The output stream.

    @param addr The address to format.

    @param addr The address to format.

    @return The output stream.

    @return The output stream.

*/

*/

    friend

    friend

    std::ostream&

    std::ostream&

        std::ostream& os,

        std::ostream& os,

        ipv4_address const& addr)

        ipv4_address const& addr)

    {

    {

    }

    }

private:

private:

    friend class ipv6_address;

    friend class ipv6_address;

    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;

    uint_type addr_ = 0;

    uint_type addr_ = 0;

};

};

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

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

/** Return an IPv4 address from an IP address string in dotted decimal form

/** Return an IPv4 address from an IP address string in dotted decimal form

    @param s The string to parse.

    @param s The string to parse.

    @return The parsed address, or an error code.

    @return The parsed address, or an error code.

*/

*/

BOOST_URL_DECL

BOOST_URL_DECL

system::result<ipv4_address>

system::result<ipv4_address>

parse_ipv4_address(

parse_ipv4_address(

    core::string_view s) noexcept;

    core::string_view s) noexcept;

} // urls

} // urls

} // boost

} // boost

#endif

#endif