include/boost/corosio/ipv6_address.hpp

Directory:	../corosio_lcov_PR-138/
Coverage:	low: ≥ 0% medium: ≥ 75.0% high: ≥ 90.0%

	Coverage	Exec / Excl / Total
Lines:	100.0%	7 / 0 / 7
Functions:	100.0%	4 / 0 / 4
Branches:	-%	0 / 0 / 0

    include/boost/corosio/ipv6_address.hpp
    
        Line
        Branch
        Exec
        Source
      
        //
      
        // Copyright (c) 2026 Vinnie Falco (vinnie.falco@gmail.com)
      
        //
      
        // Distributed under the Boost Software License, Version 1.0. (See accompanying
      
        // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
      
        //
      
        // Official repository: https://github.com/cppalliance/corosio
      
        //
      
        #ifndef BOOST_COROSIO_IPV6_ADDRESS_HPP
      
        #define BOOST_COROSIO_IPV6_ADDRESS_HPP
      
        #include <boost/corosio/detail/config.hpp>
      
        #include <array>
      
        #include <cstdint>
      
        #include <iosfwd>
      
        #include <string>
      
        #include <string_view>
      
        #include <system_error>
      
        namespace boost::corosio {
      
        class ipv4_address;
      
        /** An IP version 6 style address.
      
            Objects of this type are used to construct,
      
            parse, and manipulate IP version 6 addresses.
      
            @par BNF
      
            @code
      
            IPv6address =                            6( h16 ":" ) ls32
      
                        /                       "::" 5( h16 ":" ) ls32
      
                        / [               h16 ] "::" 4( h16 ":" ) ls32
      
                        / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
      
                        / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
      
                        / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
      
                        / [ *4( h16 ":" ) h16 ] "::"              ls32
      
                        / [ *5( h16 ":" ) h16 ] "::"              h16
      
                        / [ *6( h16 ":" ) h16 ] "::"
      
            ls32        = ( h16 ":" h16 ) / IPv4address
      
                        ; least-significant 32 bits of address
      
            h16         = 1*4HEXDIG
      
                        ; 16 bits of address represented in hexadecimal
      
            @endcode
      
            @par Specification
      
            @li <a href="https://datatracker.ietf.org/doc/html/rfc4291"
      
                >IP Version 6 Addressing Architecture (rfc4291)</a>
      
            @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
      
                >3.2.2. Host (rfc3986)</a>
      
            @see
      
                @ref ipv4_address,
      
                @ref parse_ipv6_address.
      
        */
      
        class BOOST_COROSIO_DECL ipv6_address
      
        {
      
            std::array<unsigned char, 16> addr_{};
      
        public:
      
            /** The number of characters in the longest possible IPv6 string.
      
                The longest IPv6 address is:
      
                @code
      
                ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
      
                @endcode
      
                or with IPv4-mapped:
      
                @code
      
                ::ffff:255.255.255.255
      
                @endcode
      
            */
      
            static constexpr std::size_t max_str_len = 49;
      
            /** The type used to represent an address as an array of bytes.
      
                Octets are stored in network byte order.
      
            */
      
            using bytes_type = std::array<unsigned char, 16>;
      
            /** Default constructor.
      
                Constructs the unspecified address (::).
      
                @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.2"
      
                    >2.5.2. The Unspecified Address</a>
      
                @see
      
                    @ref is_unspecified
      
            */
      
        151552
            ipv6_address() = default;
      
            /** Copy constructor.
      
            */
      
            ipv6_address(ipv6_address const&) = default;
      
            /** Copy assignment.
      
                @return A reference to this object.
      
            */
      
            ipv6_address& operator=(ipv6_address const&) = default;
      
            /** Construct from an array of bytes.
      
                This function constructs an address
      
                from the array in `bytes`, which is
      
                interpreted in big-endian.
      
                @param bytes The value to construct from.
      
            */
      
            explicit
      
            ipv6_address(bytes_type const& bytes) noexcept;
      
            /** Construct from an IPv4 address.
      
                This function constructs an IPv6 address
      
                from the IPv4 address `addr`. The resulting
      
                address is an IPv4-Mapped IPv6 Address.
      
                @param addr The address to construct from.
      
                @par Specification
      
                @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2"
      
                    >2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)</a>
      
            */
      
            explicit
      
            ipv6_address(ipv4_address const& addr) noexcept;
      
            /** Construct from a string.
      
                This function constructs an address from
      
                the string `s`, which must contain a valid
      
                IPv6 address string or else an exception
      
                is thrown.
      
                @note For a non-throwing parse function,
      
                use @ref parse_ipv6_address.
      
                @par Exception Safety
      
                Exceptions thrown on invalid input.
      
                @throw std::invalid_argument
      
                The input failed to parse correctly.
      
                @param s The string to parse.
      
                @par Specification
      
                @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
      
                    >3.2.2. Host (rfc3986)</a>
      
                @see
      
                    @ref parse_ipv6_address.
      
            */
      
            explicit
      
            ipv6_address(std::string_view s);
      
            /** Return the address as bytes, in network byte order.
      
                @return The address as an array of bytes.
      
            */
      
            bytes_type
      
        2
            to_bytes() const noexcept
      
            {
      
        2
                return addr_;
      
            }
      
            /** Return the address as a string.
      
                The returned string does not
      
                contain surrounding square brackets.
      
                @par Example
      
                @code
      
                ipv6_address::bytes_type b = {{
      
                        0, 1, 0, 2, 0, 3, 0, 4,
      
                        0, 5, 0, 6, 0, 7, 0, 8 }};
      
                ipv6_address a(b);
      
                assert(a.to_string() == "1:2:3:4:5:6:7:8");
      
                @endcode
      
                @return The address as a string.
      
                @par Specification
      
                @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.2">
      
                    2.2. Text Representation of Addresses (rfc4291)</a>
      
            */
      
            std::string
      
            to_string() const;
      
            /** Write a string representing the address to a buffer.
      
                The resulting buffer is not null-terminated.
      
                @throw std::length_error `dest_size < ipv6_address::max_str_len`
      
                @return The formatted string view.
      
                @param dest The buffer in which to write,
      
                which must have at least `dest_size` space.
      
                @param dest_size The size of the output buffer.
      
            */
      
            std::string_view
      
            to_buffer(char* dest, std::size_t dest_size) const;
      
            /** Return true if the address is unspecified.
      
                The address 0:0:0:0:0:0:0:0 is called the
      
                unspecified address. It indicates the
      
                absence of an address.
      
                @return `true` if the address is unspecified.
      
                @par Specification
      
                @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.2">
      
                    2.5.2. The Unspecified Address (rfc4291)</a>
      
            */
      
            bool
      
            is_unspecified() const noexcept;
      
            /** Return true if the address is a loopback address.
      
                The unicast address 0:0:0:0:0:0:0:1 is called
      
                the loopback address. It may be used by a node
      
                to send an IPv6 packet to itself.
      
                @return `true` if the address is a loopback address.
      
                @par Specification
      
                @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.3">
      
                    2.5.3. The Loopback Address (rfc4291)</a>
      
            */
      
            bool
      
            is_loopback() const noexcept;
      
            /** Return true if the address is a mapped IPv4 address.
      
                This address type is used to represent the
      
                addresses of IPv4 nodes as IPv6 addresses.
      
                @return `true` if the address is a mapped IPv4 address.
      
                @par Specification
      
                @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2">
      
                    2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)</a>
      
            */
      
            bool
      
            is_v4_mapped() const noexcept;
      
            /** Return true if two addresses are equal.
      
                @return `true` if the addresses are equal.
      
            */
      
            friend
      
            bool
      
        16
            operator==(ipv6_address const& a1, ipv6_address const& a2) noexcept
      
            {
      
        16
                return a1.addr_ == a2.addr_;
      
            }
      
            /** Return true if two addresses are not equal.
      
                @return `true` if the addresses are not equal.
      
            */
      
            friend
      
            bool
      
        2
            operator!=(ipv6_address const& a1, ipv6_address const& a2) noexcept
      
            {
      
        2
                return a1.addr_ != a2.addr_;
      
            }
      
            /** Return an address object that represents the loopback address.
      
                The unicast address 0:0:0:0:0:0:0:1 is called
      
                the loopback address. It may be used by a node
      
                to send an IPv6 packet to itself.
      
                @par Specification
      
                @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.3">
      
                    2.5.3. The Loopback Address (rfc4291)</a>
      
                @return The loopback address (::1).
      
            */
      
            static
      
            ipv6_address
      
            loopback() noexcept;
      
            /** Format the address to an output stream.
      
                This function writes the address to an
      
                output stream using standard notation.
      
                @return The output stream, for chaining.
      
                @param os The output stream to write to.
      
                @param addr The address to write.
      
            */
      
            friend
      
            BOOST_COROSIO_DECL
      
            std::ostream&
      
            operator<<(std::ostream& os, ipv6_address const& addr);
      
        private:
      
            std::size_t
      
            print_impl(char* dest) const noexcept;
      
        };
      
        //------------------------------------------------
      
        /** Parse a string containing an IPv6 address.
      
            This function attempts to parse the string
      
            as an IPv6 address and returns an error code
      
            if the string does not contain a valid IPv6 address.
      
            @par Exception Safety
      
            Throws nothing.
      
            @return An error code (empty on success).
      
            @param s The string to parse.
      
            @param addr The address to store the result.
      
        */
      
        [[nodiscard]] BOOST_COROSIO_DECL
      
        std::error_code
      
        parse_ipv6_address(
      
            std::string_view s,
      
            ipv6_address& addr) noexcept;
      
        } // namespace boost::corosio
      
        #endif

