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_SEGMENTS_ENCODED_REF_HPP
12			#define BOOST_URL_SEGMENTS_ENCODED_REF_HPP
13
14			#include <boost/url/detail/config.hpp>
15			#include <boost/url/segments_encoded_base.hpp>
16			#include <initializer_list>
17			#include <iterator>
18
19			namespace boost {
20			namespace urls {
21
22			#ifndef BOOST_URL_DOCS
23			class url_base;
24			class segments_encoded_view;
25			#endif
26
27			/** Mutable encoded path segment proxy
28
29			Exposes the percent-encoded segments of a
30			@ref url_base as a bidirectional range that
31			can modify the underlying URL. The proxy uses
32			the URL’s storage directly, so the url must
33			outlive any references.
34
35			@par Example
36			@code
37			url u( "/path/to/file.txt" );
38
39			segments_encoded_ref ps = u.encoded_segments();
40			@endcode
41
42			The strings returned when iterators are
43			dereferenced have type @ref pct_string_view
44			and may contain percent-escapes.
45
46			Reserved characters in inputs are
47			automatically escaped.
48			Escapes in inputs are preserved.
49
50			Exceptions are thrown on invalid inputs.
51
52			@par Iterator Invalidation
53			Changes to the underlying character buffer
54			can invalidate iterators which reference it.
55			Modifications made through the container
56			invalidate some or all iterators:
57			<br>
58
59			@li @ref push_back : Only `end()`.
60
61			@li @ref assign, @ref clear,
62			@ref operator= : All elements.
63
64			@li @ref erase : Erased elements and all
65			elements after (including `end()`).
66
67			@li @ref insert : All elements at or after
68			the insertion point (including `end()`).
69
70			@li @ref replace : Modified
71			elements and all elements
72			after (including `end()`).
73
74			@see
75			@ref segments_encoded_view,
76			@ref segments_view,
77			@ref segments_ref.
78			*/
79			class segments_encoded_ref
80			: public segments_encoded_base
81			{
82			friend class url_base;
83
84			url_base* u_ = nullptr;
85
86			segments_encoded_ref(
87			url_base& u) noexcept;
88
89			public:
90			//--------------------------------------------
91			//
92			// Special Members
93			//
94			//--------------------------------------------
95
96			/** Constructor
97
98			After construction, both views
99			reference the same url. Ownership is not
100			transferred; the caller is responsible
101			for ensuring the lifetime of the url
102			extends until it is no longer
103			referenced.
104
105			@par Postconditions
106			@code
107			&this->url() == &other.url();
108			@endcode
109
110			@par Complexity
111			Constant.
112
113			@par Exception Safety
114			Throws nothing.
115
116			@param other The other view.
117			*/
118			segments_encoded_ref(
119			segments_encoded_ref const& other) = default;
120
121			/** Assignment
122
123			The existing contents are replaced
124			by a copy of the other segments.
125
126			<br>
127			All iterators are invalidated.
128
129			@note
130			None of the character buffers referenced
131			by `other` may overlap the buffer of the
132			underlying url, or else the behavior
133			is undefined.
134
135			@par Effects
136			@code
137			this->assign( other.begin(), other.end() );
138			@endcode
139
140			@par Complexity
141			Linear in `other.buffer().size()`.
142
143			@par Exception Safety
144			Strong guarantee.
145			Calls to allocate may throw.
146
147			@param other The segments to assign.
148			@return A reference to this object.
149			*/
150			BOOST_URL_DECL
151			segments_encoded_ref&
152			operator=(segments_encoded_ref const& other);
153
154			/// @copydoc operator=(segments_encoded_ref const&)
155			BOOST_URL_DECL
156			segments_encoded_ref&
157			operator=(segments_encoded_view const& other);
158
159			/** Assignment
160
161			The existing contents are replaced
162			by a copy of the contents of the
163			initializer list.
164			Reserved characters in the list are
165			automatically escaped.
166			Escapes in the list are preserved.
167
168			<br>
169			All iterators are invalidated.
170
171			@par Example
172			@code
173			url u;
174
175			u.encoded_segments() = {"path", "to", "file.txt"};
176			@endcode
177
178			@par Preconditions
179			None of the character buffers referenced
180			by the list may overlap the character buffer
181			of the underlying url, or else the behavior
182			is undefined.
183
184			@par Effects
185			@code
186			this->assign( init.begin(), init.end() );
187			@endcode
188
189			@par Complexity
190			Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.
191
192			@par Exception Safety
193			Strong guarantee.
194			Calls to allocate may throw.
195			Exceptions thrown on invalid input.
196
197			@throw system_error
198			The list contains an invalid percent-encoding.
199
200			@param init The list of segments to assign.
201			@return A reference to this.
202			*/
203			BOOST_URL_DECL
204			segments_encoded_ref&
205			operator=(std::initializer_list<
206			pct_string_view> init);
207
208			/** Conversion
209
210			@see
211			@ref segments_encoded_view.
212
213			@return A view of the segments.
214			*/
215			BOOST_URL_DECL
216			operator
217			segments_encoded_view() const noexcept;
218
219			//--------------------------------------------
220			//
221			// Observers
222			//
223			//--------------------------------------------
224
225			/** Return the referenced url
226
227			This function returns the url referenced
228			by the view.
229
230			@par Example
231			@code
232			url u( "/path/to/file.txt" );
233
234			assert( &u.encoded_segments().url() == &u );
235			@endcode
236
237			@par Exception Safety
238			Throws nothing.
239
240			@return A reference to the url.
241			*/
242			url_base&
243		9	url() const noexcept
244			{
245		9	return *u_;
246			}
247
248			//--------------------------------------------
249			//
250			// Modifiers
251			//
252			//--------------------------------------------
253
254			/** Clear the contents of the container
255
256			<br>
257			All iterators are invalidated.
258
259			@par Effects
260			@code
261			this->url().set_encoded_path( "" );
262			@endcode
263
264			@par Postconditions
265			@code
266			this->empty() == true
267			@endcode
268
269			@par Complexity
270			Linear in `this->url().encoded_query().size() + this->url().encoded_fragment().size()`.
271
272			@par Exception Safety
273			Throws nothing.
274			*/
275			void
276			clear() noexcept;
277
278			/** Assign segments
279
280			The existing contents are replaced
281			by a copy of the contents of the
282			initializer list.
283			Reserved characters in the list are
284			automatically escaped.
285			Escapes in the list are preserved.
286
287			<br>
288			All iterators are invalidated.
289
290			@note
291			None of the character buffers referenced
292			by the list may overlap the character
293			buffer of the underlying url, or else
294			the behavior is undefined.
295
296			@par Example
297			@code
298			url u;
299
300			u.segments().assign( {"path", "to", "file.txt"} );
301			@endcode
302
303			@par Complexity
304			Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.
305
306			@par Exception Safety
307			Strong guarantee.
308			Calls to allocate may throw.
309			Exceptions thrown on invalid input.
310
311			@throw system_error
312			The list contains an invalid percent-encoding.
313
314			@param init The list of segments to assign.
315			*/
316			BOOST_URL_DECL
317			void
318			assign(std::initializer_list<
319			pct_string_view> init);
320
321			/** Assign segments
322
323			The existing contents are replaced
324			by a copy of the contents of the range.
325			Reserved characters in the range are
326			automatically escaped.
327			Escapes in the range are preserved.
328
329			<br>
330			All iterators are invalidated.
331
332			@note
333			None of the character buffers referenced
334			by the range may overlap the character
335			buffer of the underlying url, or else
336			the behavior is undefined.
337
338			@par Mandates
339			@code
340			std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true
341			@endcode
342
343			@par Complexity
344			Linear in `std::distance( first, last ) + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.
345
346			@par Exception Safety
347			Strong guarantee.
348			Calls to allocate may throw.
349			Exceptions thrown on invalid input.
350
351			@throw system_error
352			The range contains an invalid percent-encoding.
353
354			@param first The first element in the range.
355			@param last One past the last element in the range.
356			*/
357			template<class FwdIt>
358			void
359			assign(FwdIt first, FwdIt last);
360
361			//--------------------------------------------
362
363			/** Insert segments
364
365			This function inserts a segment
366			before the specified position.
367			Reserved characters in the segment are
368			automatically escaped.
369			Escapes in the segment are preserved.
370
371			<br>
372			All iterators that are equal to
373			`before` or come after are invalidated.
374
375			@par Complexity
376			Linear in `s.size() + this->url().encoded_resource().size()`.
377
378			@par Exception Safety
379			Strong guarantee.
380			Calls to allocate may throw.
381			Exceptions thrown on invalid input.
382
383			@throw system_error
384			The segment contains an invalid percent-encoding.
385
386			@return An iterator to the inserted
387			segment.
388
389			@param before An iterator before which
390			the segment is inserted. This may
391			be equal to `end()`.
392
393			@param s The segment to insert.
394			*/
395			BOOST_URL_DECL
396			iterator
397			insert(
398			iterator before,
399			pct_string_view s);
400
401			/** Insert segments
402
403			This function inserts the segments
404			in an initializer list before the
405			specified position.
406			Reserved characters in the list are
407			automatically escaped.
408			Escapes in the list are preserved.
409
410			<br>
411			All iterators that are equal to
412			`before` or come after are invalidated.
413
414			@note
415			None of the character buffers referenced
416			by the list may overlap the character
417			buffer of the underlying url, or else
418			the behavior is undefined.
419
420			@par Example
421			@code
422			url u( "/file.txt" );
423
424			u.encoded_segments().insert( u.encoded_segments().begin(), { "path", "to" } );
425			@endcode
426
427			@par Complexity
428			Linear in `init.size() + this->url().encoded_resource().size()`.
429
430			@par Exception Safety
431			Strong guarantee.
432			Calls to allocate may throw.
433			Exceptions thrown on invalid input.
434
435			@throw system_error
436			The list contains an invalid percent-encoding.
437
438			@return An iterator to the first
439			element inserted, or `before` if
440			`init.size() == 0`.
441
442			@param before An iterator before which
443			the list is inserted. This may
444			be equal to `end()`.
445
446			@param init The list of segments to insert.
447			*/
448			BOOST_URL_DECL
449			iterator
450			insert(
451			iterator before,
452			std::initializer_list<
453			pct_string_view> init);
454
455			/** Insert segments
456
457			This function inserts the segments in
458			a range before the specified position.
459			Reserved characters in the range are
460			automatically escaped.
461			Escapes in the range are preserved.
462
463			<br>
464			All iterators that are equal to
465			`before` or come after are invalidated.
466
467			@note
468			None of the character buffers referenced
469			by the range may overlap the character
470			buffer of the underlying url, or else
471			the behavior is undefined.
472
473			@par Mandates
474			@code
475			std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true
476			@endcode
477
478			@par Complexity
479			Linear in `std::distance( first, last ) + this->url().encoded_resource().size()`.
480
481			@par Exception Safety
482			Strong guarantee.
483			Calls to allocate may throw.
484			Exceptions thrown on invalid input.
485
486			@throw system_error
487			The range contains an invalid percent-encoding.
488
489			@return An iterator to the first
490			segment inserted, or `before` if
491			`init.empty()`.
492
493			@param before An iterator before which
494			the range is inserted. This may
495			be equal to `end()`.
496
497			@param first The first element in the range to insert.
498			@param last One past the last element in the range to insert.
499			*/
500			template<class FwdIt>
501			iterator
502			insert(
503			iterator before,
504			FwdIt first,
505			FwdIt last);
506
507			//--------------------------------------------
508
509			/** Erase segments
510
511			This function removes a segment.
512
513			<br>
514			All iterators that are equal to
515			`pos` or come after are invalidated.
516
517			@par Complexity
518			Linear in `this->url().encoded_resource().size()`.
519
520			@par Exception Safety
521			Throws nothing.
522
523			@return An iterator to one past
524			the removed segment.
525
526			@param pos An iterator to the element.
527			*/
528			iterator
529			erase(
530			iterator pos) noexcept;
531
532			/** Erase segments
533
534			This function removes a range of segments
535			from the container.
536
537			<br>
538			All iterators that are equal to
539			`first` or come after are invalidated.
540
541			@par Complexity
542			Linear in `this->url().encoded_resource().size()`.
543
544			@par Exception Safety
545			Throws nothing.
546
547			@param first The first element in the range to erase.
548			@param last One past the last element in the range to erase.
549			@return An iterator to one past the removed range.
550			*/
551			BOOST_URL_DECL
552			iterator
553			erase(
554			iterator first,
555			iterator last) noexcept;
556
557			//--------------------------------------------
558
559			/** Replace segments
560
561			This function replaces the segment at
562			the specified position.
563			Reserved characters in the string are
564			automatically escaped.
565			Escapes in the string are preserved.
566
567			<br>
568			All iterators that are equal to
569			`pos` or come after are invalidated.
570
571			@par Complexity
572			Linear in `s.size() + this->url().encoded_resouce().size()`.
573
574			@par Exception Safety
575			Strong guarantee.
576			Calls to allocate may throw.
577
578			@return An iterator to the replaced segment.
579
580			@param pos An iterator to the segment.
581
582			@param s The string to assign.
583			*/
584			BOOST_URL_DECL
585			iterator
586			replace(
587			iterator pos,
588			pct_string_view s);
589
590			/** Replace segments
591
592			This function replaces a range of
593			segments with one segment.
594			Reserved characters in the string are
595			automatically escaped.
596			Escapes in the string are preserved.
597
598			<br>
599			All iterators that are equal to
600			`from` or come after are invalidated.
601
602			@par Complexity
603			Linear in `s.size() + this->url().encoded_resouce().size()`.
604
605			@par Exception Safety
606			Strong guarantee.
607			Calls to allocate may throw.
608			Exceptions thrown on invalid input.
609
610			@throw system_error
611			The string contains an invalid percent-encoding.
612
613			@return An iterator to the new segment.
614
615			@param from The first element in the range of segments to replace.
616			@param to One past the last element in the range of segments to replace.
617
618			@param s The string to assign.
619			*/
620			BOOST_URL_DECL
621			iterator
622			replace(
623			iterator from,
624			iterator to,
625			pct_string_view s);
626
627			/** Replace segments
628
629			This function replaces a range of
630			segments with a list of segments in
631			an initializer list.
632			Reserved characters in the list are
633			automatically escaped.
634			Escapes in the list are preserved.
635
636			<br>
637			All iterators that are equal to
638			`from` or come after are invalidated.
639
640			@par Preconditions
641			None of the character buffers referenced
642			by the list may overlap the character
643			buffer of the underlying url, or else
644			the behavior is undefined.
645
646			@par Complexity
647			Linear in `init.size() + this->url().encoded_resouce().size()`.
648
649			@par Exception Safety
650			Strong guarantee.
651			Calls to allocate may throw.
652			Exceptions thrown on invalid input.
653
654			@throw system_error
655			The list contains an invalid percent-encoding.
656
657			@return An iterator to the first
658			segment inserted, or one past `to` if
659			`init.size() == 0`.
660
661			@param from The first element in the range of segments to replace.
662			@param to One past the last element in the range of segments to replace.
663
664			@param init The list of segments to assign.
665			*/
666			BOOST_URL_DECL
667			iterator
668			replace(
669			iterator from,
670			iterator to,
671			std::initializer_list<
672			pct_string_view> init);
673
674			/** Replace segments
675
676			This function replaces a range of
677			segments with annother range of segments.
678			Reserved characters in the new range are
679			automatically escaped.
680			Escapes in the new range are preserved.
681
682			<br>
683			All iterators that are equal to
684			`from` or come after are invalidated.
685
686			@par Preconditions
687			None of the character buffers referenced
688			by the new range may overlap the character
689			buffer of the underlying url, or else
690			the behavior is undefined.
691
692			@par Complexity
693			Linear in `std::distance( first, last ) + this->url().encoded_resouce().size()`.
694
695			@par Exception Safety
696			Strong guarantee.
697			Calls to allocate may throw.
698			Exceptions thrown on invalid input.
699
700			@throw system_error
701			The range contains an invalid percent-encoding.
702
703			@return An iterator to the first
704			segment inserted, or one past `to` if
705			`init.size() == 0`.
706
707			@param from The first element in the range of segments to replace.
708			@param to One past the last element in the range of segments to replace.
709			@param first The first element in the new range of segments.
710			@param last One past the last element in the new range of segments.
711			*/
712			template<class FwdIt>
713			iterator
714			replace(
715			iterator from,
716			iterator to,
717			FwdIt first,
718			FwdIt last);
719
720			//--------------------------------------------
721
722			/** Append a segment
723
724			This function appends a segment to
725			the end of the path.
726			Reserved characters in the string are
727			automatically escaped.
728			Escapes in the string are preserved.
729
730			<br>
731			All end iterators are invalidated.
732
733			@par Postconditions
734			@code
735			this->back() == s
736			@endcode
737
738			@par Exception Safety
739			Strong guarantee.
740			Calls to allocate may throw.
741			Exceptions thrown on invalid input.
742
743			@throw system_error
744			The string contains an invalid percent-encoding.
745
746			@param s The segment to append.
747			*/
748			void
749			push_back(
750			pct_string_view s);
751
752			/** Remove the last segment
753
754			This function removes the last segment
755			from the container.
756
757			<br>
758			Iterators to the last segment as well
759			as all end iterators are invalidated.
760
761			@par Preconditions
762			@code
763			!this->empty()
764			@endcode
765
766			@par Exception Safety
767			Throws nothing.
768			*/
769			void
770			pop_back() noexcept;
771
772			private:
773			template<class FwdIt>
774			iterator
775			insert(
776			iterator before,
777			FwdIt first,
778			FwdIt last,
779			std::input_iterator_tag) = delete;
780
781			template<class FwdIt>
782			iterator
783			insert(
784			iterator before,
785			FwdIt first,
786			FwdIt last,
787			std::forward_iterator_tag);
788			};
789
790			} // urls
791			} // boost
792
793			// This is in <boost/url/url_base.hpp>
794			//
795			// #include <boost/url/impl/segments_encoded_ref.hpp>
796
797			#endif
798