include/boost/corosio/ip_address.hpp

100.0% Lines (45 / 45) 93.3% Branches (28 / 30) 100.0% Functions (16 / 16, 1 excl)

[ ] prev/next file n p prev/next uncovered line

ip_address.hpp

f(x) Functions (17)

Function Calls Lines Branches Blocks

Line	Branch	Hits	Source Code
1			//
2			// Copyright (c) 2026 Vinnie Falco ([email protected])
3			// Copyright (c) 2026 Steve Gerbino
4			// Copyright (c) 2026 Michael Vandeberg
5			//
6			// Distributed under the Boost Software License, Version 1.0. (See accompanying
7			// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
8			//
9			// Official repository: https://github.com/cppalliance/corosio
10			//
11
12			#ifndef BOOST_COROSIO_IP_ADDRESS_HPP
13			#define BOOST_COROSIO_IP_ADDRESS_HPP
14
15			#include <boost/corosio/detail/config.hpp>
16			#include <boost/corosio/detail/except.hpp>
17			#include <boost/corosio/family.hpp>
18			#include <boost/corosio/ipv4_address.hpp>
19			#include <boost/corosio/ipv6_address.hpp>
20
21			#include <boost/capy/results.hpp>
22
23			#include <compare>
24			#include <iosfwd>
25			#include <string>
26			#include <string_view>
27			#include <system_error>
28
29			namespace boost::corosio {
30
31			/** A version-independent IP address.
32
33			This class holds either an IPv4 or an IPv6 address. Code that works with
34			both families carries one value instead of branching between @ref
35			ipv4_address and @ref ipv6_address. Family-generic queries such as
36			@ref is_loopback dispatch to the held address, and @ref to_v4 /
37			@ref to_v6 recover the family-specific form.
38
39			A v4-mapped IPv6 address (`::ffff:a.b.c.d`) is an IPv6-family
40			value: it does not compare equal to the IPv4 address it maps.
41			To compare across the mapping, normalize both sides with
42			@ref to_v4 first.
43
44			@par Thread Safety
45			Distinct objects: Safe.@n
46			Shared objects: Safe.
47
48			@par Example
49			@code
50			auto [ec, addr] = make_ip_address("2001:db8::1");
51			if (ec)
52			return ec; // not a valid address string
53			if (addr.is_loopback())
54			{
55			// family-generic query, no branching
56			}
57			@endcode
58
59			@see
60			@ref ipv4_address,
61			@ref ipv6_address,
62			@ref make_ip_address
63			*/
64			class BOOST_COROSIO_DECL ip_address
65			{
66			ipv4_address v4_;
67			ipv6_address v6_;
68		493054x	corosio::family family_ = corosio::family::v4;
69
70			public:
71			/** The number of characters in the longest possible address string.
72			*/
73			static constexpr std::size_t max_str_len = ipv6_address::max_str_len;
74
75			/** Default constructor.
76
77			Constructs the IPv4 unspecified address (0.0.0.0).
78			*/
79		1324215x	ip_address() = default;
80
81			/** Copy constructor.
82			*/
83			ip_address(ip_address const&) = default;
84
85			/** Copy assignment.
86
87			@return A reference to this object.
88			*/
89			ip_address& operator=(ip_address const&) = default;
90
91			/** Construct from an IPv4 address.
92
93			@param addr The address to hold.
94			*/
95		154946x	ip_address(ipv4_address const& addr) noexcept : v4_(addr) {}
96
97			/** Construct from an IPv6 address.
98
99			@param addr The address to hold.
100			*/
101		458x	ip_address(ipv6_address const& addr) noexcept
102		229x	: v6_(addr)
103		229x	, family_(corosio::family::v6)
104		229x	{
105		458x	}
106
107			/** Return the address family.
108
109			The portable spelling of the family; @ref is_v4 and
110			@ref is_v6 are sugar over it.
111
112			@return The family of the held address.
113			*/
114		632x	corosio::family family() const noexcept
115			{
116		632x	return family_;
117			}
118
119			/** Check if the held address is IPv4.
120
121			@return `true` if the address is IPv4, `false` if IPv6.
122			*/
123		52382x	bool is_v4() const noexcept
124			{
125		52382x	return family_ == corosio::family::v4;
126			}
127
128			/** Check if the held address is IPv6.
129
130			@return `true` if the address is IPv6, `false` if IPv4.
131			*/
132		69x	bool is_v6() const noexcept
133			{
134		69x	return family_ == corosio::family::v6;
135			}
136
137			/** Check if the address is a loopback address.
138
139			@return `true` if the held address is a loopback
140			address of its family.
141			*/
142		14x	bool is_loopback() const noexcept
143			{
144	2/2 ✓ Branch 0 taken 4 times. ✓ Branch 1 taken 10 times.	14x	return is_v4() ? v4_.is_loopback() : v6_.is_loopback();
145			}
146
147			/** Check if the address is unspecified.
148
149			@return `true` if the held address is the unspecified
150			address of its family.
151			*/
152		6x	bool is_unspecified() const noexcept
153			{
154	2/2 ✓ Branch 0 taken 4 times. ✓ Branch 1 taken 2 times.	6x	return is_v4() ? v4_.is_unspecified() : v6_.is_unspecified();
155			}
156
157			/** Check if the address is a multicast address.
158
159			@return `true` if the held address is a multicast
160			address of its family.
161			*/
162		4x	bool is_multicast() const noexcept
163			{
164	2/2 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 2 times.	4x	return is_v4() ? v4_.is_multicast() : v6_.is_multicast();
165			}
166
167			/** Check if the address is a v4-mapped IPv6 address.
168
169			@return `true` if the address is IPv6 and is an
170			IPv4-Mapped IPv6 Address (`::ffff:a.b.c.d`).
171
172			@see
173			@ref to_v4
174			*/
175		3x	bool is_v4_mapped() const noexcept
176			{
177	2/2 ✓ Branch 0 taken 1 time. ✓ Branch 1 taken 2 times.	3x	return is_v6() && v6_.is_v4_mapped();
178			}
179
180			/** Convert to an IPv4 address.
181
182			Returns the held IPv4 address, or the IPv4 address that a
183			v4-mapped IPv6 address maps. This makes normalize-then-compare
184			a single call when matching addresses across the mapping.
185
186			@throws std::system_error `errc::address_family_not_supported`
187			if the address is IPv6 and not v4-mapped.
188
189			@return The IPv4 form of the address.
190
191			@see
192			@ref is_v4, @ref is_v4_mapped
193			*/
194		18530x	ipv4_address to_v4() const
195			{
196	2/2 ✓ Branch 0 taken 18526 times. ✓ Branch 1 taken 4 times.	18530x	return is_v4() ? v4_ : v6_.to_v4();
197			}
198
199			/** Convert to an IPv6 address.
200
201			To map an IPv4 address into IPv6, use the
202			`ipv6_address(ipv4_address const&)` constructor instead.
203
204			@throws std::system_error `errc::address_family_not_supported`
205			if the address is IPv4.
206
207			@return The held IPv6 address.
208
209			@see
210			@ref is_v6
211			*/
212		85x	ipv6_address to_v6() const
213			{
214	2/2 ✓ Branch 0 taken 83 times. ✓ Branch 1 taken 2 times.	85x	if (is_v4())
215		2x	detail::throw_system_error(
216		2x	std::make_error_code(std::errc::address_family_not_supported),
217			"address is not IPv6");
218		83x	return v6_;
219			}
220
221			/** Return the address as a string.
222
223			IPv4 addresses format in dotted decimal, IPv6 addresses
224			in standard notation without surrounding brackets.
225
226			@return The address as a string.
227			*/
228		13x	std::string to_string() const
229			{
230	2/2 ✓ Branch 0 taken 9 times. ✓ Branch 1 taken 4 times.	13x	return is_v4() ? v4_.to_string() : v6_.to_string();
231			}
232
233			/** Write a string representing the address to a buffer.
234
235			The resulting buffer is not null-terminated.
236
237			@throws std::length_error `dest_size < ip_address::max_str_len`
238
239			@param dest The buffer in which to write,
240			which must have at least `dest_size` space.
241
242			@param dest_size The size of the output buffer.
243
244			@return The formatted string view.
245			*/
246			std::string_view to_buffer(char* dest, std::size_t dest_size) const;
247
248			/** Return true if two addresses are equal.
249
250			Addresses are equal if they have the same family and the
251			same value. A v4-mapped IPv6 address is not equal to the
252			IPv4 address it maps; normalize with @ref ip_address::to_v4
253			to compare
254			across the mapping.
255
256			@return `true` if the addresses are equal.
257			*/
258		161x	friend bool operator==(ip_address const& a1, ip_address const& a2) noexcept
259			{
260	2/2 ✓ Branch 0 taken 9 times. ✓ Branch 1 taken 152 times.	161x	if (a1.family_ != a2.family_)
261		9x	return false;
262	2/2 ✓ Branch 0 taken 140 times. ✓ Branch 1 taken 12 times.	152x	return a1.is_v4() ? a1.v4_ == a2.v4_ : a1.v6_ == a2.v6_;
263		161x	}
264
265			/** Order two addresses.
266
267			Establishes a strict total ordering consistent with
268			@ref operator==: addresses are ordered first by family
269			(IPv4 before IPv6), then by value. This makes `ip_address`
270			usable as a key in ordered containers such as `std::map`
271			and `std::set`.
272
273			@return The relative order of `a1` and `a2`.
274			*/
275			friend std::strong_ordering
276		30x	operator<=>(ip_address const& a1, ip_address const& a2) noexcept
277			{
278	2/2 ✓ Branch 0 taken 8 times. ✓ Branch 1 taken 22 times.	30x	if (a1.family_ != a2.family_)
279	2/2 ✓ Branch 0 taken 5 times. ✓ Branch 1 taken 3 times.	8x	return a1.is_v4() ? std::strong_ordering::less
280			: std::strong_ordering::greater;
281	2/2 ✓ Branch 0 taken 15 times. ✓ Branch 1 taken 7 times.	22x	return a1.is_v4() ? a1.v4_ <=> a2.v4_ : a1.v6_ <=> a2.v6_;
282		30x	}
283
284			/** Format the address to an output stream.
285
286			@param os The output stream.
287			@param addr The address to format.
288			@return The output stream.
289			*/
290			friend BOOST_COROSIO_DECL std::ostream&
291			operator<<(std::ostream& os, ip_address const& addr);
292			};
293
294			/** Create an IP address from a string.
295
296			This function parses `s` as an IPv4 address in dotted decimal form, or
297			an IPv6 address in hexadecimal notation. An IPv6 address may carry a
298			`%zone` suffix: a decimal interface index, or an interface name where
299			the platform names interfaces. The string must contain the address
300			alone: port suffixes, surrounding brackets, and host names are not
301			accepted.
302
303			@par Exception Safety
304			Throws nothing.
305
306			@param s The string to parse.
307			@return The error code, empty on success, and the parsed
308			address — default-constructed on failure.
309			*/
310			[[nodiscard]] BOOST_COROSIO_DECL capy::results<ip_address>
311			make_ip_address(std::string_view s) noexcept;
312
313			} // namespace boost::corosio
314
315			namespace std {
316
317			/// Hash support for `boost::corosio::ip_address`.
318			template<>
319			struct hash<boost::corosio::ip_address>
320			{
321			/// Return the hash of `addr`.
322			std::size_t
323		17x	operator()(boost::corosio::ip_address const& addr) const noexcept
324			{
325			// Family-guarded dispatch keeps the throwing conversions
326			// unreachable
327	2/2 ✓ Branch 0 taken 9 times. ✓ Branch 1 taken 8 times.	34x	return addr.is_v4()
328	1/2 ✓ Branch 0 taken 9 times. ✗ Branch 1 not taken.	9x	? hash<boost::corosio::ipv4_address>()(addr.to_v4())
329	1/2 ✓ Branch 0 taken 8 times. ✗ Branch 1 not taken.	8x	: hash<boost::corosio::ipv6_address>()(addr.to_v6());
330			}
331			};
332
333			} // namespace std
334
335			#endif
336