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/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			range&
225			operator=(range&&) noexcept;
226
227			/** Assignment
228
229			The copy references the same
230			underlying character buffer.
231			Ownership is not transferred; the
232			caller is responsible for ensuring
233			that the lifetime of the buffer
234			extends until it is no longer
235			referenced.
236
237			@par Exception Safety
238			Throws nothing.
239			*/
240			range&
241			operator=(range const&) noexcept;
242
243			/** Return an iterator to the beginning
244			*/
245			iterator begin() const noexcept;
246
247			/** Return an iterator to the end
248			*/
249			iterator end() const noexcept;
250
251			/** Return true if the range is empty
252			*/
253			bool
254		11	empty() const noexcept
255			{
256		11	return n_ == 0;
257			}
258
259			/** Return the number of elements in the range
260			*/
261			std::size_t
262		34	size() const noexcept
263			{
264		34	return n_;
265			}
266
267			/** Return the matching part of the string
268			*/
269			core::string_view
270		19	string() const noexcept
271			{
272		19	return s_;
273			}
274			};
275
276			//------------------------------------------------
277
278			#ifndef BOOST_URL_DOCS
279			namespace implementation_defined {
280			template<
281			class R0,
282			class R1 = void>
283			struct range_rule_t;
284			}
285			#endif
286
287			//------------------------------------------------
288
289			/** Match a repeating number of elements
290
291			Elements are matched using the passed rule.
292			<br>
293			Normally when the rule returns an error,
294			the range ends and the input is rewound to
295			one past the last character that matched
296			successfully. However, if the rule returns
297			the special value @ref error::end_of_range, the
298			input is not rewound. This allows for rules
299			which consume input without producing
300			elements in the range. For example, to
301			relax the grammar for a comma-delimited
302			list by allowing extra commas in between
303			elements.
304
305			@par Value Type
306			@code
307			using value_type = range< typename Rule::value_type >;
308			@endcode
309
310			@par Example
311			Rules are used with the function @ref parse.
312			@code
313			// range = 1*( ";" token )
314
315			system::result< range<core::string_view> > rv = parse( ";alpha;xray;charlie",
316			range_rule(
317			tuple_rule(
318			squelch( delim_rule( ';' ) ),
319			token_rule( alpha_chars ) ),
320			1 ) );
321			@endcode
322
323			@par BNF
324			@code
325			range = <N>*<M>next
326			@endcode
327
328			@par Specification
329			@li <a href="https://datatracker.ietf.org/doc/html/rfc5234#section-3.6"
330			>3.6. Variable Repetition (rfc5234)</a>
331
332			@param next The rule to use for matching
333			each element. The range extends until this
334			rule returns an error.
335
336			@param N The minimum number of elements for
337			the range to be valid. If omitted, this
338			defaults to zero.
339
340			@param M The maximum number of elements for
341			the range to be valid. If omitted, this
342			defaults to unlimited.
343
344			@see
345			@ref alpha_chars,
346			@ref delim_rule,
347			@ref error::end_of_range,
348			@ref parse,
349			@ref range,
350			@ref tuple_rule,
351			@ref squelch.
352			*/
353			#ifdef BOOST_URL_DOCS
354			template<class Rule>
355			constexpr
356			__implementation_defined__
357			range_rule(
358			Rule next,
359			std::size_t N = 0,
360			std::size_t M =
361			std::size_t(-1)) noexcept;
362			#else
363			namespace implementation_defined {
364			template<class R>
365			struct range_rule_t<R>
366			{
367			using value_type =
368			range<typename R::value_type>;
369
370			system::result<value_type>
371			parse(
372			char const*& it,
373			char const* end) const;
374
375			constexpr
376		18	range_rule_t(
377			R const& next,
378			std::size_t N,
379			std::size_t M) noexcept
380		18	: next_(next)
381		18	, N_(N)
382		18	, M_(M)
383			{
384		18	}
385
386			private:
387			R const next_;
388			std::size_t N_;
389			std::size_t M_;
390			};
391			} // implementation_defined
392
393			/** Match a repeating number of elements
394
395			Elements are matched using the passed rule.
396			<br>
397			Normally when the rule returns an error,
398			the range ends and the input is rewound to
399			one past the last character that matched
400			successfully. However, if the rule returns
401			the special value @ref error::end_of_range, the
402			input is not rewound. This allows for rules
403			which consume input without producing
404			elements in the range. For example, to
405			relax the grammar for a comma-delimited
406			list by allowing extra commas in between
407			elements.
408
409			@par Value Type
410			@code
411			using value_type = range< typename Rule::value_type >;
412			@endcode
413
414			@par Example
415			Rules are used with the function @ref parse.
416			@code
417			// range = 1*( ";" token )
418
419			system::result< range<core::string_view> > rv = parse( ";alpha;xray;charlie",
420			range_rule(
421			tuple_rule(
422			squelch( delim_rule( ';' ) ),
423			token_rule( alpha_chars ) ),
424			1 ) );
425			@endcode
426
427			@par BNF
428			@code
429			range = <N>*<M>next
430			@endcode
431
432			@par Specification
433			@li <a href="https://datatracker.ietf.org/doc/html/rfc5234#section-3.6"
434			>3.6. Variable Repetition (rfc5234)</a>
435
436			@param next The rule to use for matching
437			each element. The range extends until this
438			rule returns an error.
439
440			@param N The minimum number of elements for
441			the range to be valid. If omitted, this
442			defaults to zero.
443
444			@param M The maximum number of elements for
445			the range to be valid. If omitted, this
446			defaults to unlimited.
447
448			@see
449			@ref alpha_chars,
450			@ref delim_rule,
451			@ref error::end_of_range,
452			@ref parse,
453			@ref range,
454			@ref tuple_rule,
455			@ref squelch.
456			*/
457			template<class Rule>
458			constexpr
459			implementation_defined::range_rule_t<Rule>
460		18	range_rule(
461			Rule const& next,
462			std::size_t N = 0,
463			std::size_t M =
464			std::size_t(-1)) noexcept
465			{
466			// If you get a compile error here it
467			// means that your rule does not meet
468			// the type requirements. Please check
469			// the documentation.
470			static_assert(
471			is_rule<Rule>::value,
472			"Rule requirements not met");
473
474			return implementation_defined::range_rule_t<Rule>{
475		18	next, N, M};
476			}
477			#endif
478
479			//------------------------------------------------
480
481			/** Match a repeating number of elements
482
483			Two rules are used for match. The rule
484			`first` is used for matching the first
485			element, while the `next` rule is used
486			to match every subsequent element.
487			<br>
488			Normally when the rule returns an error,
489			the range ends and the input is rewound to
490			one past the last character that matched
491			successfully. However, if the rule returns
492			the special value @ref error::end_of_range, the
493			input is not rewound. This allows for rules
494			which consume input without producing
495			elements in the range. For example, to
496			relax the grammar for a comma-delimited
497			list by allowing extra commas in between
498			elements.
499
500			@par Value Type
501			@code
502			using value_type = range< typename Rule::value_type >;
503			@endcode
504
505			@par Example
506			Rules are used with the function @ref parse.
507			@code
508			// range = [ token ] *( "," token )
509
510			system::result< range< core::string_view > > rv = parse( "whiskey,tango,foxtrot",
511			range_rule(
512			token_rule( alpha_chars ), // first
513			tuple_rule( // next
514			squelch( delim_rule(',') ),
515			token_rule( alpha_chars ) ) ) );
516			@endcode
517
518			@par BNF
519			@code
520			range = <1>*<1>first
521			/ first <N-1>*<M-1>next
522			@endcode
523
524			@par Specification
525			@li <a href="https://datatracker.ietf.org/doc/html/rfc5234#section-3.6"
526			>3.6. Variable Repetition (rfc5234)</a>
527
528			@param first The rule to use for matching
529			the first element. If this rule returns
530			an error, the range is empty.
531
532			@param next The rule to use for matching
533			each subsequent element. The range extends
534			until this rule returns an error.
535
536			@param N The minimum number of elements for
537			the range to be valid. If omitted, this
538			defaults to zero.
539
540			@param M The maximum number of elements for
541			the range to be valid. If omitted, this
542			defaults to unlimited.
543
544			@see
545			@ref alpha_chars,
546			@ref delim_rule,
547			@ref error::end_of_range,
548			@ref parse,
549			@ref range,
550			@ref tuple_rule,
551			@ref squelch.
552			*/
553			#ifdef BOOST_URL_DOCS
554			template<
555			class Rule1, class Rule2>
556			constexpr
557			__implementation_defined__
558			range_rule(
559			Rule1 first,
560			Rule2 next,
561			std::size_t N = 0,
562			std::size_t M =
563			std::size_t(-1)) noexcept;
564			#else
565			namespace implementation_defined {
566			template<class R0, class R1>
567			struct range_rule_t
568			{
569			using value_type =
570			range<typename R0::value_type>;
571
572			system::result<value_type>
573			parse(
574			char const*& it,
575			char const* end) const;
576
577			constexpr
578		1	range_rule_t(
579			R0 const& first,
580			R1 const& next,
581			std::size_t N,
582			std::size_t M) noexcept
583		1	: first_(first)
584		1	, next_(next)
585		1	, N_(N)
586		1	, M_(M)
587			{
588		1	}
589
590			private:
591			R0 const first_;
592			R1 const next_;
593			std::size_t N_;
594			std::size_t M_;
595			};
596			} // implementation_defined
597
598			/** Match a repeating number of elements
599
600			Two rules are used for match. The rule
601			`first` is used for matching the first
602			element, while the `next` rule is used
603			to match every subsequent element.
604			<br>
605			Normally when the rule returns an error,
606			the range ends and the input is rewound to
607			one past the last character that matched
608			successfully. However, if the rule returns
609			the special value @ref error::end_of_range, the
610			input is not rewound. This allows for rules
611			which consume input without producing
612			elements in the range. For example, to
613			relax the grammar for a comma-delimited
614			list by allowing extra commas in between
615			elements.
616
617			@par Value Type
618			@code
619			using value_type = range< typename Rule::value_type >;
620			@endcode
621
622			@par Example
623			Rules are used with the function @ref parse.
624			@code
625			// range = [ token ] *( "," token )
626
627			system::result< range< core::string_view > > rv = parse( "whiskey,tango,foxtrot",
628			range_rule(
629			token_rule( alpha_chars ), // first
630			tuple_rule( // next
631			squelch( delim_rule(',') ),
632			token_rule( alpha_chars ) ) ) );
633			@endcode
634
635			@par BNF
636			@code
637			range = <1>*<1>first
638			/ first <N-1>*<M-1>next
639			@endcode
640
641			@par Specification
642			@li <a href="https://datatracker.ietf.org/doc/html/rfc5234#section-3.6"
643			>3.6. Variable Repetition (rfc5234)</a>
644
645			@param first The rule to use for matching
646			the first element. If this rule returns
647			an error, the range is empty.
648
649			@param next The rule to use for matching
650			each subsequent element. The range extends
651			until this rule returns an error.
652
653			@param N The minimum number of elements for
654			the range to be valid. If omitted, this
655			defaults to zero.
656
657			@param M The maximum number of elements for
658			the range to be valid. If omitted, this
659			defaults to unlimited.
660
661			@see
662			@ref alpha_chars,
663			@ref delim_rule,
664			@ref error::end_of_range,
665			@ref parse,
666			@ref range,
667			@ref tuple_rule,
668			@ref squelch.
669			*/
670			template<
671			class Rule1, class Rule2>
672			constexpr
673			auto
674		1	range_rule(
675			Rule1 const& first,
676			Rule2 const& next,
677			std::size_t N = 0,
678			std::size_t M =
679			std::size_t(-1)) noexcept ->
680			#if 1
681			typename std::enable_if<
682			! std::is_integral<Rule2>::value,
683			implementation_defined::range_rule_t<Rule1, Rule2>>::type
684			#else
685			range_rule_t<Rule1, Rule2>
686			#endif
687			{
688			// If you get a compile error here it
689			// means that your rule does not meet
690			// the type requirements. Please check
691			// the documentation.
692			static_assert(
693			is_rule<Rule1>::value,
694			"Rule requirements not met");
695			static_assert(
696			is_rule<Rule2>::value,
697			"Rule requirements not met");
698
699			// If you get a compile error here it
700			// means that your rules do not have
701			// the exact same value_type. Please
702			// check the documentation.
703			static_assert(
704			std::is_same<
705			typename Rule1::value_type,
706			typename Rule2::value_type>::value,
707			"Rule requirements not met");
708
709			return implementation_defined::range_rule_t<Rule1, Rule2>{
710		1	first, next, N, M};
711			}
712			#endif
713
714			} // grammar
715			} // urls
716			} // boost
717
718			#include <boost/url/grammar/impl/range_rule.hpp>
719
720			#endif
721