Root/libs / url / include / boost / url / ipv4_address.hpp
Prev Index Next

libs/url/include/boost/url/ipv4_address.hpp

100.0% Lines (17/17) 100.0% Functions (8/8) -% Branches (0/0)
libs/url/include/boost/url/ipv4_address.hpp
Line Hits Source Code
1 //
2 // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
3 // Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)
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/boostorg/url
9 //
10
11 #ifndef BOOST_URL_IPV4_ADDRESS_HPP
12 #define BOOST_URL_IPV4_ADDRESS_HPP
13
14 #include <boost/url/detail/config.hpp>
15 #include <boost/url/error.hpp>
16 #include <boost/url/error_types.hpp>
17 #include <boost/core/detail/string_view.hpp>
18 #include <boost/url/grammar/string_token.hpp>
19 #include <string>
20 #include <array>
21 #include <cstdint>
22 #include <iosfwd>
23
24 namespace boost {
25 namespace urls {
26
27 /** An IP version 4 style address.
28
29 Objects of this type are used to construct,
30 parse, and manipulate IP version 6 addresses.
31
32 @par BNF
33 @code
34 IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
35
36 dec-octet = DIGIT ; 0-9
37 / %x31-39 DIGIT ; 10-99
38 / "1" 2DIGIT ; 100-199
39 / "2" %x30-34 DIGIT ; 200-249
40 / "25" %x30-35 ; 250-255
41 @endcode
42
43 @par Specification
44 @li <a href="https://en.wikipedia.org/wiki/IPv4"
45 >IPv4 (Wikipedia)</a>
46 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
47 >3.2.2. Host (rfc3986)</a>
48
49 @see
50 @ref parse_ipv4_address,
51 @ref ipv6_address.
52 */
53 class ipv4_address
54 {
55 public:
56 /** The number of characters in the longest possible IPv4 string.
57
58 The longest ipv4 address string is "255.255.255.255".
59 */
60 static
61 constexpr
62 std::size_t max_str_len = 15;
63
64 /** The type used to represent an address as an unsigned integer
65 */
66 using uint_type =
67 std::uint_least32_t;
68
69 /** The type used to represent an address as an array of bytes
70 */
71 using bytes_type =
72 std::array<unsigned char, 4>;
73
74 /** Constructor.
75 */
76 77 ipv4_address() = default;
77
78 /** Constructor.
79 */
80 ipv4_address(
81 ipv4_address const&) = default;
82
83 /** Copy Assignment.
84
85 @param other The object to copy.
86 @return A reference to this object.
87 */
88 ipv4_address&
89 operator=(
90 ipv4_address const& other) = default;
91
92 //
93 //---
94 //
95
96 /** Construct from an unsigned integer.
97
98 This function constructs an address from
99 the unsigned integer `u`, where the most
100 significant byte forms the first octet
101 of the resulting address.
102
103 @param u The integer to construct from.
104 */
105 BOOST_URL_DECL
106 explicit
107 ipv4_address(
108 uint_type u) noexcept;
109
110 /** Construct from an array of bytes.
111
112 This function constructs an address
113 from the array in `bytes`, which is
114 interpreted in big-endian.
115
116 @param bytes The value to construct from.
117 */
118 BOOST_URL_DECL
119 explicit
120 ipv4_address(
121 bytes_type const& bytes) noexcept;
122
123 /** Construct from a string.
124
125 This function constructs an address from
126 the string `s`, which must contain a valid
127 IPv4 address string or else an exception
128 is thrown.
129
130 @note For a non-throwing parse function,
131 use @ref parse_ipv4_address.
132
133 @par Exception Safety
134 Exceptions thrown on invalid input.
135
136 @throw system_error The input failed to parse correctly.
137
138 @param s The string to parse.
139
140 @par Specification
141 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
142 >3.2.2. Host (rfc3986)</a>
143
144 @see
145 @ref parse_ipv4_address.
146 */
147 BOOST_URL_DECL
148 explicit
149 ipv4_address(
150 core::string_view s);
151
152 /** Return the address as bytes, in network byte order.
153
154 @return The address as an array of bytes.
155 */
156 BOOST_URL_DECL
157 bytes_type
158 to_bytes() const noexcept;
159
160 /** Return the address as an unsigned integer.
161
162 @return The address as an unsigned integer.
163 */
164 BOOST_URL_DECL
165 uint_type
166 to_uint() const noexcept;
167
168 /** Return the address as a string in dotted decimal format
169
170 When called with no arguments, the
171 return type is `std::string`.
172 Otherwise, the return type and style
173 of output is determined by which string
174 token is passed.
175
176 @par Example
177 @code
178 assert( ipv4_address(0x01020304).to_string() == "1.2.3.4" );
179 @endcode
180
181 @par Complexity
182 Constant.
183
184 @par Exception Safety
185 Strong guarantee.
186 Calls to allocate may throw.
187 String tokens may throw exceptions.
188
189 @return The return type of the string token.
190 If the token parameter is omitted, then
191 a new `std::string` is returned.
192 Otherwise, the function return type
193 is the result type of the token.
194
195 @param token An optional string token.
196
197 @par Specification
198 @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.2">
199 2.2. Text Representation of Addresses (rfc4291)</a>
200 */
201 template<BOOST_URL_STRTOK_TPARAM>
202 BOOST_URL_STRTOK_RETURN
203 2 to_string(StringToken&& token = {}) const
204 {
205 2 to_string_impl(token);
206 2 return token.result();
207 }
208
209 /** Write a dotted decimal string representing the address to a buffer
210
211 The resulting buffer is not null-terminated.
212
213 @throw std::length_error `dest_size < ipv4_address::max_str_len`
214
215 @return The formatted string
216
217 @param dest The buffer in which to write,
218 which must have at least `dest_size` space.
219
220 @param dest_size The size of the output buffer.
221 */
222 BOOST_URL_DECL
223 core::string_view
224 to_buffer(
225 char* dest,
226 std::size_t dest_size) const;
227
228 /** Return true if the address is a loopback address
229
230 @return `true` if the address is a loopback address
231 */
232 BOOST_URL_DECL
233 bool
234 is_loopback() const noexcept;
235
236 /** Return true if the address is unspecified
237
238 @return `true` if the address is unspecified
239 */
240 BOOST_URL_DECL
241 bool
242 is_unspecified() const noexcept;
243
244 /** Return true if the address is a multicast address
245
246 @return `true` if the address is a multicast address
247 */
248 BOOST_URL_DECL
249 bool
250 is_multicast() const noexcept;
251
252 /** Return true if two addresses are equal
253
254 @param a1 The first address to compare.
255 @param a2 The second address to compare.
256 @return `true` if the addresses are equal, otherwise `false`.
257
258 */
259 friend
260 bool
261 57 operator==(
262 ipv4_address const& a1,
263 ipv4_address const& a2) noexcept
264 {
265 57 return a1.addr_ == a2.addr_;
266 }
267
268 /** Return true if two addresses are not equal
269
270 @param a1 The first address to compare.
271 @param a2 The second address to compare.
272 @return `true` if the addresses are not equal, otherwise `false`.
273 */
274 friend
275 bool
276 3 operator!=(
277 ipv4_address const& a1,
278 ipv4_address const& a2) noexcept
279 {
280 3 return a1.addr_ != a2.addr_;
281 }
282
283 /** Return an address object that represents any address
284
285 @return The any address.
286 */
287 static
288 ipv4_address
289 3 any() noexcept
290 {
291 3 return ipv4_address();
292 }
293
294 /** Return an address object that represents the loopback address
295
296 @return The loopback address.
297 */
298 static
299 ipv4_address
300 3 loopback() noexcept
301 {
302 3 return ipv4_address(0x7F000001);
303 }
304
305 /** Return an address object that represents the broadcast address
306
307 @return The broadcast address.
308 */
309 static
310 ipv4_address
311 3 broadcast() noexcept
312 {
313 3 return ipv4_address(0xFFFFFFFF);
314 }
315
316 /** Format the address to an output stream.
317
318 IPv4 addresses written to output streams
319 are written in their dotted decimal format.
320
321 @param os The output stream.
322 @param addr The address to format.
323 @return The output stream.
324 */
325 friend
326 std::ostream&
327 1 operator<<(
328 std::ostream& os,
329 ipv4_address const& addr)
330 {
331 1 addr.write_ostream(os);
332 1 return os;
333 }
334
335 private:
336 friend class ipv6_address;
337
338 BOOST_URL_DECL void write_ostream(std::ostream&) const;
339
340 BOOST_URL_DECL
341 std::size_t
342 print_impl(
343 char* dest) const noexcept;
344
345 BOOST_URL_DECL
346 void
347 to_string_impl(
348 string_token::arg& t) const;
349
350 uint_type addr_ = 0;
351 };
352
353 //------------------------------------------------
354
355 /** Return an IPv4 address from an IP address string in dotted decimal form
356
357 @param s The string to parse.
358 @return The parsed address, or an error code.
359 */
360 BOOST_URL_DECL
361 system::result<ipv4_address>
362 parse_ipv4_address(
363 core::string_view s) noexcept;
364
365 } // urls
366 } // boost
367
368 #endif
369