Index/include / boost / url / segments_encoded_base.hpp
Prev Index Next

include/boost/url/segments_encoded_base.hpp

100.0% Lines (1/1) 100.0% Functions (1/1) -% Branches (0/0)
include/boost/url/segments_encoded_base.hpp
Line Hits Source Code
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_BASE_HPP
12 #define BOOST_URL_SEGMENTS_ENCODED_BASE_HPP
13
14 #include <boost/url/detail/config.hpp>
15 #include <boost/url/ignore_case.hpp>
16 #include <boost/url/pct_string_view.hpp>
17 #include <boost/url/detail/url_impl.hpp>
18 #include <iosfwd>
19
20 namespace boost {
21 namespace urls {
22
23 /** Percent-encoded path segment helper base
24
25 Implements the shared encoded-segment
26 algorithms reused by @ref segments_encoded_view
27 and @ref segments_encoded_ref. It is not
28 intended to be instantiated directly; use
29 one of those concrete containers instead.
30
31 @par Containers
32 @li @ref segments_ref
33 @li @ref segments_view
34 @li @ref segments_encoded_ref
35 @li @ref segments_encoded_view
36 */
37 class BOOST_URL_DECL segments_encoded_base
38 {
39 detail::path_ref ref_;
40
41 friend class url_view_base;
42 friend class segments_encoded_ref;
43 friend class segments_encoded_view;
44
45 segments_encoded_base(
46 detail::path_ref const& ref) noexcept;
47 1 segments_encoded_base() = default;
48 segments_encoded_base(
49 segments_encoded_base const&) = default;
50 segments_encoded_base& operator=(
51 segments_encoded_base const&) = default;
52
53 public:
54 /** A Bidirectional iterator to a path segment
55
56 Objects of this type allow iteration
57 through the segments in the path.
58 Strings returned by iterators may
59 contain percent escapes.
60 The values returned are read-only;
61 changes to segments must be made
62 through the container instead, if the
63 container supports modification.
64
65 <br>
66
67 The strings produced when iterators
68 are dereferenced refer to the underlying
69 character buffer.
70 Ownership is not transferred; the caller
71 is responsible for ensuring that the
72 lifetime of the buffer extends until
73 it is no longer referenced by any
74 container or iterator.
75 */
76 class iterator;
77
78 /// @copydoc iterator
79 using const_iterator = iterator;
80
81 /** The value type
82
83 Values of this type represent a segment
84 where unique ownership is retained by
85 making a copy.
86
87 @par Example
88 @code
89 segments_encoded_base::value_type ps( url_view( "/path/to/file.txt" ).encoded_segments().back() );
90 @endcode
91 */
92 using value_type = std::string;
93
94 /** The reference type
95
96 This is the type of value returned when
97 iterators of the view are dereferenced.
98 */
99 using reference = pct_string_view;
100
101 /// @copydoc reference
102 using const_reference = pct_string_view;
103
104 /** An unsigned integer type used to represent size.
105 */
106 using size_type = std::size_t;
107
108 /** A signed integer type used to represent differences.
109 */
110 using difference_type = std::ptrdiff_t;
111
112 //--------------------------------------------
113 //
114 // Observers
115 //
116 //--------------------------------------------
117
118 /** Return the maximum number of characters possible
119
120 This represents the largest number of
121 characters that are possible in a path,
122 not including any null terminator.
123
124 @par Exception Safety
125 Throws nothing.
126
127 @return The maximum number of characters possible.
128 */
129 static
130 constexpr
131 std::size_t
132 max_size() noexcept
133 {
134 return BOOST_URL_MAX_SIZE;
135 }
136
137 /** Return the referenced character buffer.
138
139 This function returns the character
140 buffer referenced by the view.
141 The returned string may contain
142 percent escapes.
143
144 @par Example
145 @code
146 assert( url_view( "/path/to/file.txt" ).encoded_segments().buffer() == "/path/to/file.txt" );
147 @endcode
148
149 @par Complexity
150 Constant.
151
152 @par Exception Safety
153 Throws nothing.
154
155 @return A string view of the buffer.
156 */
157 pct_string_view
158 buffer() const noexcept;
159
160 /** Returns true if this references an absolute path.
161
162 Absolute paths always start with a
163 forward slash ('/').
164
165 @par Example
166 @code
167 assert( url_view( "/path/to/file.txt" ).encoded_segments().is_absolute() == true );
168 @endcode
169
170 @par Complexity
171 Constant.
172
173 @par Exception Safety
174 Throws nothing.
175
176 @return `true` if the path is absolute, otherwise `false`.
177 */
178 bool
179 is_absolute() const noexcept;
180
181 /** Return true if there are no segments
182
183 @par Example
184 @code
185 assert( ! url_view( "/index.htm" ).encoded_segments().empty() );
186 @endcode
187
188 @par Complexity
189 Constant.
190
191 @par Exception Safety
192 Throws nothing.
193
194 @return `true` if there are no segments, otherwise `false`.
195 */
196 bool
197 empty() const noexcept;
198
199 /** Return the number of segments
200
201 @par Example
202 @code
203 assert( url_view( "/path/to/file.txt" ).encoded_segments().size() == 3 );
204 @endcode
205
206 @par Complexity
207 Constant.
208
209 @par Exception Safety
210 Throws nothing.
211
212 @return The number of segments.
213 */
214 std::size_t
215 size() const noexcept;
216
217 /** Return the first segment
218
219 This function returns a string with the
220 first segment of the path without any
221 leading or trailing '/' separators.
222 The returned string may contain
223 percent escapes.
224
225 @par Preconditions
226 @code
227 this->empty() == false
228 @endcode
229
230 @par Effects
231 @code
232 return *begin();
233 @endcode
234
235 @par Example
236 @code
237 assert( url_view( "/path/to/file.txt" ).encoded_segments().front() == "path" );
238 @endcode
239
240 @par Complexity
241 Constant.
242
243 @par Exception Safety
244 Throws nothing.
245
246 @return The first segment.
247 */
248 pct_string_view
249 front() const noexcept;
250
251 /** Return the last segment
252
253 This function returns a string with the
254 last segment of the path without any
255 leading or trailing '/' separators.
256 The returned string may contain
257 percent escapes.
258
259 @par Preconditions
260 @code
261 this->empty() == false
262 @endcode
263
264 @par Example
265 @code
266 assert( url_view( "/path/to/file.txt" ).encoded_segments().back() == "file.txt" );
267 @endcode
268
269 @par Preconditions
270 @code
271 this->empty() == false
272 @endcode
273
274 @par Effects
275 @code
276 return *--end();
277 @endcode
278
279 @par Complexity
280 Constant.
281
282 @par Exception Safety
283 Throws nothing.
284
285 @return The last segment.
286 */
287 pct_string_view
288 back() const noexcept;
289
290 /** Return an iterator to the beginning
291
292 @par Complexity
293 Linear in `this->front().size()` or
294 constant if `this->empty()`.
295
296 @par Exception Safety
297 Throws nothing.
298
299 @return An iterator to the first segment.
300 */
301 iterator
302 begin() const noexcept;
303
304 /** Return an iterator to the end
305
306 @par Complexity
307 Constant.
308
309 @par Exception Safety
310 Throws nothing.
311
312 @return An iterator to one past the last segment.
313 */
314 iterator
315 end() const noexcept;
316 };
317
318 //------------------------------------------------
319
320 /** Format to an output stream
321
322 Any percent-escapes are emitted as-is;
323 no decoding is performed.
324
325 @par Complexity
326 Linear in `ps.buffer().size()`.
327
328 @par Effects
329 @code
330 return os << ps.buffer();
331 @endcode
332
333 @param os The output stream to write to.
334 @param ps The object to format.
335 @return A reference to the output stream.
336 */
337 BOOST_URL_DECL
338 std::ostream&
339 operator<<(
340 std::ostream& os,
341 segments_encoded_base const& ps);
342
343 } // urls
344 } // boost
345
346 #include <boost/url/impl/segments_encoded_base.hpp>
347
348 #endif
349