Index/include / boost / corosio / endpoint.hpp

include/boost/corosio/endpoint.hpp

100.0% Lines (66/66) 100.0% List of functions (13/13) 100.0% Branches (26/26)
[ ] prev/next file
endpoint.hpp
f(x) Functions (13)
Function Calls Lines Branches Blocks
boost::corosio::endpoint::endpoint() :56 75164x 100.0% – 100.0% boost::corosio::endpoint::endpoint(boost::corosio::ipv4_address, unsigned short) :69 11699x 100.0% – 100.0% boost::corosio::endpoint::endpoint(boost::corosio::ipv6_address, unsigned short) :82 106x 100.0% – 100.0% boost::corosio::endpoint::endpoint(unsigned short) :97 12x 100.0% – 100.0% boost::corosio::endpoint::endpoint(boost::corosio::endpoint const&, unsigned short) :113 2x 100.0% – 100.0% boost::corosio::endpoint::is_v4() const :141 5995x 100.0% – 100.0% boost::corosio::endpoint::is_v6() const :150 2058x 100.0% – 100.0% boost::corosio::endpoint::v4_address() const :160 3996x 100.0% – 100.0% boost::corosio::endpoint::v6_address() const :170 40x 100.0% – 100.0% boost::corosio::endpoint::port() const :179 5951x 100.0% – 100.0% boost::corosio::operator==(boost::corosio::endpoint const&, boost::corosio::endpoint const&) :191 2000x 100.0% 100.0% 100.0% boost::corosio::operator<=>(boost::corosio::endpoint const&, boost::corosio::endpoint const&) :215 25x 100.0% 100.0% 100.0% boost::corosio::endpoint::endpoint(std::basic_string_view<char, std::char_traits<char> >) :285 25x 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 std::uint16_t port_ = 0;
49 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 75164x endpoint() noexcept
57 75164x : v4_address_(ipv4_address::any())
58 75164x , v6_address_{}
59 75164x , port_(0)
60 75164x , is_v4_(true)
61 {
62 75164x }
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 11699x endpoint(ipv4_address addr, std::uint16_t p) noexcept
70 11699x : v4_address_(addr)
71 11699x , v6_address_{}
72 11699x , port_(p)
73 11699x , is_v4_(true)
74 {
75 11699x }
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 106x endpoint(ipv6_address addr, std::uint16_t p) noexcept
83 106x : v4_address_(ipv4_address::any())
84 106x , v6_address_(addr)
85 106x , port_(p)
86 106x , is_v4_(false)
87 {
88 106x }
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 12x explicit endpoint(std::uint16_t p) noexcept
98 12x : v4_address_(ipv4_address::any())
99 12x , v6_address_{}
100 12x , port_(p)
101 12x , is_v4_(true)
102 {
103 12x }
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 2x 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 {
119 2x }
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 5995x bool is_v4() const noexcept
142 {
143 5995x 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 2058x bool is_v6() const noexcept
151 {
152 2058x 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 3996x ipv4_address v4_address() const noexcept
161 {
162 3996x 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 40x ipv6_address v6_address() const noexcept
171 {
172 40x return v6_address_;
173 }
174
175 /** Get the port number.
176
177 @return The port number in host byte order.
178 */
179 5951x std::uint16_t port() const noexcept
180 {
181 5951x 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 2000x friend bool operator==(endpoint const& a, endpoint const& b) noexcept
192 {
193
2/2
✓ Branch 2 → 3 taken 1 time.
✓ Branch 2 → 4 taken 1999 times.
 2000x if (a.is_v4_ != b.is_v4_)
194 1x return false;
195
2/2
✓ Branch 4 → 5 taken 5 times.
✓ Branch 4 → 6 taken 1994 times.
 1999x if (a.port_ != b.port_)
196 5x return false;
197
2/2
✓ Branch 6 → 7 taken 1992 times.
✓ Branch 6 → 8 taken 2 times.
 1994x if (a.is_v4_)
198 1992x return a.v4_address_ == b.v4_address_;
199 else
200 2x return a.v6_address_ == b.v6_address_;
201 }
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 25x operator<=>(endpoint const& a, endpoint const& b) noexcept
216 {
217
2/2
✓ Branch 2 → 3 taken 9 times.
✓ Branch 2 → 7 taken 16 times.
 25x if (a.is_v4_ != b.is_v4_)
218
2/2
✓ Branch 3 → 4 taken 6 times.
✓ Branch 3 → 5 taken 3 times.
 9x return a.is_v4_ ? std::strong_ordering::less
219 9x : std::strong_ordering::greater;
220
2/2
✓ Branch 7 → 8 taken 13 times.
✓ Branch 7 → 19 taken 3 times.
 16x if (a.is_v4_)
221 {
222
4/4
✓ Branch 10 → 11 taken 2 times.
✓ Branch 10 → 14 taken 11 times.
✓ Branch 11 → 12 taken 1 time.
✓ Branch 11 → 13 taken 1 time.
 13x if (auto c = a.v4_address_.to_uint() <=> b.v4_address_.to_uint();
223
2/2
✓ Branch 16 → 17 taken 2 times.
✓ Branch 16 → 18 taken 11 times.
 13x c != 0)
224 2x return c;
225 }
226 else
227 {
228 3x if (auto c = a.v6_address_.to_bytes() <=> b.v6_address_.to_bytes();
229
2/2
✓ Branch 23 → 24 taken 1 time.
✓ Branch 23 → 25 taken 2 times.
 3x c != 0)
230 1x return c;
231 }
232
4/4
✓ Branch 26 → 27 taken 6 times.
✓ Branch 26 → 30 taken 7 times.
✓ Branch 27 → 28 taken 4 times.
✓ Branch 27 → 29 taken 2 times.
 13x return a.port_ <=> b.port_;
233 }
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 25x inline endpoint::endpoint(std::string_view s)
286 {
287 25x auto [ec, ep] = make_endpoint(s);
288
2/2
✓ Branch 8 → 9 taken 16 times.
✓ Branch 8 → 10 taken 9 times.
 25x if (ec)
289 16x detail::throw_system_error(ec);
290 9x *this = ep;
291 9x }
292
293 } // namespace boost::corosio
294
295 #endif
296