include/boost/corosio/ipv6_address.hpp

100.0% Lines (19 / 19) 90.0% Branches (9 / 10) 100.0% Functions (7 / 7)

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

ipv6_address.hpp

f(x) Functions (7)

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_IPV6_ADDRESS_HPP
12			#define BOOST_COROSIO_IPV6_ADDRESS_HPP
13
14			#include <boost/corosio/detail/config.hpp>
15			#include <boost/corosio/ipv4_address.hpp>
16
17			#include <boost/capy/results.hpp>
18
19			#include <array>
20			#include <compare>
21			#include <cstdint>
22			#include <functional>
23			#include <iosfwd>
24			#include <string>
25			#include <string_view>
26			#include <system_error>
27
28			namespace boost::corosio {
29
30			/** An IP version 6 style address.
31
32			Objects of this type are used to construct,
33			parse, and manipulate IP version 6 addresses.
34
35			@par BNF
36			@code
37			IPv6address = 6( h16 ":" ) ls32
38			/ "::" 5( h16 ":" ) ls32
39			/ [ h16 ] "::" 4( h16 ":" ) ls32
40			/ [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
41			/ [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
42			/ [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32
43			/ [ *4( h16 ":" ) h16 ] "::" ls32
44			/ [ *5( h16 ":" ) h16 ] "::" h16
45			/ [ *6( h16 ":" ) h16 ] "::"
46
47			ls32 = ( h16 ":" h16 ) / IPv4address
48			; least-significant 32 bits of address
49
50			h16 = 1*4HEXDIG
51			; 16 bits of address represented in hexadecimal
52
53			IPv6addrz = IPv6address "%" ZoneID
54			; rfc6874: an address qualified by its zone
55			@endcode
56
57			The zone accepts a strict decimal interface index on every
58			platform; where the platform names interfaces (POSIX), an
59			interface name maps through `if_nametoindex`. An unknown name
60			or malformed index is a parse error, never a silent zone 0.
61			Formatting always emits the numeric form (`%2`).
62
63			@par Specification
64			@li <a href="https://datatracker.ietf.org/doc/html/rfc4291"
65			>IP Version 6 Addressing Architecture (rfc4291)</a>
66			@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
67			>3.2.2. Host (rfc3986)</a>
68
69			@see
70			@ref ipv4_address,
71			@ref make_ipv6_address
72			*/
73			class BOOST_COROSIO_DECL ipv6_address
74			{
75			std::array<unsigned char, 16> addr_{};
76			std::uint32_t scope_id_ = 0;
77
78			public:
79			/** The number of characters in the longest possible IPv6 string.
80
81			The longest address body is the IPv4-mapped form
82			`ffff:ffff:ffff:ffff:ffff:ffff:255.255.255.255` (45 characters). A
83			numeric zone suffix adds up to eleven more (`%4294967295`), for a
84			worst case of 56; the constant carries a little slack.
85			*/
86			static constexpr std::size_t max_str_len = 60;
87
88			/** The type used to represent an address as an array of bytes.
89
90			Octets are stored in network byte order.
91			*/
92			using bytes_type = std::array<unsigned char, 16>;
93
94			/** Default constructor.
95
96			Constructs the unspecified address (::).
97
98			@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.2"
99			>2.5.2. The Unspecified Address</a>
100
101			@see
102			@ref is_unspecified
103			*/
104		113371x	ipv6_address() = default;
105
106			/** Copy constructor.
107			*/
108			ipv6_address(ipv6_address const&) = default;
109
110			/** Copy assignment.
111
112			@return A reference to this object.
113			*/
114			ipv6_address& operator=(ipv6_address const&) = default;
115
116			/** Construct from an array of bytes.
117
118			This function constructs an address
119			from the array in `bytes`, which is
120			interpreted in big-endian.
121
122			@param bytes The value to construct from.
123			@param scope_id The zone the address belongs to, as an
124			interface index; 0 means unscoped.
125			*/
126			explicit ipv6_address(
127			bytes_type const& bytes, std::uint32_t scope_id = 0) noexcept;
128
129			/** Return the zone the address belongs to.
130
131			Link-local addresses (`fe80::/10`) are unique only per network link,
132			so the address bits alone do not identify a destination. The zone —
133			an interface index, written with a `%` suffix in text form —
134			disambiguates. For global addresses the zone is 0 and has no
135			meaning.
136
137			@return The zone as an interface index; 0 if unscoped.
138
139			@par Specification
140			@li <a href="https://datatracker.ietf.org/doc/html/rfc4007"
141			>IPv6 Scoped Address Architecture (rfc4007)</a>
142			*/
143		107x	std::uint32_t scope_id() const noexcept
144			{
145		107x	return scope_id_;
146			}
147
148			/** Construct from an IPv4 address.
149
150			This function constructs an IPv6 address
151			from the IPv4 address `addr`. The resulting
152			address is an IPv4-Mapped IPv6 Address.
153
154			@param addr The address to construct from.
155
156			@par Specification
157			@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2"
158			>2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)</a>
159			*/
160			explicit ipv6_address(ipv4_address const& addr) noexcept;
161
162			/** Return the address as bytes, in network byte order.
163
164			The 16 bytes cannot carry the zone: for a scoped address
165			the result identifies the value only together with
166			@ref scope_id.
167
168			@return The address as an array of bytes.
169			*/
170		176x	bytes_type to_bytes() const noexcept
171			{
172		176x	return addr_;
173			}
174
175			/** Return the address as a string.
176
177			The returned string does not
178			contain surrounding square brackets.
179
180			@par Example
181			@par !example to_string
182
183			@return The address as a string.
184
185			@par Specification
186			@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.2">
187			2.2. Text Representation of Addresses (rfc4291)</a>
188			*/
189			std::string to_string() const;
190
191			/** Write a string representing the address to a buffer.
192
193			The resulting buffer is not null-terminated.
194
195			@throws std::length_error `dest_size < ipv6_address::max_str_len`
196
197			@param dest The buffer in which to write,
198			which must have at least `dest_size` space.
199
200			@param dest_size The size of the output buffer.
201
202			@return The formatted string view.
203			*/
204			std::string_view to_buffer(char* dest, std::size_t dest_size) const;
205
206			/** Return true if the address is unspecified.
207
208			The address 0:0:0:0:0:0:0:0 is called the
209			unspecified address. It indicates the
210			absence of an address.
211
212			@return `true` if the address is unspecified.
213
214			@par Specification
215			@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.2">
216			2.5.2. The Unspecified Address (rfc4291)</a>
217			*/
218			bool is_unspecified() const noexcept;
219
220			/** Return true if the address is a loopback address.
221
222			The unicast address 0:0:0:0:0:0:0:1 is called
223			the loopback address. It may be used by a node
224			to send an IPv6 packet to itself.
225
226			@return `true` if the address is a loopback address.
227
228			@par Specification
229			@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.3">
230			2.5.3. The Loopback Address (rfc4291)</a>
231			*/
232			bool is_loopback() const noexcept;
233
234			/** Return true if the address is a mapped IPv4 address.
235
236			This address type is used to represent the
237			addresses of IPv4 nodes as IPv6 addresses.
238
239			@return `true` if the address is a mapped IPv4 address.
240
241			@par Specification
242			@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2">
243			2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)</a>
244			*/
245			bool is_v4_mapped() const noexcept;
246
247			/** Convert a v4-mapped address to the IPv4 address it maps.
248
249			This is the inverse of the mapping constructor
250			`ipv6_address(ipv4_address const&)`: it extracts the low
251			32 bits of an IPv4-Mapped IPv6 Address (`::ffff:a.b.c.d`)
252			as an `ipv4_address`.
253
254			@throws std::system_error `errc::address_family_not_supported`
255			if the address is not v4-mapped.
256
257			@return The mapped IPv4 address.
258
259			@par Specification
260			@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2">
261			2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)</a>
262
263			@see
264			@ref is_v4_mapped
265			*/
266			ipv4_address to_v4() const;
267
268			/** Return true if the address is a multicast address.
269
270			IPv6 multicast addresses have the prefix ff00::/8.
271
272			@return `true` if the address is a multicast address.
273
274			@par Specification
275			@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.7">
276			2.7. Multicast Addresses (rfc4291)</a>
277			*/
278			bool is_multicast() const noexcept;
279
280			/** Return true if two addresses are equal.
281
282			Addresses are equal if they have the same bytes and the
283			same zone: the same link-local bits on different links are
284			different destinations.
285
286			@return `true` if the addresses are equal.
287			*/
288			friend bool
289		54x	operator==(ipv6_address const& a1, ipv6_address const& a2) noexcept
290			{
291	4/4 ✓ Branch 3 → 4 taken 50 times. ✓ Branch 3 → 6 taken 4 times. ✓ Branch 4 → 5 taken 45 times. ✓ Branch 4 → 6 taken 5 times.	54x	return a1.addr_ == a2.addr_ && a1.scope_id_ == a2.scope_id_;
292			}
293
294			/** Order two addresses.
295
296			Establishes a strict total ordering consistent with
297			`operator==`: addresses are ordered lexicographically by
298			their bytes in network order, then by zone. This makes
299			`ipv6_address` usable as a key in ordered containers such
300			as `std::map` and `std::set`.
301
302			@return The relative order of `a1` and `a2`.
303			*/
304			friend std::strong_ordering
305		17x	operator<=>(ipv6_address const& a1, ipv6_address const& a2) noexcept
306			{
307	2/2 ✓ Branch 4 → 5 taken 6 times. ✓ Branch 4 → 6 taken 11 times.	17x	if (auto c = a1.addr_ <=> a2.addr_; c != 0)
308		6x	return c;
309	3/4 ✓ Branch 6 → 7 taken 4 times. ✓ Branch 6 → 10 taken 7 times. ✓ Branch 7 → 8 taken 4 times. ✗ Branch 7 → 9 not taken.	11x	return a1.scope_id_ <=> a2.scope_id_;
310			}
311
312			/** Return an address object that represents the unspecified address.
313
314			The address 0:0:0:0:0:0:0:0 (::) may be used to bind a socket
315			to all available interfaces.
316
317			@return The unspecified address (::).
318			*/
319		16x	static ipv6_address any() noexcept
320			{
321		16x	return ipv6_address();
322			}
323
324			/** Return an address object that represents the loopback address.
325
326			The unicast address 0:0:0:0:0:0:0:1 is called
327			the loopback address. It may be used by a node
328			to send an IPv6 packet to itself.
329
330			@par Specification
331			@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.3">
332			2.5.3. The Loopback Address (rfc4291)</a>
333
334			@return The loopback address (::1).
335			*/
336			static ipv6_address loopback() noexcept;
337
338			/** Format the address to an output stream.
339
340			This function writes the address to an
341			output stream using standard notation.
342
343			@return The output stream, for chaining.
344
345			@param os The output stream to write to.
346
347			@param addr The address to write.
348			*/
349			friend BOOST_COROSIO_DECL std::ostream&
350			operator<<(std::ostream& os, ipv6_address const& addr);
351
352			private:
353			std::size_t print_impl(char* dest) const noexcept;
354			};
355
356			/** Create an IPv6 address from a string.
357
358			This function attempts to parse the string as an IPv6 address. It
359			returns an error code if the string holds no valid IPv6 address.
360
361			@par Exception Safety
362			Throws nothing.
363
364			@par Specification
365			@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
366			>3.2.2. Host (rfc3986)</a>
367
368			@param s The string to parse.
369			@return The error code, empty on success, and the parsed
370			address — default-constructed on failure.
371			*/
372			[[nodiscard]] BOOST_COROSIO_DECL capy::results<ipv6_address>
373			make_ipv6_address(std::string_view s) noexcept;
374
375			} // namespace boost::corosio
376
377			namespace std {
378
379			/// Hash support for `boost::corosio::ipv6_address`.
380			template<>
381			struct hash<boost::corosio::ipv6_address>
382			{
383			/// Return the hash of `addr`.
384			std::size_t
385		21x	operator()(boost::corosio::ipv6_address const& addr) const noexcept
386			{
387		21x	auto const bytes = addr.to_bytes();
388		21x	auto const h = hash<std::string_view>()(std::string_view(
389		21x	reinterpret_cast<char const*>(bytes.data()), bytes.size()));
390			// The zone participates in equality, so it must feed the
391			// hash; combine so it cannot cancel the byte entropy
392		21x	auto const z = hash<std::uint32_t>()(addr.scope_id());
393		21x	return h ^ (z + 0x9e3779b9u + (h << 6) + (h >> 2));
394			}
395			};
396
397			} // namespace std
398
399			#endif
400