Line	Exec	Source
1		//
2		// Copyright (c) 2026 Vinnie Falco (vinnie.falco@gmail.com)
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_IPV6_ADDRESS_HPP
11		#define BOOST_COROSIO_IPV6_ADDRESS_HPP
12
13		#include <boost/corosio/detail/config.hpp>
14
15		#include <array>
16		#include <cstdint>
17		#include <iosfwd>
18		#include <string>
19		#include <string_view>
20		#include <system_error>
21
22		namespace boost::corosio {
23
24		class ipv4_address;
25
26		/** An IP version 6 style address.
27
28		Objects of this type are used to construct,
29		parse, and manipulate IP version 6 addresses.
30
31		@par BNF
32		@code
33		IPv6address = 6( h16 ":" ) ls32
34		/ "::" 5( h16 ":" ) ls32
35		/ [ h16 ] "::" 4( h16 ":" ) ls32
36		/ [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
37		/ [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
38		/ [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32
39		/ [ *4( h16 ":" ) h16 ] "::" ls32
40		/ [ *5( h16 ":" ) h16 ] "::" h16
41		/ [ *6( h16 ":" ) h16 ] "::"
42
43		ls32 = ( h16 ":" h16 ) / IPv4address
44		; least-significant 32 bits of address
45
46		h16 = 1*4HEXDIG
47		; 16 bits of address represented in hexadecimal
48		@endcode
49
50		@par Specification
51		@li <a href="https://datatracker.ietf.org/doc/html/rfc4291"
52		>IP Version 6 Addressing Architecture (rfc4291)</a>
53		@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
54		>3.2.2. Host (rfc3986)</a>
55
56		@see
57		@ref ipv4_address,
58		@ref parse_ipv6_address.
59		*/
60		class BOOST_COROSIO_DECL ipv6_address
61		{
62		std::array<unsigned char, 16> addr_{};
63
64		public:
65		/** The number of characters in the longest possible IPv6 string.
66
67		The longest IPv6 address is:
68		@code
69		ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
70		@endcode
71		or with IPv4-mapped:
72		@code
73		::ffff:255.255.255.255
74		@endcode
75		*/
76		static constexpr std::size_t max_str_len = 49;
77
78		/** The type used to represent an address as an array of bytes.
79
80		Octets are stored in network byte order.
81		*/
82		using bytes_type = std::array<unsigned char, 16>;
83
84		/** Default constructor.
85
86		Constructs the unspecified address (::).
87
88		@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.2"
89		>2.5.2. The Unspecified Address</a>
90
91		@see
92		@ref is_unspecified
93		*/
94	151552	ipv6_address() = default;
95
96		/** Copy constructor.
97		*/
98		ipv6_address(ipv6_address const&) = default;
99
100		/** Copy assignment.
101
102		@return A reference to this object.
103		*/
104		ipv6_address& operator=(ipv6_address const&) = default;
105
106		/** Construct from an array of bytes.
107
108		This function constructs an address
109		from the array in `bytes`, which is
110		interpreted in big-endian.
111
112		@param bytes The value to construct from.
113		*/
114		explicit
115		ipv6_address(bytes_type const& bytes) noexcept;
116
117		/** Construct from an IPv4 address.
118
119		This function constructs an IPv6 address
120		from the IPv4 address `addr`. The resulting
121		address is an IPv4-Mapped IPv6 Address.
122
123		@param addr The address to construct from.
124
125		@par Specification
126		@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2"
127		>2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)</a>
128		*/
129		explicit
130		ipv6_address(ipv4_address const& addr) noexcept;
131
132		/** Construct from a string.
133
134		This function constructs an address from
135		the string `s`, which must contain a valid
136		IPv6 address string or else an exception
137		is thrown.
138
139		@note For a non-throwing parse function,
140		use @ref parse_ipv6_address.
141
142		@par Exception Safety
143		Exceptions thrown on invalid input.
144
145		@throw std::invalid_argument
146		The input failed to parse correctly.
147
148		@param s The string to parse.
149
150		@par Specification
151		@li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
152		>3.2.2. Host (rfc3986)</a>
153
154		@see
155		@ref parse_ipv6_address.
156		*/
157		explicit
158		ipv6_address(std::string_view s);
159
160		/** Return the address as bytes, in network byte order.
161
162		@return The address as an array of bytes.
163		*/
164		bytes_type
165	2	to_bytes() const noexcept
166		{
167	2	return addr_;
168		}
169
170		/** Return the address as a string.
171
172		The returned string does not
173		contain surrounding square brackets.
174
175		@par Example
176		@code
177		ipv6_address::bytes_type b = {{
178		0, 1, 0, 2, 0, 3, 0, 4,
179		0, 5, 0, 6, 0, 7, 0, 8 }};
180		ipv6_address a(b);
181		assert(a.to_string() == "1:2:3:4:5:6:7:8");
182		@endcode
183
184		@return The address as a string.
185
186		@par Specification
187		@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.2">
188		2.2. Text Representation of Addresses (rfc4291)</a>
189		*/
190		std::string
191		to_string() const;
192
193		/** Write a string representing the address to a buffer.
194
195		The resulting buffer is not null-terminated.
196
197		@throw std::length_error `dest_size < ipv6_address::max_str_len`
198
199		@return The formatted string view.
200
201		@param dest The buffer in which to write,
202		which must have at least `dest_size` space.
203
204		@param dest_size The size of the output buffer.
205		*/
206		std::string_view
207		to_buffer(char* dest, std::size_t dest_size) const;
208
209		/** Return true if the address is unspecified.
210
211		The address 0:0:0:0:0:0:0:0 is called the
212		unspecified address. It indicates the
213		absence of an address.
214
215		@return `true` if the address is unspecified.
216
217		@par Specification
218		@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.2">
219		2.5.2. The Unspecified Address (rfc4291)</a>
220		*/
221		bool
222		is_unspecified() const noexcept;
223
224		/** Return true if the address is a loopback address.
225
226		The unicast address 0:0:0:0:0:0:0:1 is called
227		the loopback address. It may be used by a node
228		to send an IPv6 packet to itself.
229
230		@return `true` if the address is a loopback address.
231
232		@par Specification
233		@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.3">
234		2.5.3. The Loopback Address (rfc4291)</a>
235		*/
236		bool
237		is_loopback() const noexcept;
238
239		/** Return true if the address is a mapped IPv4 address.
240
241		This address type is used to represent the
242		addresses of IPv4 nodes as IPv6 addresses.
243
244		@return `true` if the address is a mapped IPv4 address.
245
246		@par Specification
247		@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2">
248		2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)</a>
249		*/
250		bool
251		is_v4_mapped() const noexcept;
252
253		/** Return true if two addresses are equal.
254
255		@return `true` if the addresses are equal.
256		*/
257		friend
258		bool
259	16	operator==(ipv6_address const& a1, ipv6_address const& a2) noexcept
260		{
261	16	return a1.addr_ == a2.addr_;
262		}
263
264		/** Return true if two addresses are not equal.
265
266		@return `true` if the addresses are not equal.
267		*/
268		friend
269		bool
270	2	operator!=(ipv6_address const& a1, ipv6_address const& a2) noexcept
271		{
272	2	return a1.addr_ != a2.addr_;
273		}
274
275		/** Return an address object that represents the loopback address.
276
277		The unicast address 0:0:0:0:0:0:0:1 is called
278		the loopback address. It may be used by a node
279		to send an IPv6 packet to itself.
280
281		@par Specification
282		@li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.3">
283		2.5.3. The Loopback Address (rfc4291)</a>
284
285		@return The loopback address (::1).
286		*/
287		static
288		ipv6_address
289		loopback() noexcept;
290
291		/** Format the address to an output stream.
292
293		This function writes the address to an
294		output stream using standard notation.
295
296		@return The output stream, for chaining.
297
298		@param os The output stream to write to.
299
300		@param addr The address to write.
301		*/
302		friend
303		BOOST_COROSIO_DECL
304		std::ostream&
305		operator<<(std::ostream& os, ipv6_address const& addr);
306
307		private:
308		std::size_t
309		print_impl(char* dest) const noexcept;
310		};
311
312		//------------------------------------------------
313
314		/** Parse a string containing an IPv6 address.
315
316		This function attempts to parse the string
317		as an IPv6 address and returns an error code
318		if the string does not contain a valid IPv6 address.
319
320		@par Exception Safety
321		Throws nothing.
322
323		@return An error code (empty on success).
324
325		@param s The string to parse.
326		@param addr The address to store the result.
327		*/
328		[[nodiscard]] BOOST_COROSIO_DECL
329		std::error_code
330		parse_ipv6_address(
331		std::string_view s,
332		ipv6_address& addr) noexcept;
333
334		} // namespace boost::corosio
335
336		#endif
337