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