corosio

Directory: ../corosio_lcov_PR-138/
Coverage: low: ≥ 0% medium: ≥ 75.0% high: ≥ 90.0%
Coverage Exec / Excl / Total
Lines: 100.0% 11 / 0 / 11
Functions: 100.0% 6 / 0 / 6
Branches: -% 0 / 0 / 0
include/boost/corosio/ipv4_address.hpp
Line Branch 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_IPV4_ADDRESS_HPP
11 #define BOOST_COROSIO_IPV4_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 /** An IP version 4 style address.
25
26 Objects of this type are used to construct,
27 parse, and manipulate IP version 4 addresses.
28
29 @par BNF
30 @code
31 IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
32
33 dec-octet = DIGIT ; 0-9
34 / %x31-39 DIGIT ; 10-99
35 / "1" 2DIGIT ; 100-199
36 / "2" %x30-34 DIGIT ; 200-249
37 / "25" %x30-35 ; 250-255
38 @endcode
39
40 @par Specification
41 @li <a href="https://en.wikipedia.org/wiki/IPv4">IPv4 (Wikipedia)</a>
42 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
43 >3.2.2. Host (rfc3986)</a>
44
45 @see
46 @ref parse_ipv4_address,
47 @ref ipv6_address.
48 */
49 class BOOST_COROSIO_DECL ipv4_address
50 {
51 std::uint32_t addr_ = 0;
52
53 public:
54 /** The number of characters in the longest possible IPv4 string.
55
56 The longest IPv4 address string is "255.255.255.255".
57 */
58 static constexpr std::size_t max_str_len = 15;
59
60 /** The type used to represent an address as an unsigned integer.
61 */
62 using uint_type = std::uint32_t;
63
64 /** The type used to represent an address as an array of bytes.
65 */
66 using bytes_type = std::array<unsigned char, 4>;
67
68 /** Default constructor.
69
70 Constructs the unspecified address (0.0.0.0).
71 */
72 123081 ipv4_address() = default;
73
74 /** Copy constructor.
75 */
76 ipv4_address(ipv4_address const&) = default;
77
78 /** Copy assignment.
79
80 @return A reference to this object.
81 */
82 ipv4_address& operator=(ipv4_address const&) = default;
83
84 /** Construct from an unsigned integer.
85
86 This function constructs an address from
87 the unsigned integer `u`, where the most
88 significant byte forms the first octet
89 of the resulting address.
90
91 @param u The integer to construct from.
92 */
93 explicit
94 ipv4_address(uint_type u) noexcept;
95
96 /** Construct from an array of bytes.
97
98 This function constructs an address
99 from the array in `bytes`, which is
100 interpreted in big-endian.
101
102 @param bytes The value to construct from.
103 */
104 explicit
105 ipv4_address(bytes_type const& bytes) noexcept;
106
107 /** Construct from a string.
108
109 This function constructs an address from
110 the string `s`, which must contain a valid
111 IPv4 address string or else an exception
112 is thrown.
113
114 @note For a non-throwing parse function,
115 use @ref parse_ipv4_address.
116
117 @par Exception Safety
118 Exceptions thrown on invalid input.
119
120 @throw std::invalid_argument The input failed to parse correctly.
121
122 @param s The string to parse.
123
124 @par Specification
125 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
126 >3.2.2. Host (rfc3986)</a>
127
128 @see
129 @ref parse_ipv4_address.
130 */
131 explicit
132 ipv4_address(std::string_view s);
133
134 /** Return the address as bytes, in network byte order.
135
136 @return The address as an array of bytes.
137 */
138 bytes_type
139 to_bytes() const noexcept;
140
141 /** Return the address as an unsigned integer.
142
143 @return The address as an unsigned integer.
144 */
145 uint_type
146 to_uint() const noexcept;
147
148 /** Return the address as a string in dotted decimal format.
149
150 @par Example
151 @code
152 assert( ipv4_address(0x01020304).to_string() == "1.2.3.4" );
153 @endcode
154
155 @return The address as a string.
156 */
157 std::string
158 to_string() const;
159
160 /** Write a dotted decimal string representing the address to a buffer.
161
162 The resulting buffer is not null-terminated.
163
164 @throw std::length_error `dest_size < ipv4_address::max_str_len`
165
166 @return The formatted string view.
167
168 @param dest The buffer in which to write,
169 which must have at least `dest_size` space.
170
171 @param dest_size The size of the output buffer.
172 */
173 std::string_view
174 to_buffer(char* dest, std::size_t dest_size) const;
175
176 /** Return true if the address is a loopback address.
177
178 @return `true` if the address is a loopback address.
179 */
180 bool
181 is_loopback() const noexcept;
182
183 /** Return true if the address is unspecified.
184
185 @return `true` if the address is unspecified.
186 */
187 bool
188 is_unspecified() const noexcept;
189
190 /** Return true if the address is a multicast address.
191
192 @return `true` if the address is a multicast address.
193 */
194 bool
195 is_multicast() const noexcept;
196
197 /** Return true if two addresses are equal.
198
199 @return `true` if the addresses are equal, otherwise `false`.
200 */
201 friend
202 bool
203 59 operator==(ipv4_address const& a1, ipv4_address const& a2) noexcept
204 {
205 59 return a1.addr_ == a2.addr_;
206 }
207
208 /** Return true if two addresses are not equal.
209
210 @return `true` if the addresses are not equal, otherwise `false`.
211 */
212 friend
213 bool
214 2 operator!=(ipv4_address const& a1, ipv4_address const& a2) noexcept
215 {
216 2 return a1.addr_ != a2.addr_;
217 }
218
219 /** Return an address object that represents any address.
220
221 @return The any address (0.0.0.0).
222 */
223 static
224 ipv4_address
225 123057 any() noexcept
226 {
227 123057 return ipv4_address();
228 }
229
230 /** Return an address object that represents the loopback address.
231
232 @return The loopback address (127.0.0.1).
233 */
234 static
235 ipv4_address
236 8341 loopback() noexcept
237 {
238 8341 return ipv4_address(0x7F000001);
239 }
240
241 /** Return an address object that represents the broadcast address.
242
243 @return The broadcast address (255.255.255.255).
244 */
245 static
246 ipv4_address
247 1 broadcast() noexcept
248 {
249 1 return ipv4_address(0xFFFFFFFF);
250 }
251
252 /** Format the address to an output stream.
253
254 IPv4 addresses written to output streams
255 are written in their dotted decimal format.
256
257 @param os The output stream.
258 @param addr The address to format.
259 @return The output stream.
260 */
261 friend
262 BOOST_COROSIO_DECL
263 std::ostream&
264 operator<<(std::ostream& os, ipv4_address const& addr);
265
266 private:
267 friend class ipv6_address;
268
269 std::size_t
270 print_impl(char* dest) const noexcept;
271 };
272
273 //------------------------------------------------
274
275 /** Return an IPv4 address from an IP address string in dotted decimal form.
276
277 @param s The string to parse.
278 @param addr The address to store the result.
279 @return An error code (empty on success).
280 */
281 [[nodiscard]] BOOST_COROSIO_DECL
282 std::error_code
283 parse_ipv4_address(
284 std::string_view s,
285 ipv4_address& addr) noexcept;
286
287 } // namespace boost::corosio
288
289 #endif
290