Index/include / boost / corosio / endpoint.hpp

include/boost/corosio/endpoint.hpp

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