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