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