Diff coverage report for

//

//

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

// Copyright (c) 2026 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/cppalliance/corosio

// Official repository: https://github.com/cppalliance/corosio

//

//

#ifndef BOOST_COROSIO_ENDPOINT_HPP

#ifndef BOOST_COROSIO_ENDPOINT_HPP

#define BOOST_COROSIO_ENDPOINT_HPP

#define BOOST_COROSIO_ENDPOINT_HPP

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

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

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

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

#include <boost/corosio/ipv4_address.hpp>

#include <boost/corosio/ipv4_address.hpp>

#include <boost/corosio/ipv6_address.hpp>

#include <boost/corosio/ipv6_address.hpp>

#include <cstdint>

#include <cstdint>

#include <string_view>

#include <string_view>

#include <system_error>

#include <system_error>

namespace boost::corosio {

namespace boost::corosio {

/** An IP endpoint (address + port) supporting both IPv4 and IPv6.

/** An IP endpoint (address + port) supporting both IPv4 and IPv6.

    This class represents an endpoint for IP communication,

    This class represents an endpoint for IP communication,

    consisting of either an IPv4 or IPv6 address and a port number.

    consisting of either an IPv4 or IPv6 address and a port number.

    Endpoints are used to specify connection targets and bind addresses.

    Endpoints are used to specify connection targets and bind addresses.

    The endpoint holds both address types as separate members (not a union),

    The endpoint holds both address types as separate members (not a union),

    with a discriminator to track which address type is active.

    with a discriminator to track which address type is active.

    @par Thread Safety

    @par Thread Safety

    Distinct objects: Safe.@n

    Distinct objects: Safe.@n

    Shared objects: Safe.

    Shared objects: Safe.

    @par Example

    @par Example

    @code

    @code

    // IPv4 endpoint

    // IPv4 endpoint

    endpoint ep4(ipv4_address::loopback(), 8080);

    endpoint ep4(ipv4_address::loopback(), 8080);

    // IPv6 endpoint

    // IPv6 endpoint

    endpoint ep6(ipv6_address::loopback(), 8080);

    endpoint ep6(ipv6_address::loopback(), 8080);

    // Port only (defaults to IPv4 any address)

    // Port only (defaults to IPv4 any address)

    endpoint bind_addr(8080);

    endpoint bind_addr(8080);

    // Parse from string

    // Parse from string

    endpoint ep;

    endpoint ep;

    if (auto ec = parse_endpoint("192.168.1.1:8080", ep); !ec) {

    if (auto ec = parse_endpoint("192.168.1.1:8080", ep); !ec) {

        // use ep

        // use ep

    }

    }

    @endcode

    @endcode

*/

*/

class endpoint

class endpoint

{

{

    ipv4_address v4_address_;

    ipv4_address v4_address_;

    ipv6_address v6_address_;

    ipv6_address v6_address_;

    std::uint16_t port_ = 0;

    std::uint16_t port_ = 0;

    bool is_v4_ = true;

    bool is_v4_ = true;

public:

public:

    /** Default constructor.

    /** Default constructor.

        Creates an endpoint with the IPv4 any address (0.0.0.0) and port 0.

        Creates an endpoint with the IPv4 any address (0.0.0.0) and port 0.

    */

    */

    {

    {

    /** Construct from IPv4 address and port.

    /** Construct from IPv4 address and port.

        @param addr The IPv4 address.

        @param addr The IPv4 address.

        @param p The port number in host byte order.

        @param p The port number in host byte order.

    */

    */

    {

    {

    /** Construct from IPv6 address and port.

    /** Construct from IPv6 address and port.

        @param addr The IPv6 address.

        @param addr The IPv6 address.

        @param p The port number in host byte order.

        @param p The port number in host byte order.

    */

    */

    {

    {

    /** Construct from port only.

    /** Construct from port only.

        Uses the IPv4 any address (0.0.0.0), which binds to all

        Uses the IPv4 any address (0.0.0.0), which binds to all

        available network interfaces.

        available network interfaces.

        @param p The port number in host byte order.

        @param p The port number in host byte order.

    */

    */

    {

    {

    /** Construct from an endpoint's address with a different port.

    /** Construct from an endpoint's address with a different port.

        Creates a new endpoint using the address from an existing

        Creates a new endpoint using the address from an existing

        endpoint but with a different port number.

        endpoint but with a different port number.

        @param ep The endpoint whose address to use.

        @param ep The endpoint whose address to use.

        @param p The port number in host byte order.

        @param p The port number in host byte order.

    */

    */

    {

    {

    /** Construct from a string.

    /** Construct from a string.

        Parses an endpoint string in one of the following formats:

        Parses an endpoint string in one of the following formats:

        @li IPv4 without port: `192.168.1.1`

        @li IPv4 without port: `192.168.1.1`

        @li IPv4 with port: `192.168.1.1:8080`

        @li IPv4 with port: `192.168.1.1:8080`

        @li IPv6 without port: `::1` or `2001:db8::1`

        @li IPv6 without port: `::1` or `2001:db8::1`

        @li IPv6 with port (bracketed): `[::1]:8080`

        @li IPv6 with port (bracketed): `[::1]:8080`

        @param s The string to parse.

        @param s The string to parse.

        @throws std::system_error on parse failure.

        @throws std::system_error on parse failure.

    */

    */

    explicit endpoint(std::string_view s);

    explicit endpoint(std::string_view s);

    /** Check if this endpoint uses an IPv4 address.

    /** Check if this endpoint uses an IPv4 address.

        @return `true` if the endpoint uses IPv4, `false` if IPv6.

        @return `true` if the endpoint uses IPv4, `false` if IPv6.

    */

    */

    {

    {

    }

    }

    /** Check if this endpoint uses an IPv6 address.

    /** Check if this endpoint uses an IPv6 address.

        @return `true` if the endpoint uses IPv6, `false` if IPv4.

        @return `true` if the endpoint uses IPv6, `false` if IPv4.

    */

    */

    {

    {

    }

    }

    /** Get the IPv4 address.

    /** Get the IPv4 address.

        @return The IPv4 address. The value is valid even if

        @return The IPv4 address. The value is valid even if

        the endpoint is using IPv6 (it will be the default any address).

        the endpoint is using IPv6 (it will be the default any address).

    */

    */

    {

    {

    }

    }

    /** Get the IPv6 address.

    /** Get the IPv6 address.

        @return The IPv6 address. The value is valid even if

        @return The IPv6 address. The value is valid even if

        the endpoint is using IPv4 (it will be the default any address).

        the endpoint is using IPv4 (it will be the default any address).

    */

    */

    {

    {

    }

    }

    /** Get the port number.

    /** Get the port number.

        @return The port number in host byte order.

        @return The port number in host byte order.

    */

    */

    {

    {

    }

    }

    /** Compare endpoints for equality.

    /** Compare endpoints for equality.

        Two endpoints are equal if they have the same address type,

        Two endpoints are equal if they have the same address type,

        the same address value, and the same port.

        the same address value, and the same port.

        @return `true` if both endpoints are equal.

        @return `true` if both endpoints are equal.

    */

    */

    {

    {

        else

        else

    }

    }

    /** Compare endpoints for inequality.

    /** Compare endpoints for inequality.

        @return `true` if endpoints differ.

        @return `true` if endpoints differ.

    */

    */

    friend bool operator!=(endpoint const& a, endpoint const& b) noexcept

    friend bool operator!=(endpoint const& a, endpoint const& b) noexcept

    {

    {

        return !(a == b);

        return !(a == b);

    }

    }

};

};

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

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

/** Endpoint format detection result.

/** Endpoint format detection result.

    Used internally by parse_endpoint to determine

    Used internally by parse_endpoint to determine

    the format of an endpoint string.

    the format of an endpoint string.

*/

*/

enum class endpoint_format

enum class endpoint_format

{

{

    ipv4_no_port,      ///< "192.168.1.1"

    ipv4_no_port,      ///< "192.168.1.1"

    ipv4_with_port,    ///< "192.168.1.1:8080"

    ipv4_with_port,    ///< "192.168.1.1:8080"

    ipv6_no_port,      ///< "::1" or "1:2:3:4:5:6:7:8"

    ipv6_no_port,      ///< "::1" or "1:2:3:4:5:6:7:8"

    ipv6_bracketed     ///< "[::1]" or "[::1]:8080"

    ipv6_bracketed     ///< "[::1]" or "[::1]:8080"

};

};

/** Detect the format of an endpoint string.

/** Detect the format of an endpoint string.

    This helper function determines the endpoint format

    This helper function determines the endpoint format

    based on simple rules:

    based on simple rules:

    1. Starts with `[` -> `ipv6_bracketed`

    1. Starts with `[` -> `ipv6_bracketed`

    2. Else count `:` characters:

    2. Else count `:` characters:

       - 0 colons -> `ipv4_no_port`

       - 0 colons -> `ipv4_no_port`

       - 1 colon -> `ipv4_with_port`

       - 1 colon -> `ipv4_with_port`

       - 2+ colons -> `ipv6_no_port`

       - 2+ colons -> `ipv6_no_port`

    @param s The string to analyze.

    @param s The string to analyze.

    @return The detected endpoint format.

    @return The detected endpoint format.

*/

*/

BOOST_COROSIO_DECL

BOOST_COROSIO_DECL

endpoint_format

endpoint_format

detect_endpoint_format(std::string_view s) noexcept;

detect_endpoint_format(std::string_view s) noexcept;

/** Parse an endpoint from a string.

/** Parse an endpoint from a string.

    This function parses an endpoint string in one of

    This function parses an endpoint string in one of

    the following formats:

    the following formats:

    @li IPv4 without port: `192.168.1.1`

    @li IPv4 without port: `192.168.1.1`

    @li IPv4 with port: `192.168.1.1:8080`

    @li IPv4 with port: `192.168.1.1:8080`

    @li IPv6 without port: `::1` or `2001:db8::1`

    @li IPv6 without port: `::1` or `2001:db8::1`

    @li IPv6 with port (bracketed): `[::1]:8080`

    @li IPv6 with port (bracketed): `[::1]:8080`

    @par Example

    @par Example

    @code

    @code

    endpoint ep;

    endpoint ep;

    if (auto ec = parse_endpoint("192.168.1.1:8080", ep); !ec) {

    if (auto ec = parse_endpoint("192.168.1.1:8080", ep); !ec) {

        // ep.is_v4() == true

        // ep.is_v4() == true

        // ep.port() == 8080

        // ep.port() == 8080

    }

    }

    if (auto ec = parse_endpoint("[::1]:443", ep); !ec) {

    if (auto ec = parse_endpoint("[::1]:443", ep); !ec) {

        // ep.is_v6() == true

        // ep.is_v6() == true

        // ep.port() == 443

        // ep.port() == 443

    }

    }

    @endcode

    @endcode

    @param s The string to parse.

    @param s The string to parse.

    @param ep The endpoint to store the result.

    @param ep The endpoint to store the result.

    @return An error code (empty on success).

    @return An error code (empty on success).

*/

*/

[[nodiscard]] BOOST_COROSIO_DECL

[[nodiscard]] BOOST_COROSIO_DECL

std::error_code

std::error_code

parse_endpoint(

parse_endpoint(

    std::string_view s,

    std::string_view s,

    endpoint& ep) noexcept;

    endpoint& ep) noexcept;

inline

inline

{

{

} // namespace boost::corosio

} // namespace boost::corosio

#endif

#endif