EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-01-18 09:53:29
0001 // 0002 // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com) 0003 // Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com) 0004 // 0005 // Distributed under the Boost Software License, Version 1.0. (See accompanying 0006 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 0007 // 0008 // Official repository: https://github.com/boostorg/url 0009 // 0010 0011 #ifndef BOOST_URL_PARAMS_ENCODED_BASE_HPP 0012 #define BOOST_URL_PARAMS_ENCODED_BASE_HPP 0013 0014 #include <boost/url/detail/config.hpp> 0015 #include <boost/url/ignore_case.hpp> 0016 #include <boost/url/param.hpp> 0017 #include <boost/url/detail/params_iter_impl.hpp> 0018 #include <boost/url/detail/url_impl.hpp> 0019 #include <iosfwd> 0020 0021 namespace boost { 0022 namespace urls { 0023 0024 /** Common functionality for containers 0025 0026 This base class is used by the library 0027 to provide common member functions for 0028 containers. This cannot be instantiated 0029 directly; Instead, use one of the 0030 containers or functions: 0031 0032 @par Containers 0033 @li @ref params_ref 0034 @li @ref params_view 0035 @li @ref params_encoded_ref 0036 @li @ref params_encoded_view 0037 */ 0038 class BOOST_URL_DECL params_encoded_base 0039 { 0040 friend class url_view_base; 0041 friend class params_encoded_ref; 0042 friend class params_encoded_view; 0043 0044 detail::query_ref ref_; 0045 0046 params_encoded_base() = default; 0047 params_encoded_base( 0048 params_encoded_base const&) = default; 0049 params_encoded_base& operator=( 0050 params_encoded_base const&) = default; 0051 params_encoded_base( 0052 detail::query_ref const& ref) noexcept; 0053 0054 public: 0055 /** A Bidirectional iterator to a query parameter 0056 0057 Objects of this type allow iteration 0058 through the parameters in the query. 0059 Strings returned by iterators may 0060 contain percent escapes. 0061 The values returned are read-only; 0062 changes to parameters must be made 0063 through the container instead, if the 0064 container supports modification. 0065 0066 <br> 0067 0068 The strings produced when iterators 0069 are dereferenced refer to the underlying 0070 character buffer. 0071 Ownership is not transferred; the caller 0072 is responsible for ensuring that the 0073 lifetime of the buffer extends until 0074 it is no longer referenced by any 0075 container or iterator. 0076 */ 0077 #ifdef BOOST_URL_DOCS 0078 using iterator = __see_below__; 0079 #else 0080 class iterator; 0081 #endif 0082 0083 /// @copydoc iterator 0084 using const_iterator = iterator; 0085 0086 /** The value type 0087 0088 Values of this type represent parameters 0089 whose strings retain unique ownership by 0090 making a copy. 0091 0092 @par Example 0093 @code 0094 params_encoded_view::value_type qp( *url_view( "?first=John&last=Doe" ).params().find( "first" ) ); 0095 @endcode 0096 0097 @see 0098 @ref param. 0099 */ 0100 using value_type = param; 0101 0102 /** The reference type 0103 0104 This is the type of value returned when 0105 iterators of the view are dereferenced. 0106 0107 @see 0108 @ref param_view. 0109 */ 0110 using reference = param_pct_view; 0111 0112 /// @copydoc reference 0113 using const_reference = param_pct_view; 0114 0115 /** An unsigned integer type to represent sizes. 0116 */ 0117 using size_type = std::size_t; 0118 0119 /** A signed integer type used to represent differences. 0120 */ 0121 using difference_type = std::ptrdiff_t; 0122 0123 //-------------------------------------------- 0124 // 0125 // Observers 0126 // 0127 //-------------------------------------------- 0128 0129 /** Return the maximum number of characters possible 0130 0131 This represents the largest number of 0132 characters that are possible in a path, 0133 not including any null terminator. 0134 0135 @par Exception Safety 0136 Throws nothing. 0137 */ 0138 static 0139 constexpr 0140 std::size_t 0141 max_size() noexcept 0142 { 0143 return BOOST_URL_MAX_SIZE; 0144 } 0145 0146 /** Return the query corresponding to these params 0147 0148 This function returns the query string 0149 referenced by the container. 0150 The returned string may contain 0151 percent escapes. 0152 0153 @par Example 0154 @code 0155 assert( url_view( "?first=John&last=Doe" ).encoded_params().buffer() == "first=John&last=Doe" ); 0156 @endcode 0157 0158 @par Complexity 0159 Constant. 0160 0161 @par Exception Safety 0162 Throws nothing. 0163 0164 @par BNF 0165 @code 0166 query-params = query-param *( "&" query-param ) 0167 query-param = key [ "=" value ] 0168 key = *qpchar 0169 value = *( qpchar / "=" ) 0170 @endcode 0171 0172 @par Specification 0173 @li <a href="https://en.wikipedia.org/wiki/Query_string" 0174 >Query string (Wikipedia)</a> 0175 */ 0176 pct_string_view 0177 buffer() const noexcept; 0178 0179 /** Return true if there are no params 0180 0181 @par Example 0182 @code 0183 assert( ! url_view( "?key=value" ).encoded_params().empty() ); 0184 @endcode 0185 0186 @par Complexity 0187 Constant. 0188 0189 @par Exception Safety 0190 Throws nothing. 0191 */ 0192 bool 0193 empty() const noexcept; 0194 0195 /** Return the number of params 0196 0197 @par Example 0198 @code 0199 assert( url_view( "?key=value").encoded_params().size() == 1 ); 0200 @endcode 0201 0202 @par Complexity 0203 Constant. 0204 0205 @par Exception Safety 0206 Throws nothing. 0207 */ 0208 std::size_t 0209 size() const noexcept; 0210 0211 /** Return an iterator to the beginning 0212 0213 @par Complexity 0214 Linear in the size of the first param. 0215 0216 @par Exception Safety 0217 Throws nothing. 0218 */ 0219 iterator 0220 begin() const noexcept; 0221 0222 /** Return an iterator to the end 0223 0224 @par Complexity 0225 Constant. 0226 0227 @par Exception Safety 0228 Throws nothing. 0229 */ 0230 iterator 0231 end() const noexcept; 0232 0233 //-------------------------------------------- 0234 0235 /** Return true if a matching key exists 0236 0237 This function examines the parameters 0238 in the container to find a match for 0239 the specified key, 0240 which may contain percent escapes. 0241 The comparison is performed as if all 0242 escaped characters were decoded first. 0243 0244 @par Example 0245 @code 0246 assert( url_view( "?first=John&last=Doe" ).encoded_params().contains( "first" ) ); 0247 @endcode 0248 0249 @par Complexity 0250 Linear in `this->buffer().size()`. 0251 0252 @par Exception Safety 0253 Exceptions thrown on invalid input. 0254 0255 @throw system_error 0256 `key` contains an invalid percent-encoding. 0257 0258 @param key The key to match. 0259 By default, a case-sensitive 0260 comparison is used. 0261 0262 @param ic An optional parameter. If 0263 the value @ref ignore_case is passed 0264 here, the comparison is 0265 case-insensitive. 0266 */ 0267 bool 0268 contains( 0269 pct_string_view key, 0270 ignore_case_param ic = {}) const noexcept; 0271 0272 /** Return the number of matching keys 0273 0274 This function examines the parameters 0275 in the container to find the number of 0276 matches for the specified key, 0277 which may contain percent escapes. 0278 The comparison is performed as if all 0279 escaped characters were decoded first. 0280 0281 @par Example 0282 @code 0283 assert( url_view( "?first=John&last=Doe" ).encoded_params().count( "first" ) == 1 ); 0284 @endcode 0285 0286 @par Complexity 0287 Linear in `this->buffer().size()`. 0288 0289 @par Exception Safety 0290 Exceptions thrown on invalid input. 0291 0292 @throw system_error 0293 `key` contains an invalid percent-encoding. 0294 0295 @param key The key to match. 0296 By default, a case-sensitive 0297 comparison is used. 0298 0299 @param ic An optional parameter. If 0300 the value @ref ignore_case is passed 0301 here, the comparison is 0302 case-insensitive. 0303 */ 0304 std::size_t 0305 count( 0306 pct_string_view key, 0307 ignore_case_param ic = {}) const noexcept; 0308 0309 /** Find a matching key 0310 0311 This function examines the parameters 0312 in the container to find a match for 0313 the specified key, 0314 which may contain percent escapes. 0315 The comparison is performed as if all 0316 escaped characters were decoded first. 0317 0318 <br> 0319 0320 The search starts from the first param 0321 and proceeds forward until either the 0322 key is found or the end of the range is 0323 reached, in which case `end()` is 0324 returned. 0325 0326 @par Example 0327 @code 0328 assert( url_view( "?first=John&last=Doe" ).encoded_params().find( "First", ignore_case )->value == "John" ); 0329 @endcode 0330 0331 @par Effects 0332 @code 0333 return this->find( this->begin(), key, ic ); 0334 @endcode 0335 0336 @par Complexity 0337 Linear in `this->buffer().size()`. 0338 0339 @par Exception Safety 0340 Exceptions thrown on invalid input. 0341 0342 @throw system_error 0343 `key` contains an invalid percent-encoding. 0344 0345 @return an iterator to the param 0346 0347 @param key The key to match. 0348 By default, a case-sensitive 0349 comparison is used. 0350 0351 @param ic An optional parameter. If 0352 the value @ref ignore_case is passed 0353 here, the comparison is 0354 case-insensitive. 0355 */ 0356 iterator 0357 find( 0358 pct_string_view key, 0359 ignore_case_param ic = {}) const noexcept; 0360 0361 /** Find a matching key 0362 0363 This function examines the parameters 0364 in the container to find a match for 0365 the specified key, which may contain 0366 percent escapes. 0367 The comparison is performed as if all 0368 escaped characters were decoded first. 0369 0370 <br> 0371 0372 The search starts at `from` 0373 and proceeds forward until either the 0374 key is found or the end of the range is 0375 reached, in which case `end()` is 0376 returned. 0377 0378 @par Example 0379 @code 0380 url_view u( "?First=John&Last=Doe" ); 0381 0382 assert( u.encoded_params().find( "first" ) != u.encoded_params().find( "first", ignore_case ) ); 0383 @endcode 0384 0385 @par Complexity 0386 Linear in `this->buffer().size()`. 0387 0388 @par Exception Safety 0389 Exceptions thrown on invalid input. 0390 0391 @throw system_error 0392 `key` contains an invalid percent-encoding. 0393 0394 @return an iterator to the param 0395 0396 @param from The position to begin the 0397 search from. This can be `end()`. 0398 0399 @param key The key to match. 0400 By default, a case-sensitive 0401 comparison is used. 0402 0403 @param ic An optional parameter. If 0404 the value @ref ignore_case is passed 0405 here, the comparison is 0406 case-insensitive. 0407 */ 0408 iterator 0409 find( 0410 iterator from, 0411 pct_string_view key, 0412 ignore_case_param ic = {}) const noexcept; 0413 0414 /** Find a matching key 0415 0416 This function examines the parameters 0417 in the container to find a match for 0418 the specified key, which may contain 0419 percent escapes. 0420 The comparison is performed as if all 0421 escaped characters were decoded first. 0422 0423 <br> 0424 0425 The search starts from the last param 0426 and proceeds backwards until either the 0427 key is found or the beginning of the 0428 range is reached, in which case `end()` 0429 is returned. 0430 0431 @par Example 0432 @code 0433 assert( url_view( "?first=John&last=Doe" ).encoded_params().find_last( "last" )->value == "Doe" ); 0434 @endcode 0435 0436 @par Complexity 0437 Linear in `this->buffer().size()`. 0438 0439 @par Exception Safety 0440 Exceptions thrown on invalid input. 0441 0442 @throw system_error 0443 `key` contains an invalid percent-encoding. 0444 0445 @return an iterator to the param 0446 0447 @param key The key to match. 0448 By default, a case-sensitive 0449 comparison is used. 0450 0451 @param ic An optional parameter. If 0452 the value @ref ignore_case is passed 0453 here, the comparison is 0454 case-insensitive. 0455 */ 0456 iterator 0457 find_last( 0458 pct_string_view key, 0459 ignore_case_param ic = {}) const noexcept; 0460 0461 /** Find a matching key 0462 0463 This function examines the parameters 0464 in the container to find a match for 0465 the specified key, which may contain 0466 percent escapes. 0467 The comparison is performed as if all 0468 escaped characters were decoded first. 0469 0470 <br> 0471 0472 The search starts prior to `before` 0473 and proceeds backwards until either the 0474 key is found or the beginning of the 0475 range is reached, in which case `end()` 0476 is returned. 0477 0478 @par Example 0479 @code 0480 url_view u( "?First=John&Last=Doe" ); 0481 0482 assert( u.encoded_params().find_last( "last" ) != u.encoded_params().find_last( "last", ignore_case ) ); 0483 @endcode 0484 0485 @par Complexity 0486 Linear in `this->buffer().size()`. 0487 0488 @return an iterator to the param 0489 0490 @param before One past the position 0491 to begin the search from. This can 0492 be `end()`. 0493 0494 @param key The key to match. 0495 By default, a case-sensitive 0496 comparison is used. 0497 0498 @param ic An optional parameter. If 0499 the value @ref ignore_case is passed 0500 here, the comparison is 0501 case-insensitive. 0502 */ 0503 iterator 0504 find_last( 0505 iterator before, 0506 pct_string_view key, 0507 ignore_case_param ic = {}) const noexcept; 0508 0509 private: 0510 detail::params_iter_impl 0511 find_impl( 0512 detail::params_iter_impl, 0513 pct_string_view, 0514 ignore_case_param) const noexcept; 0515 0516 detail::params_iter_impl 0517 find_last_impl( 0518 detail::params_iter_impl, 0519 pct_string_view, 0520 ignore_case_param) const noexcept; 0521 }; 0522 0523 //------------------------------------------------ 0524 0525 /** Format to an output stream 0526 0527 Any percent-escapes are emitted as-is; 0528 no decoding is performed. 0529 0530 @par Complexity 0531 Linear in `ps.buffer().size()`. 0532 0533 @par Effects 0534 @code 0535 return os << ps.buffer(); 0536 @endcode 0537 */ 0538 BOOST_URL_DECL 0539 std::ostream& 0540 operator<<( 0541 std::ostream& os, 0542 params_encoded_base const& qp); 0543 0544 } // urls 0545 } // boost 0546 0547 #include <boost/url/impl/params_encoded_base.hpp> 0548 0549 #endif
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|