GCC Code Coverage Report

Line	Branch	Exec	Source
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