GCC Code Coverage Report

Line	Branch	Exec	Source
1			//
2			// Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot 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/boostorg/url
8			//
9
10			#ifndef BOOST_URL_GRAMMAR_RANGE_RULE_HPP
11			#define BOOST_URL_GRAMMAR_RANGE_RULE_HPP
12
13			#include <boost/url/detail/config.hpp>
14			#include <boost/url/error.hpp>
15			#include <boost/core/detail/string_view.hpp>
16			#include <boost/url/grammar/parse.hpp>
17			#include <boost/url/grammar/type_traits.hpp>
18			#include <boost/core/detail/static_assert.hpp>
19			#include <cstddef>
20			#include <iterator>
21			#include <type_traits>
22			#include <stddef.h> // ::max_align_t
23
24			namespace boost {
25			namespace urls {
26			namespace grammar {
27			namespace implementation_defined {
28			template<class R0, class R1>
29			struct range_rule_t;
30			} // implementation_defined
31
32			/** A forward range of parsed elements
33
34			Objects of this type are forward ranges
35			returned when parsing using the
36			@ref range_rule.
37			Iteration is performed by re-parsing the
38			underlying character buffer. Ownership
39			of the buffer is not transferred; the
40			caller is responsible for ensuring that
41			the lifetime of the buffer extends until
42			it is no longer referenced by the range.
43
44			@note
45
46			The implementation may use temporary,
47			recycled storage for type-erasure. Objects
48			of type `range` are intended to be used
49			ephemerally. That is, for short durations
50			such as within a function scope. If it is
51			necessary to store the range for a long
52			period of time or with static storage
53			duration, it is necessary to copy the
54			contents to an object of a different type.
55
56			@tparam T The value type of the range
57
58			@see
59			@ref parse,
60			@ref range_rule.
61			*/
62			template<class T>
63			class range
64			{
65			// buffer size for type-erased rule
66			static constexpr
67			std::size_t BufferSize = 128;
68
69			struct small_buffer
70			{
71			alignas(alignof(::max_align_t))
72			unsigned char buf[BufferSize];
73
74		707	void const* addr() const noexcept
75			{
76		707	return buf;
77			}
78
79		3317	void* addr() noexcept
80			{
81		3317	return buf;
82			}
83			};
84
85			small_buffer sb_;
86			core::string_view s_;
87			std::size_t n_ = 0;
88
89			//--------------------------------------------
90
91			struct any_rule;
92
93			template<class R, bool>
94			struct impl1;
95
96			template<
97			class R0, class R1, bool>
98			struct impl2;
99
100			template<
101			class R0, class R1>
102			friend struct implementation_defined::range_rule_t;
103
104			any_rule&
105		3317	get() noexcept
106			{
107			return *reinterpret_cast<
108		3317	any_rule*>(sb_.addr());
109			}
110
111			any_rule const&
112		707	get() const noexcept
113			{
114			return *reinterpret_cast<
115			any_rule const*>(
116		707	sb_.addr());
117			}
118
119			template<class R>
120			range(
121			core::string_view s,
122			std::size_t n,
123			R const& r);
124
125			template<
126			class R0, class R1>
127			range(
128			core::string_view s,
129			std::size_t n,
130			R0 const& first,
131			R1 const& next);
132
133			public:
134			/** The type of each element of the range
135			*/
136			using value_type = T;
137
138			/** The type of each element of the range
139			*/
140			using reference = T const&;
141
142			/** The type of each element of the range
143			*/
144			using const_reference = T const&;
145
146			/** Provided for compatibility, unused
147			*/
148			using pointer = void const*;
149
150			/** The type used to represent unsigned integers
151			*/
152			using size_type = std::size_t;
153
154			/** The type used to represent signed integers
155			*/
156			using difference_type = std::ptrdiff_t;
157
158			/** A constant, forward iterator to elements of the range
159			*/
160			class iterator;
161
162			/** A constant, forward iterator to elements of the range
163			*/
164			using const_iterator = iterator;
165
166			/** Destructor
167			*/
168			~range();
169
170			/** Constructor
171
172			Default-constructed ranges have
173			zero elements.
174
175			@par Exception Safety
176			Throws nothing.
177			*/
178			range() noexcept;
179
180			/** Constructor
181
182			The new range references the
183			same underlying character buffer.
184			Ownership is not transferred; the
185			caller is responsible for ensuring
186			that the lifetime of the buffer
187			extends until it is no longer
188			referenced. The moved-from object
189			becomes as if default-constructed.
190
191			@par Exception Safety
192			Throws nothing.
193			*/
194			range(range&&) noexcept;
195
196			/** Constructor
197
198			The copy references the same
199			underlying character buffer.
200			Ownership is not transferred; the
201			caller is responsible for ensuring
202			that the lifetime of the buffer
203			extends until it is no longer
204			referenced.
205
206			@par Exception Safety
207			Throws nothing.
208			*/
209			range(range const&) noexcept;
210
211			/** Assignment
212
213			After the move, this references the
214			same underlying character buffer. Ownership
215			is not transferred; the caller is responsible
216			for ensuring that the lifetime of the buffer
217			extends until it is no longer referenced.
218			The moved-from object becomes as if
219			default-constructed.
220
221			@par Exception Safety
222			Throws nothing.
223
224			@return `*this`
225			*/
226			range&
227			operator=(range&&) noexcept;
228
229			/** Assignment
230
231			The copy references the same
232			underlying character buffer.
233			Ownership is not transferred; the
234			caller is responsible for ensuring
235			that the lifetime of the buffer
236			extends until it is no longer
237			referenced.
238
239			@par Exception Safety
240			Throws nothing.
241
242			@return `*this`
243			*/
244			range&
245			operator=(range const&) noexcept;
246
247			/** Return an iterator to the beginning
248
249			@return An iterator to the first element
250			*/
251			iterator begin() const noexcept;
252
253			/** Return an iterator to the end
254
255			@return An iterator to one past the last element
256			*/
257			iterator end() const noexcept;
258
259			/** Return true if the range is empty
260
261			@return `true` if the range is empty
262			*/
263			bool
264		11	empty() const noexcept
265			{
266		11	return n_ == 0;
267			}
268
269			/** Return the number of elements in the range
270
271			@return The number of elements
272			*/
273			std::size_t
274		34	size() const noexcept
275			{
276		34	return n_;
277			}
278
279			/** Return the matching part of the string
280
281			@return A string view representing the range
282			*/
283			core::string_view
284		19	string() const noexcept
285			{
286		19	return s_;
287			}
288			};
289
290			//------------------------------------------------
291
292			namespace implementation_defined {
293			template<
294			class R0,
295			class R1 = void>
296			struct range_rule_t;
297			}
298
299			//------------------------------------------------
300
301			namespace implementation_defined {
302			template<class R>
303			struct range_rule_t<R>
304			{
305			using value_type =
306			range<typename R::value_type>;
307
308			system::result<value_type>
309			parse(
310			char const*& it,
311			char const* end) const;
312
313			constexpr
314		18	range_rule_t(
315			R const& next,
316			std::size_t N,
317			std::size_t M) noexcept
318		18	: next_(next)
319		18	, N_(N)
320		18	, M_(M)
321			{
322		18	}
323
324			private:
325			R const next_;
326			std::size_t N_;
327			std::size_t M_;
328			};
329			} // implementation_defined
330
331			/** Match a repeating number of elements
332
333			Elements are matched using the passed rule.
334			<br>
335			Normally when the rule returns an error,
336			the range ends and the input is rewound to
337			one past the last character that matched
338			successfully. However, if the rule returns
339			the special value @ref error::end_of_range, the
340			input is not rewound. This allows for rules
341			which consume input without producing
342			elements in the range. For example, to
343			relax the grammar for a comma-delimited
344			list by allowing extra commas in between
345			elements.
346
347			@par Value Type
348			@code
349			using value_type = range< typename Rule::value_type >;
350			@endcode
351
352			@par Example
353			Rules are used with the function @ref parse.
354			@code
355			// range = 1*( ";" token )
356
357			system::result< range<core::string_view> > rv = parse( ";alpha;xray;charlie",
358			range_rule(
359			tuple_rule(
360			squelch( delim_rule( ';' ) ),
361			token_rule( alpha_chars ) ),
362			1 ) );
363			@endcode
364
365			@par BNF
366			@code
367			range = <N>*<M>next
368			@endcode
369
370			@par Specification
371			@li <a href="https://datatracker.ietf.org/doc/html/rfc5234#section-3.6"
372			>3.6. Variable Repetition (rfc5234)</a>
373
374			@param next The rule to use for matching
375			each element. The range extends until this
376			rule returns an error.
377
378			@param N The minimum number of elements for
379			the range to be valid. If omitted, this
380			defaults to zero.
381
382			@param M The maximum number of elements for
383			the range to be valid. If omitted, this
384			defaults to unlimited.
385
386			@return A rule that matches the range.
387
388			@see
389			@ref alpha_chars,
390			@ref delim_rule,
391			@ref error::end_of_range,
392			@ref parse,
393			@ref range,
394			@ref tuple_rule,
395			@ref squelch.
396			*/
397			template<BOOST_URL_CONSTRAINT(Rule) R>
398			constexpr
399			implementation_defined::range_rule_t<R>
400		18	range_rule(
401			R const& next,
402			std::size_t N = 0,
403			std::size_t M =
404			std::size_t(-1)) noexcept
405			{
406			// If you get a compile error here it
407			// means that your rule does not meet
408			// the type requirements. Please check
409			// the documentation.
410			static_assert(
411			is_rule<R>::value,
412			"Rule requirements not met");
413
414			return implementation_defined::range_rule_t<R>{
415		18	next, N, M};
416			}
417
418			//------------------------------------------------
419
420			namespace implementation_defined {
421			template<class R0, class R1>
422			struct range_rule_t
423			{
424			using value_type =
425			range<typename R0::value_type>;
426
427			system::result<value_type>
428			parse(
429			char const*& it,
430			char const* end) const;
431
432			constexpr
433		1	range_rule_t(
434			R0 const& first,
435			R1 const& next,
436			std::size_t N,
437			std::size_t M) noexcept
438		1	: first_(first)
439		1	, next_(next)
440		1	, N_(N)
441		1	, M_(M)
442			{
443		1	}
444
445			private:
446			R0 const first_;
447			R1 const next_;
448			std::size_t N_;
449			std::size_t M_;
450			};
451			} // implementation_defined
452
453			/** Match a repeating number of elements
454
455			Two rules are used for match. The rule
456			`first` is used for matching the first
457			element, while the `next` rule is used
458			to match every subsequent element.
459			<br>
460			Normally when the rule returns an error,
461			the range ends and the input is rewound to
462			one past the last character that matched
463			successfully. However, if the rule returns
464			the special value @ref error::end_of_range, the
465			input is not rewound. This allows for rules
466			which consume input without producing
467			elements in the range. For example, to
468			relax the grammar for a comma-delimited
469			list by allowing extra commas in between
470			elements.
471
472			@par Value Type
473			@code
474			using value_type = range< typename Rule::value_type >;
475			@endcode
476
477			@par Example
478			Rules are used with the function @ref parse.
479			@code
480			// range = [ token ] *( "," token )
481
482			system::result< range< core::string_view > > rv = parse( "whiskey,tango,foxtrot",
483			range_rule(
484			token_rule( alpha_chars ), // first
485			tuple_rule( // next
486			squelch( delim_rule(',') ),
487			token_rule( alpha_chars ) ) ) );
488			@endcode
489
490			@par BNF
491			@code
492			range = <1>*<1>first
493			/ first <N-1>*<M-1>next
494			@endcode
495
496			@par Specification
497			@li <a href="https://datatracker.ietf.org/doc/html/rfc5234#section-3.6"
498			>3.6. Variable Repetition (rfc5234)</a>
499
500			@param first The rule to use for matching
501			the first element. If this rule returns
502			an error, the range is empty.
503
504			@param next The rule to use for matching
505			each subsequent element. The range extends
506			until this rule returns an error.
507
508			@param N The minimum number of elements for
509			the range to be valid. If omitted, this
510			defaults to zero.
511
512			@param M The maximum number of elements for
513			the range to be valid. If omitted, this
514			defaults to unlimited.
515
516			@return A rule that matches the range.
517
518			@see
519			@ref alpha_chars,
520			@ref delim_rule,
521			@ref error::end_of_range,
522			@ref parse,
523			@ref range,
524			@ref tuple_rule,
525			@ref squelch.
526			*/
527			template<
528			BOOST_URL_CONSTRAINT(Rule) R1,
529			BOOST_URL_CONSTRAINT(Rule) R2>
530			constexpr
531			auto
532		1	range_rule(
533			R1 const& first,
534			R2 const& next,
535			std::size_t N = 0,
536			std::size_t M =
537			std::size_t(-1)) noexcept ->
538			#if 1
539			typename std::enable_if<
540			! std::is_integral<R2>::value,
541			implementation_defined::range_rule_t<R1, R2>>::type
542			#else
543			range_rule_t<R1, R2>
544			#endif
545			{
546			// If you get a compile error here it
547			// means that your rule does not meet
548			// the type requirements. Please check
549			// the documentation.
550			static_assert(
551			is_rule<R1>::value,
552			"Rule requirements not met");
553			static_assert(
554			is_rule<R2>::value,
555			"Rule requirements not met");
556
557			// If you get a compile error here it
558			// means that your rules do not have
559			// the exact same value_type. Please
560			// check the documentation.
561			static_assert(
562			std::is_same<
563			typename R1::value_type,
564			typename R2::value_type>::value,
565			"Rule requirements not met");
566
567			return implementation_defined::range_rule_t<R1, R2>{
568		1	first, next, N, M};
569			}
570
571			} // grammar
572			} // urls
573			} // boost
574
575			#include <boost/url/grammar/impl/range_rule.hpp>
576
577			#endif
578