Index/include / boost / corosio / endpoint.hpp

include/boost/corosio/endpoint.hpp

100.0% Lines (76/76) 100.0% List of functions (13/14) 95.8% Branches (23/24)
[ ] prev/next file n p prev/next uncovered line
endpoint.hpp
f(x) Functions (14)
Function Calls Lines Branches Blocks
<unknown function 48> :48 – – – – boost::corosio::endpoint::endpoint() :56 431538x 100.0% – 100.0% boost::corosio::endpoint::endpoint(boost::corosio::ipv4_address, unsigned short) :69 45462x 100.0% – 100.0% boost::corosio::endpoint::endpoint(boost::corosio::ipv6_address, unsigned short) :82 322x 100.0% – 100.0% boost::corosio::endpoint::endpoint(unsigned short) :97 44x 100.0% – 100.0% boost::corosio::endpoint::endpoint(boost::corosio::endpoint const&, unsigned short) :113 4x 100.0% – 100.0% boost::corosio::endpoint::is_v4() const :141 15065x 100.0% – 100.0% boost::corosio::endpoint::is_v6() const :150 242x 100.0% – 100.0% boost::corosio::endpoint::v4_address() const :160 8294x 100.0% – 100.0% boost::corosio::endpoint::v6_address() const :170 65x 100.0% – 100.0% boost::corosio::endpoint::port() const :179 9944x 100.0% – 100.0% boost::corosio::operator==(boost::corosio::endpoint const&, boost::corosio::endpoint const&) :191 99x 100.0% 100.0% 100.0% boost::corosio::operator<=>(boost::corosio::endpoint const&, boost::corosio::endpoint const&) :215 22x 100.0% 93.8% 93.0% boost::corosio::endpoint::endpoint(std::__1::basic_string_view<char, std::__1::char_traits<char>>) :285 50x 100.0% 100.0% 100.0%
Line Branch TLA 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/ipv4_address.hpp>
17 #include <boost/corosio/ipv6_address.hpp>
18
19 #include <boost/capy/io_result.hpp>
20
21 #include <compare>
22 #include <cstdint>
23 #include <string_view>
24 #include <system_error>
25
26 namespace boost::corosio {
27
28 /** An IP endpoint (address + port) supporting both IPv4 and IPv6.
29
30 This class represents an endpoint for IP communication,
31 consisting of either an IPv4 or IPv6 address and a port number.
32 Endpoints are used to specify connection targets and bind addresses.
33
34 The endpoint holds both address types as separate members (not a union),
35 with a discriminator to track which address type is active.
36
37 @par Thread Safety
38 Distinct objects: Safe.@n
39 Shared objects: Safe.
40
41 @par Example
42 @par !example endpoint
43 */
44 class endpoint
45 {
46 ipv4_address v4_address_;
47 ipv6_address v6_address_;
48 25x std::uint16_t port_ = 0;
49 25x bool is_v4_ = true;
50
51 public:
52 /** Default constructor.
53
54 Creates an endpoint with the IPv4 any address (0.0.0.0) and port 0.
55 */
56 431538x endpoint() noexcept
57 215769x : v4_address_(ipv4_address::any())
58 215769x , v6_address_{}
59 215769x , port_(0)
60 215769x , is_v4_(true)
61 215769x {
62 431538x }
63
64 /** Construct from IPv4 address and port.
65
66 @param addr The IPv4 address.
67 @param p The port number in host byte order.
68 */
69 45462x endpoint(ipv4_address addr, std::uint16_t p) noexcept
70 22731x : v4_address_(addr)
71 22731x , v6_address_{}
72 22731x , port_(p)
73 22731x , is_v4_(true)
74 22731x {
75 45462x }
76
77 /** Construct from IPv6 address and port.
78
79 @param addr The IPv6 address.
80 @param p The port number in host byte order.
81 */
82 322x endpoint(ipv6_address addr, std::uint16_t p) noexcept
83 161x : v4_address_(ipv4_address::any())
84 161x , v6_address_(addr)
85 161x , port_(p)
86 161x , is_v4_(false)
87 161x {
88 322x }
89
90 /** Construct from port only.
91
92 Uses the IPv4 any address (0.0.0.0), which binds to all
93 available network interfaces.
94
95 @param p The port number in host byte order.
96 */
97 44x explicit endpoint(std::uint16_t p) noexcept
98 22x : v4_address_(ipv4_address::any())
99 22x , v6_address_{}
100 22x , port_(p)
101 22x , is_v4_(true)
102 22x {
103 44x }
104
105 /** Construct from an endpoint's address with a different port.
106
107 Creates a new endpoint using the address from an existing
108 endpoint but with a different port number.
109
110 @param ep The endpoint whose address to use.
111 @param p The port number in host byte order.
112 */
113 4x endpoint(endpoint const& ep, std::uint16_t p) noexcept
114 2x : v4_address_(ep.v4_address_)
115 2x , v6_address_(ep.v6_address_)
116 2x , port_(p)
117 2x , is_v4_(ep.is_v4_)
118 2x {
119 4x }
120
121 /** Construct from a string.
122
123 Parses an endpoint string in one of the following formats:
124 @li IPv4 without port: `192.168.1.1`
125 @li IPv4 with port: `192.168.1.1:8080`
126 @li IPv6 without port: `::1` or `2001:db8::1`
127 @li IPv6 with port (bracketed): `[::1]:8080`
128
129 @param s The string to parse.
130
131 @throws std::system_error on parse failure.
132
133 @see make_endpoint for the non-throwing form.
134 */
135 explicit endpoint(std::string_view s);
136
137 /** Check if this endpoint uses an IPv4 address.
138
139 @return `true` if the endpoint uses IPv4, `false` if IPv6.
140 */
141 15065x bool is_v4() const noexcept
142 {
143 15065x return is_v4_;
144 }
145
146 /** Check if this endpoint uses an IPv6 address.
147
148 @return `true` if the endpoint uses IPv6, `false` if IPv4.
149 */
150 242x bool is_v6() const noexcept
151 {
152 242x return !is_v4_;
153 }
154
155 /** Get the IPv4 address.
156
157 @return The IPv4 address. The value is valid even if
158 the endpoint is using IPv6 (it will be the default any address).
159 */
160 8294x ipv4_address v4_address() const noexcept
161 {
162 8294x return v4_address_;
163 }
164
165 /** Get the IPv6 address.
166
167 @return The IPv6 address. The value is valid even if
168 the endpoint is using IPv4 (it will be the default any address).
169 */
170 65x ipv6_address v6_address() const noexcept
171 {
172 65x return v6_address_;
173 }
174
175 /** Get the port number.
176
177 @return The port number in host byte order.
178 */
179 9944x std::uint16_t port() const noexcept
180 {
181 9944x return port_;
182 }
183
184 /** Compare endpoints for equality.
185
186 Two endpoints are equal if they have the same address type,
187 the same address value, and the same port.
188
189 @return `true` if both endpoints are equal.
190 */
191 99x friend bool operator==(endpoint const& a, endpoint const& b) noexcept
192 {
193
2/2
✓ Branch 0 taken 1 time.
✓ Branch 1 taken 98 times.
 99x if (a.is_v4_ != b.is_v4_)
194 1x return false;
195
2/2
✓ Branch 0 taken 3 times.
✓ Branch 1 taken 95 times.
 98x if (a.port_ != b.port_)
196 3x return false;
197
2/2
✓ Branch 0 taken 93 times.
✓ Branch 1 taken 2 times.
 95x if (a.is_v4_)
198 93x return a.v4_address_ == b.v4_address_;
199 else
200 2x return a.v6_address_ == b.v6_address_;
201 99x }
202
203 /** Order two endpoints.
204
205 Establishes a strict total ordering consistent with
206 @ref operator==: equal endpoints compare equivalent.
207 Endpoints are ordered first by address family (IPv4
208 before IPv6), then by address value, then by port. This
209 makes `endpoint` usable as a key in ordered containers
210 such as `std::map` and `std::set`.
211
212 @return The relative order of @p a and @p b.
213 */
214 friend std::strong_ordering
215 22x operator<=>(endpoint const& a, endpoint const& b) noexcept
216 {
217
2/2
✓ Branch 0 taken 6 times.
✓ Branch 1 taken 16 times.
 22x if (a.is_v4_ != b.is_v4_)
218
2/2
✓ Branch 0 taken 4 times.
✓ Branch 1 taken 2 times.
 6x return a.is_v4_ ? std::strong_ordering::less
219 : std::strong_ordering::greater;
220
2/2
✓ Branch 0 taken 13 times.
✓ Branch 1 taken 3 times.
 16x if (a.is_v4_)
221 {
222
4/4
✓ Branch 0 taken 2 times.
✓ Branch 1 taken 11 times.
✓ Branch 2 taken 2 times.
✓ Branch 3 taken 11 times.
 26x if (auto c = a.v4_address_.to_uint() <=> b.v4_address_.to_uint();
223 13x c != 0)
224 2x return c;
225 11x }
226 else
227 {
228
5/6
✓ Branch 0 taken 3 times.
✗ Branch 1 not taken.
✓ Branch 2 taken 1 time.
✓ Branch 3 taken 2 times.
✓ Branch 4 taken 1 time.
✓ Branch 5 taken 2 times.
 3x if (auto c = a.v6_address_.to_bytes() <=> b.v6_address_.to_bytes();
229 3x c != 0)
230 1x return c;
231 }
232 13x return a.port_ <=> b.port_;
233 22x }
234 };
235
236 /** Endpoint format detection result.
237
238 Used internally by make_endpoint to determine
239 the format of an endpoint string.
240 */
241 enum class endpoint_format
242 {
243 ipv4_no_port, ///< "192.168.1.1"
244 ipv4_with_port, ///< "192.168.1.1:8080"
245 ipv6_no_port, ///< "::1" or "1:2:3:4:5:6:7:8"
246 ipv6_bracketed ///< "[::1]" or "[::1]:8080"
247 };
248
249 /** Detect the format of an endpoint string.
250
251 This helper function determines the endpoint format
252 based on simple rules:
253 1. Starts with `[` -> `ipv6_bracketed`
254 2. Else count `:` characters:
255 - 0 colons -> `ipv4_no_port`
256 - 1 colon -> `ipv4_with_port`
257 - 2+ colons -> `ipv6_no_port`
258
259 @param s The string to analyze.
260 @return The detected endpoint format.
261 */
262 BOOST_COROSIO_DECL
263 endpoint_format detect_endpoint_format(std::string_view s) noexcept;
264
265 /** Create an endpoint from a string.
266
267 This function parses an endpoint string in one of
268 the following formats:
269
270 @li IPv4 without port: `192.168.1.1`
271 @li IPv4 with port: `192.168.1.1:8080`
272 @li IPv6 without port: `::1` or `2001:db8::1`
273 @li IPv6 with port (bracketed): `[::1]:8080`
274
275 @par Example
276 @par !example make_endpoint
277
278 @param s The string to parse.
279 @return The error code, empty on success, and the parsed
280 endpoint — default-constructed on failure.
281 */
282 [[nodiscard]] BOOST_COROSIO_DECL capy::io_result<endpoint>
283 make_endpoint(std::string_view s) noexcept;
284
285 50x inline endpoint::endpoint(std::string_view s)
286 25x {
287 25x auto [ec, ep] = make_endpoint(s);
288
2/2
✓ Branch 0 taken 9 times.
✓ Branch 1 taken 16 times.
 25x if (ec)
289 16x detail::throw_system_error(ec);
290 9x *this = ep;
291 34x }
292
293 } // namespace boost::corosio
294
295 #endif
296