include/boost/corosio/endpoint.hpp

100.0% Lines (32/32) 100.0% List of functions (12/12) 100.0% Branches (12/12)

[ ] prev/next file

endpoint.hpp

f(x) Functions (12)

Function Calls Lines Branches Blocks

Line	Branch	Hits	Source Code
1			//
2			// Copyright (c) 2026 Vinnie Falco ([email protected])
3			// Copyright (c) 2026 Michael Vandeberg
4			//
5			// Distributed under the Boost Software License, Version 1.0. (See accompanying
6			// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7			//
8			// Official repository: https://github.com/cppalliance/corosio
9			//
10
11			#ifndef BOOST_COROSIO_ENDPOINT_HPP
12			#define BOOST_COROSIO_ENDPOINT_HPP
13
14			#include <boost/corosio/detail/config.hpp>
15			#include <boost/corosio/detail/except.hpp>
16			#include <boost/corosio/ip_address.hpp>
17
18			#include <boost/capy/io_result.hpp>
19
20			#include <compare>
21			#include <cstdint>
22			#include <string_view>
23			#include <system_error>
24
25			namespace boost::corosio {
26
27			/** Pairs an IP address with a port for either IPv4 or IPv6.
28
29			This class represents an endpoint for IP communication,
30			consisting of an IP address of either family and a port number.
31			Use an endpoint to specify a connection target or bind address.
32
33			@par Thread Safety
34			Distinct objects: Safe.@n
35			Shared objects: Safe.
36
37			@par Example
38			@par !example endpoint
39			*/
40			class endpoint
41			{
42			ip_address addr_;
43			std::uint16_t port_ = 0;
44
45			public:
46			/** Creates an endpoint with the IPv4 any address (0.0.0.0) and port 0.
47			*/
48		65911x	endpoint() noexcept = default;
49
50			/** Construct from an IP address and port.
51
52			`ipv4_address` and `ipv6_address` arguments convert
53			implicitly, so both families construct directly:
54			`endpoint(ipv4_address::loopback(), 80)`.
55
56			@param addr The IP address.
57			@param p The port number in host byte order.
58			*/
59		11190x	endpoint(ip_address addr, std::uint16_t p) noexcept : addr_(addr), port_(p)
60			{
61		11190x	}
62
63			/** Construct from port only.
64
65			Uses the IPv4 any address (0.0.0.0), which binds to all
66			available network interfaces.
67
68			@param p The port number in host byte order.
69			*/
70		12x	explicit endpoint(std::uint16_t p) noexcept : port_(p) {}
71
72			/** Construct from an endpoint's address with a different port.
73
74			Creates a new endpoint using the address from an existing
75			endpoint but with a different port number.
76
77			@param ep The endpoint whose address to use.
78			@param p The port number in host byte order.
79			*/
80		2x	endpoint(endpoint const& ep, std::uint16_t p) noexcept
81		2x	: addr_(ep.addr_)
82		2x	, port_(p)
83			{
84		2x	}
85
86			/** Construct from a string.
87
88			Parses an endpoint string in one of the following formats:
89			@li IPv4 without port: `192.168.1.1`
90			@li IPv4 with port: `192.168.1.1:8080`
91			@li IPv6 without port: `::1` or `2001:db8::1`
92			@li IPv6 with port (bracketed): `[::1]:8080`
93
94			@param s The string to parse.
95
96			@throws std::system_error on parse failure.
97
98			@see make_endpoint for the non-throwing form.
99			*/
100			explicit endpoint(std::string_view s);
101
102			/** Check if this endpoint uses an IPv4 address.
103
104			@return `true` if the endpoint uses IPv4, `false` if IPv6.
105			*/
106		5669x	bool is_v4() const noexcept
107			{
108		5669x	return addr_.is_v4();
109			}
110
111			/** Check if this endpoint uses an IPv6 address.
112
113			@return `true` if the endpoint uses IPv6, `false` if IPv4.
114			*/
115		41x	bool is_v6() const noexcept
116			{
117		41x	return addr_.is_v6();
118			}
119
120			/** Return the IP address.
121
122			@return The endpoint's address.
123			*/
124		5758x	ip_address address() const noexcept
125			{
126		5758x	return addr_;
127			}
128
129			/** Return the port number.
130
131			@return The port number in host byte order.
132			*/
133		5651x	std::uint16_t port() const noexcept
134			{
135		5651x	return port_;
136			}
137
138			/** Compare endpoints for equality.
139
140			Two endpoints are equal if they have the same address type,
141			the same address value, and the same port.
142
143			@return `true` if both endpoints are equal.
144			*/
145		1893x	friend bool operator==(endpoint const& a, endpoint const& b) noexcept
146			{
147	4/4 ✓ Branch 2 → 3 taken 1889 times. ✓ Branch 2 → 6 taken 4 times. ✓ Branch 4 → 5 taken 1885 times. ✓ Branch 4 → 6 taken 4 times.	1893x	return a.port_ == b.port_ && a.addr_ == b.addr_;
148			}
149
150			/** Order two endpoints.
151
152			Establishes a strict total ordering consistent with
153			@ref operator==: equal endpoints compare equivalent.
154			`operator<=>` orders endpoints first by address family
155			(IPv4 before IPv6), then by address value, then by port. This
156			makes `endpoint` usable as a key in ordered containers
157			such as `std::map` and `std::set`.
158
159			@return The relative order of @p a and @p b.
160			*/
161			friend std::strong_ordering
162		25x	operator<=>(endpoint const& a, endpoint const& b) noexcept
163			{
164	2/2 ✓ Branch 4 → 5 taken 12 times. ✓ Branch 4 → 6 taken 13 times.	25x	if (auto c = a.addr_ <=> b.addr_; c != 0)
165		12x	return c;
166	4/4 ✓ Branch 6 → 7 taken 6 times. ✓ Branch 6 → 10 taken 7 times. ✓ Branch 7 → 8 taken 4 times. ✓ Branch 7 → 9 taken 2 times.	13x	return a.port_ <=> b.port_;
167			}
168			};
169
170			/** Identifies which of the four supported endpoint string formats a string is in.
171
172			Used internally by `make_endpoint` to determine
173			the format of an endpoint string.
174			*/
175			enum class endpoint_format
176			{
177			ipv4_no_port, ///< "192.168.1.1"
178			ipv4_with_port, ///< "192.168.1.1:8080"
179			ipv6_no_port, ///< "::1" or "1:2:3:4:5:6:7:8"
180			ipv6_bracketed ///< "[::1]" or "[::1]:8080"
181			};
182
183			/** Detect the format of an endpoint string.
184
185			This helper function determines the endpoint format
186			based on simple rules:
187			1. Starts with `[` -> `ipv6_bracketed`
188			2. Else count `:` characters:
189			- 0 colons -> `ipv4_no_port`
190			- 1 colon -> `ipv4_with_port`
191			- 2+ colons -> `ipv6_no_port`
192
193			@param s The string to analyze.
194			@return The detected endpoint format.
195			*/
196			BOOST_COROSIO_DECL
197			endpoint_format detect_endpoint_format(std::string_view s) noexcept;
198
199			/** Create an endpoint from a string.
200
201			This function parses an endpoint string in one of
202			the following formats:
203
204			@li IPv4 without port: `192.168.1.1`
205			@li IPv4 with port: `192.168.1.1:8080`
206			@li IPv6 without port: `::1` or `2001:db8::1`
207			@li IPv6 with port (bracketed): `[::1]:8080`
208
209			@par Example
210			@par !example make_endpoint
211
212			@param s The string to parse.
213			@return The error code, empty on success, and the parsed
214			endpoint — default-constructed on failure.
215			*/
216			[[nodiscard]] BOOST_COROSIO_DECL capy::io_result<endpoint>
217			make_endpoint(std::string_view s) noexcept;
218
219		27x	inline endpoint::endpoint(std::string_view s)
220			{
221		27x	auto [ec, ep] = make_endpoint(s);
222	2/2 ✓ Branch 7 → 8 taken 16 times. ✓ Branch 7 → 9 taken 11 times.	27x	if (ec)
223		16x	detail::throw_system_error(ec);
224		11x	*this = ep;
225		11x	}
226
227			} // namespace boost::corosio
228
229			namespace std {
230
231			/// Hash support for `boost::corosio::endpoint`.
232			template<>
233			struct hash<boost::corosio::endpoint>
234			{
235			/// Return the hash of `ep`.
236		12x	std::size_t operator()(boost::corosio::endpoint const& ep) const noexcept
237			{
238		12x	std::size_t const h1 = hash<boost::corosio::ip_address>()(ep.address());
239		12x	std::size_t const h2 = hash<std::uint16_t>()(ep.port());
240		12x	return h1 ^ (h2 + 0x9e3779b9 + (h1 << 6) + (h1 >> 2));
241			}
242			};
243
244			} // namespace std
245
246			#endif
247