LCOV - code coverage report
Current view: top level - boost/url/params_encoded_ref.hpp (source / functions) Coverage Total Hit
Test: coverage_filtered.info Lines: 100.0 % 2 2
Test Date: 2024-08-19 20:08:54 Functions: 100.0 % 1 1

            Line data    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_PARAMS_ENCODED_REF_HPP
      12              : #define BOOST_URL_PARAMS_ENCODED_REF_HPP
      13              : 
      14              : #include <boost/url/detail/config.hpp>
      15              : #include <boost/url/ignore_case.hpp>
      16              : #include <boost/url/params_encoded_view.hpp>
      17              : #include <initializer_list>
      18              : 
      19              : namespace boost {
      20              : namespace urls {
      21              : 
      22              : #ifndef BOOST_URL_DOCS
      23              : class url_base;
      24              : class params_encoded_view;
      25              : #endif
      26              : 
      27              : /** A view representing query parameters in a URL
      28              : 
      29              :     Objects of this type are used to interpret
      30              :     the query parameters as a bidirectional view
      31              :     of key value pairs.
      32              : 
      33              :     The view does not retain ownership of the
      34              :     elements and instead references the original
      35              :     url. The caller is responsible for ensuring
      36              :     that the lifetime of the referenced url
      37              :     extends until it is no longer referenced.
      38              : 
      39              :     The view is modifiable; calling non-const
      40              :     members causes changes to the referenced
      41              :     url.
      42              : 
      43              :     @par Example
      44              :     @code
      45              :     url u( "?first=John&last=Doe" );
      46              : 
      47              :     params_encoded_ref p = u.encoded_params();
      48              :     @endcode
      49              : 
      50              :     Strings produced when elements are returned
      51              :     have type @ref param_pct_view and represent
      52              :     encoded strings. Strings passed to member
      53              :     functions may contain percent escapes, and
      54              :     throw exceptions on invalid inputs.
      55              : 
      56              :     @par Iterator Invalidation
      57              :     Changes to the underlying character buffer
      58              :     can invalidate iterators which reference it.
      59              :     Modifications made through the container
      60              :     invalidate some iterators to the underlying
      61              :     character buffer:
      62              :     @li @ref append : Only `end()`.
      63              :     @li @ref assign, @ref clear,
      64              :         `operator=` : All params.
      65              :     @li @ref erase : Erased params and all
      66              :         params after (including `end()`).
      67              :     @li @ref insert : All params at or after
      68              :         the insertion point (including `end()`).
      69              :     @li @ref replace, @ref set : Modified
      70              :         params and all params
      71              :         after (including `end()`).
      72              : */
      73              : class BOOST_URL_DECL params_encoded_ref
      74              :     : public params_encoded_base
      75              : {
      76              :     friend class url_base;
      77              : 
      78              :     url_base* u_ = nullptr;
      79              : 
      80              :     params_encoded_ref(
      81              :         url_base& u) noexcept;
      82              : 
      83              : public:
      84              :     //--------------------------------------------
      85              :     //
      86              :     // Special Members
      87              :     //
      88              :     //--------------------------------------------
      89              : 
      90              :     /** Constructor
      91              : 
      92              :         After construction, both views
      93              :         reference the same url. Ownership is not
      94              :         transferred; the caller is responsible
      95              :         for ensuring the lifetime of the url
      96              :         extends until it is no longer
      97              :         referenced.
      98              : 
      99              :         @par Postconditions
     100              :         @code
     101              :         &this->url() == &other.url();
     102              :         @endcode
     103              : 
     104              :         @par Complexity
     105              :         Constant.
     106              : 
     107              :         @par Exception Safety
     108              :         Throws nothing.
     109              : 
     110              :         @param other The other view.
     111              :     */
     112              :     params_encoded_ref(
     113              :         params_encoded_ref const& other) = default;
     114              : 
     115              :     /** Assignment
     116              : 
     117              :         The previous contents of this are
     118              :         replaced by the contents of `other.
     119              : 
     120              :         <br>
     121              :         All iterators are invalidated.
     122              : 
     123              :         @note
     124              :         The strings referenced by `other`
     125              :         must not come from the underlying url,
     126              :         or else the behavior is undefined.
     127              : 
     128              :         @par Effects
     129              :         @code
     130              :         this->assign( other.begin(), other.end() );
     131              :         @endcode
     132              : 
     133              :         @par Complexity
     134              :         Linear in `other.buffer().size()`.
     135              : 
     136              :         @par Exception Safety
     137              :         Strong guarantee.
     138              :         Calls to allocate may throw.
     139              : 
     140              :         @param other The params to assign.
     141              :     */
     142              :     params_encoded_ref&
     143              :     operator=(
     144              :         params_encoded_ref const& other);
     145              : 
     146              :     /** Assignment
     147              : 
     148              :         After assignment, the previous contents
     149              :         of the query parameters are replaced by
     150              :         the contents of the initializer-list.
     151              : 
     152              :         <br>
     153              :         All iterators are invalidated.
     154              : 
     155              :         @par Preconditions
     156              :         None of character buffers referenced by
     157              :         `init` may overlap the character buffer of
     158              :         the underlying url, or else the behavior
     159              :         is undefined.
     160              : 
     161              :         @par Effects
     162              :         @code
     163              :         this->assign( init.begin(), init.end() );
     164              :         @endcode
     165              : 
     166              :         @par Complexity
     167              :         Linear in `init.size()`.
     168              : 
     169              :         @par Exception Safety
     170              :         Strong guarantee.
     171              :         Calls to allocate may throw.
     172              :         Exceptions thrown on invalid input.
     173              : 
     174              :         @throw system_error
     175              :         `init` contains an invalid percent-encoding.
     176              : 
     177              :         @param init The list of params to assign.
     178              :     */
     179              :     params_encoded_ref&
     180              :     operator=(std::initializer_list<
     181              :         param_pct_view> init);
     182              : 
     183              :     /** Conversion
     184              : 
     185              :         @par Complexity
     186              :         Constant.
     187              : 
     188              :         @par Exception Safety
     189              :         Throws nothing.
     190              :     */
     191              :     operator
     192              :     params_encoded_view() const noexcept;
     193              : 
     194              :     //--------------------------------------------
     195              :     //
     196              :     // Observers
     197              :     //
     198              :     //--------------------------------------------
     199              : 
     200              :     /** Return the referenced url
     201              : 
     202              :         This function returns the url referenced
     203              :         by the view.
     204              : 
     205              :         @par Example
     206              :         @code
     207              :         url u( "?key=value" );
     208              : 
     209              :         assert( &u.encoded_params().url() == &u );
     210              :         @endcode
     211              : 
     212              :         @par Exception Safety
     213              :         @code
     214              :         Throws nothing.
     215              :         @endcode
     216              :     */
     217              :     url_base&
     218            7 :     url() const noexcept
     219              :     {
     220            7 :         return *u_;
     221              :     }
     222              : 
     223              :     //--------------------------------------------
     224              :     //
     225              :     // Modifiers
     226              :     //
     227              :     //--------------------------------------------
     228              : 
     229              :     /** Clear the contents of the container
     230              : 
     231              :         <br>
     232              :         All iterators are invalidated.
     233              : 
     234              :         @par Effects
     235              :         @code
     236              :         this->url().remove_query();
     237              :         @endcode
     238              : 
     239              :         @par Postconditions
     240              :         @code
     241              :         this->empty() == true && this->url().has_query() == false
     242              :         @endcode
     243              : 
     244              :         @par Complexity
     245              :         Constant.
     246              : 
     247              :         @par Exception Safety
     248              :         Throws nothing.
     249              :     */
     250              :     void
     251              :     clear() noexcept;
     252              : 
     253              :     //--------------------------------------------
     254              : 
     255              :     /** Assign params
     256              : 
     257              :         This function replaces the entire
     258              :         contents of the view with the params
     259              :         in the <em>initializer-list</em>.
     260              : 
     261              :         <br>
     262              :         All iterators are invalidated.
     263              : 
     264              :         @note
     265              :         The strings referenced by the inputs
     266              :         must not come from the underlying url,
     267              :         or else the behavior is undefined.
     268              : 
     269              :         @par Example
     270              :         @code
     271              :         url u;
     272              : 
     273              :         u.encoded_params().assign({ { "first", "John" }, { "last", "Doe" } });
     274              :         @endcode
     275              : 
     276              :         @par Complexity
     277              :         Linear in `init.size()`.
     278              : 
     279              :         @par Exception Safety
     280              :         Strong guarantee.
     281              :         Calls to allocate may throw.
     282              :         Exceptions thrown on invalid input.
     283              : 
     284              :         @throw system_error
     285              :         `init` contains an invalid percent-encoding.
     286              : 
     287              :         @param init The list of params to assign.
     288              :     */
     289              :     void
     290              :     assign(
     291              :         std::initializer_list<
     292              :             param_pct_view> init);
     293              : 
     294              :     /** Assign params
     295              : 
     296              :         This function replaces the entire
     297              :         contents of the view with the params
     298              :         in the range.
     299              : 
     300              :         <br>
     301              :         All iterators are invalidated.
     302              : 
     303              :         @note
     304              :         The strings referenced by the inputs
     305              :         must not come from the underlying url,
     306              :         or else the behavior is undefined.
     307              : 
     308              :         @par Mandates
     309              :         @code
     310              :         std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true
     311              :         @endcode
     312              : 
     313              :         @par Complexity
     314              :         Linear in the size of the range.
     315              : 
     316              :         @par Exception Safety
     317              :         Strong guarantee.
     318              :         Calls to allocate may throw.
     319              :         Exceptions thrown on invalid input.
     320              : 
     321              :         @throw system_error
     322              :         The range contains an invalid percent-encoding.
     323              : 
     324              :         @param first, last The range of params
     325              :         to assign.
     326              :     */
     327              :     template<class FwdIt>
     328              :     void
     329              :     assign(FwdIt first, FwdIt last);
     330              : 
     331              :     //--------------------------------------------
     332              : 
     333              :     /** Append params
     334              : 
     335              :         This function appends a param to the view.
     336              : 
     337              :         <br>
     338              :         The `end()` iterator is invalidated.
     339              : 
     340              :         @par Example
     341              :         @code
     342              :         url u;
     343              : 
     344              :         u.encoded_params().append( { "first", "John" } );
     345              :         @endcode
     346              : 
     347              :         @par Complexity
     348              :         Linear in `this->url().encoded_query().size()`.
     349              : 
     350              :         @par Exception Safety
     351              :         Strong guarantee.
     352              :         Calls to allocate may throw.
     353              :         Exceptions thrown on invalid input.
     354              : 
     355              :         @throw system_error
     356              :         `p` contains an invalid percent-encoding.
     357              : 
     358              :         @return An iterator to the new element.
     359              : 
     360              :         @param p The param to append.
     361              :     */
     362              :     iterator
     363              :     append(
     364              :         param_pct_view const& p);
     365              : 
     366              :     /** Append params
     367              : 
     368              :         This function appends the params in
     369              :         an <em>initializer-list</em> to the view.
     370              : 
     371              :         <br>
     372              :         The `end()` iterator is invalidated.
     373              : 
     374              :         @par Example
     375              :         @code
     376              :         url u;
     377              : 
     378              :         u.encoded_params().append({ {"first", "John"}, {"last", "Doe"} });
     379              :         @endcode
     380              : 
     381              :         @par Complexity
     382              :         Linear in `this->url().encoded_query().size()`.
     383              : 
     384              :         @par Exception Safety
     385              :         Strong guarantee.
     386              :         Calls to allocate may throw.
     387              :         Exceptions thrown on invalid input.
     388              : 
     389              :         @throw system_error
     390              :         `init` contains an invalid percent-encoding.
     391              : 
     392              :         @return An iterator to the first new element.
     393              : 
     394              :         @param init The list of params to append.
     395              :     */
     396              :     iterator
     397              :     append(
     398              :         std::initializer_list<
     399              :             param_pct_view> init);
     400              : 
     401              :     /** Append params
     402              : 
     403              :         This function appends a range of params
     404              :         to the view.
     405              : 
     406              :         <br>
     407              :         The `end()` iterator is invalidated.
     408              : 
     409              :         @note
     410              :         The strings referenced by the inputs
     411              :         must not come from the underlying url,
     412              :         or else the behavior is undefined.
     413              : 
     414              :         @par Mandates
     415              :         @code
     416              :         std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true
     417              :         @endcode
     418              : 
     419              :         @par Complexity
     420              :         Linear in `this->url().encoded_query().size()`.
     421              : 
     422              :         @par Exception Safety
     423              :         Strong guarantee.
     424              :         Calls to allocate may throw.
     425              :         Exceptions thrown on invalid input.
     426              : 
     427              :         @throw system_error
     428              :         The range contains an invalid percent-encoding.
     429              : 
     430              :         @return An iterator to the first new element.
     431              : 
     432              :         @param first, last The range of params
     433              :         to append.
     434              :     */
     435              :     template<class FwdIt>
     436              :     iterator
     437              :     append(
     438              :         FwdIt first, FwdIt last);
     439              : 
     440              :     //--------------------------------------------
     441              : 
     442              :     /** Insert params
     443              : 
     444              :         This function inserts a param
     445              :         before the specified position.
     446              : 
     447              :         <br>
     448              :         All iterators that are equal to
     449              :         `before` or come after are invalidated.
     450              : 
     451              :         @par Complexity
     452              :         Linear in `this->url().encoded_query().size()`.
     453              : 
     454              :         @par Exception Safety
     455              :         Strong guarantee.
     456              :         Calls to allocate may throw.
     457              :         Exceptions thrown on invalid input.
     458              : 
     459              :         @throw system_error
     460              :         `p` contains an invalid percent-encoding.
     461              : 
     462              :         @return An iterator to the inserted
     463              :         element.
     464              : 
     465              :         @param before An iterator before which
     466              :         the param is inserted. This may
     467              :         be equal to `end()`.
     468              : 
     469              :         @param p The param to insert.
     470              :     */
     471              :     iterator
     472              :     insert(
     473              :         iterator before,
     474              :         param_pct_view const& p);
     475              : 
     476              :     /** Insert params
     477              : 
     478              :         This function inserts the params in
     479              :         an <em>initializer-list</em> before
     480              :         the specified position.
     481              : 
     482              :         <br>
     483              :         All iterators that are equal to
     484              :         `before` or come after are invalidated.
     485              : 
     486              :         @note
     487              :         The strings referenced by the inputs
     488              :         must not come from the underlying url,
     489              :         or else the behavior is undefined.
     490              : 
     491              :         @par Complexity
     492              :         Linear in `this->url().encoded_query().size()`.
     493              : 
     494              :         @par Exception Safety
     495              :         Strong guarantee.
     496              :         Calls to allocate may throw.
     497              :         Exceptions thrown on invalid input.
     498              : 
     499              :         @throw system_error
     500              :         `init` contains an invalid percent-encoding.
     501              : 
     502              :         @return An iterator to the first
     503              :         element inserted, or `before` if
     504              :         `init.size() == 0`.
     505              : 
     506              :         @param before An iterator before which
     507              :         the element is inserted. This may
     508              :         be equal to `end()`.
     509              : 
     510              :         @param init The list of params to insert.
     511              :     */
     512              :     iterator
     513              :     insert(
     514              :         iterator before,
     515              :         std::initializer_list<
     516              :             param_pct_view> init);
     517              : 
     518              :     /** Insert params
     519              : 
     520              :         This function inserts a range of
     521              :         params before the specified position.
     522              : 
     523              :         <br>
     524              :         All iterators that are equal to
     525              :         `before` or come after are invalidated.
     526              : 
     527              :         @note
     528              :         The strings referenced by the inputs
     529              :         must not come from the underlying url,
     530              :         or else the behavior is undefined.
     531              : 
     532              :         @par Mandates
     533              :         @code
     534              :         std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true
     535              :         @endcode
     536              : 
     537              :         @par Complexity
     538              :         Linear in `this->url().encoded_query().size()`.
     539              : 
     540              :         @par Exception Safety
     541              :         Strong guarantee.
     542              :         Calls to allocate may throw.
     543              :         Exceptions thrown on invalid input.
     544              : 
     545              :         @throw system_error
     546              :         The range contains an invalid percent-encoding.
     547              : 
     548              :         @return An iterator to the first
     549              :         element inserted, or `before` if
     550              :         `first == last`.
     551              : 
     552              :         @param before An iterator before which
     553              :         the element is inserted. This may
     554              :         be equal to `end()`.
     555              : 
     556              :         @param first, last The range of params
     557              :         to insert.
     558              :     */
     559              :     template<class FwdIt>
     560              :     iterator
     561              :     insert(
     562              :         iterator before,
     563              :         FwdIt first,
     564              :         FwdIt last);
     565              : 
     566              :     //--------------------------------------------
     567              : 
     568              :     /** Erase params
     569              : 
     570              :         This function removes an element from
     571              :         the container.
     572              : 
     573              :         <br>
     574              :         All iterators that are equal to
     575              :         `pos` or come after are invalidated.
     576              : 
     577              :         @par Example
     578              :         @code
     579              :         url u( "?first=John&last=Doe" );
     580              : 
     581              :         params_encoded_ref::iterator it = u.encoded_params().erase( u.encoded_params().begin() );
     582              : 
     583              :         assert( u.encoded_query() == "last=Doe" );
     584              :         @endcode
     585              : 
     586              :         @par Complexity
     587              :         Linear in `this->url().encoded_query().size()`.
     588              : 
     589              :         @par Exception Safety
     590              :         Throws nothing.
     591              : 
     592              :         @return An iterator to one past
     593              :         the removed element.
     594              : 
     595              :         @param pos An iterator to the element.
     596              :     */
     597              :     iterator
     598              :     erase(iterator pos) noexcept;
     599              : 
     600              :     /** Erase params
     601              : 
     602              :         This function removes a range of params
     603              :         from the container.
     604              : 
     605              :         <br>
     606              :         All iterators that are equal to
     607              :         `first` or come after are invalidated.
     608              : 
     609              :         @par Complexity
     610              :         Linear in `this->url().encoded_query().size()`.
     611              : 
     612              :         @par Exception Safety
     613              :         Throws nothing.
     614              : 
     615              :         @return An iterator to one past
     616              :         the removed range.
     617              : 
     618              :         @param first, last The range of
     619              :         params to erase.
     620              :     */
     621              :     iterator
     622              :     erase(
     623              :         iterator first,
     624              :         iterator last) noexcept;
     625              : 
     626              :     /** Erase params
     627              : 
     628              :         <br>
     629              :         All iterators are invalidated.
     630              : 
     631              :         @par Postconditions
     632              :         @code
     633              :         this->count( key, ic ) == 0
     634              :         @endcode
     635              : 
     636              :         @par Complexity
     637              :         Linear in `this->url().encoded_query().size()`.
     638              : 
     639              :         @par Exception Safety
     640              :         Exceptions thrown on invalid input.
     641              : 
     642              :         @throw system_error
     643              :         `key` contains an invalid percent-encoding.
     644              : 
     645              :         @return The number of params removed
     646              :         from the container.
     647              : 
     648              :         @param key The key to match.
     649              :         By default, a case-sensitive
     650              :         comparison is used.
     651              : 
     652              :         @param ic An optional parameter. If
     653              :         the value @ref ignore_case is passed
     654              :         here, the comparison is
     655              :         case-insensitive.
     656              :     */
     657              :     std::size_t
     658              :     erase(
     659              :         pct_string_view key,
     660              :         ignore_case_param ic = {}) noexcept;
     661              : 
     662              :     //--------------------------------------------
     663              : 
     664              :     /** Replace params
     665              : 
     666              :         This function replaces the contents
     667              :         of the element at `pos` with the
     668              :         specified param.
     669              : 
     670              :         <br>
     671              :         All iterators that are equal to
     672              :         `pos` or come after are invalidated.
     673              : 
     674              :         @note
     675              :         The strings passed in must not come
     676              :         from the element being replaced,
     677              :         or else the behavior is undefined.
     678              : 
     679              :         @par Example
     680              :         @code
     681              :         url u( "?first=John&last=Doe" );
     682              : 
     683              :         u.encoded_params().replace( u.encoded_params().begin(), { "title", "Mr" });
     684              : 
     685              :         assert( u.encoded_query() == "title=Mr&last=Doe" );
     686              :         @endcode
     687              : 
     688              :         @par Complexity
     689              :         Linear in `this->url().encoded_query().size()`.
     690              : 
     691              :         @par Exception Safety
     692              :         Strong guarantee.
     693              :         Calls to allocate may throw.
     694              :         Exceptions thrown on invalid input.
     695              : 
     696              :         @throw system_error
     697              :         `p` contains an invalid percent-encoding.
     698              : 
     699              :         @return An iterator to the element.
     700              : 
     701              :         @param pos An iterator to the element.
     702              : 
     703              :         @param p The param to assign.
     704              :     */
     705              :     iterator
     706              :     replace(
     707              :         iterator pos,
     708              :         param_pct_view const& p);
     709              : 
     710              :     /** Replace params
     711              : 
     712              :         This function replaces a range of
     713              :         params with the params in an
     714              :         <em>initializer-list</em>.
     715              : 
     716              :         <br>
     717              :         All iterators that are equal to
     718              :         `from` or come after are invalidated.
     719              : 
     720              :         @note
     721              :         The strings referenced by the inputs
     722              :         must not come from the underlying url,
     723              :         or else the behavior is undefined.
     724              : 
     725              :         @par Complexity
     726              :         Linear in `this->url().encoded_query().size()`.
     727              : 
     728              :         @par Exception Safety
     729              :         Strong guarantee.
     730              :         Calls to allocate may throw.
     731              :         Exceptions thrown on invalid input.
     732              : 
     733              :         @throw system_error
     734              :         `init` contains an invalid percent-encoding.
     735              : 
     736              :         @return An iterator to the first
     737              :         element inserted, or one past `to` if
     738              :         `init.size() == 0`.
     739              : 
     740              :         @param from,to The range of params
     741              :         to replace.
     742              : 
     743              :         @param init The list of params to assign.
     744              :     */
     745              :     iterator
     746              :     replace(
     747              :         iterator from,
     748              :         iterator to,
     749              :         std::initializer_list<
     750              :             param_pct_view> init);
     751              : 
     752              :     /** Replace params
     753              : 
     754              :         This function replaces a range of
     755              :         params with a range of params.
     756              : 
     757              :         <br>
     758              :         All iterators that are equal to
     759              :         `from` or come after are invalidated.
     760              : 
     761              :         @note
     762              :         The strings referenced by the inputs
     763              :         must not come from the underlying url,
     764              :         or else the behavior is undefined.
     765              : 
     766              :         @par Mandates
     767              :         @code
     768              :         std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true
     769              :         @endcode
     770              : 
     771              :         @par Complexity
     772              :         Linear in `this->url().encoded_query().size()`.
     773              : 
     774              :         @par Exception Safety
     775              :         Strong guarantee.
     776              :         Calls to allocate may throw.
     777              :         Exceptions thrown on invalid input.
     778              : 
     779              :         @throw system_error
     780              :         The range contains an invalid percent-encoding.
     781              : 
     782              :         @return An iterator to the first
     783              :         element inserted, or one past `to` if
     784              :         `first == last`.
     785              : 
     786              :         @param from,to The range of params to
     787              :         replace.
     788              : 
     789              :         @param first, last The range of params
     790              :         to assign.
     791              :     */
     792              :     template<class FwdIt>
     793              :     iterator
     794              :     replace(
     795              :         iterator from,
     796              :         iterator to,
     797              :         FwdIt first,
     798              :         FwdIt last);
     799              : 
     800              :     //--------------------------------------------
     801              : 
     802              :     /** Remove the value on an element
     803              : 
     804              :         This function removes the value of
     805              :         an element at the specified position.
     806              :         After the call returns, `has_value`
     807              :         for the element is false.
     808              : 
     809              :         <br>
     810              :         All iterators that are equal to
     811              :         `pos` or come after are invalidated.
     812              : 
     813              :         @par Example
     814              :         @code
     815              :         url u( "?first=John&last=Doe" );
     816              : 
     817              :         u.encoded_params().unset( u.encoded_params().begin() );
     818              : 
     819              :         assert( u.encoded_query() == "first&last=Doe" );
     820              :         @endcode
     821              : 
     822              :         @par Complexity
     823              :         Linear in `this->url().encoded_query().size()`.
     824              : 
     825              :         @par Exception Safety
     826              :         Throws nothing.
     827              : 
     828              :         @return An iterator to the element.
     829              : 
     830              :         @param pos An iterator to the element.
     831              :     */
     832              :     iterator
     833              :     unset(
     834              :         iterator pos) noexcept;
     835              : 
     836              :     /** Set a value
     837              : 
     838              :         This function replaces the value of an
     839              :         element at the specified position.
     840              : 
     841              :         <br>
     842              :         All iterators that are equal to
     843              :         `pos` or come after are invalidated.
     844              : 
     845              :         @note
     846              :         The string passed in must not come
     847              :         from the element being replaced,
     848              :         or else the behavior is undefined.
     849              : 
     850              :         @par Example
     851              :         @code
     852              :         url u( "?id=42&id=69" );
     853              : 
     854              :         u.encoded_params().set( u.encoded_params().begin(), "none" );
     855              : 
     856              :         assert( u.encoded_query() == "id=none&id=69" );
     857              :         @endcode
     858              : 
     859              :         @par Complexity
     860              :         Linear in `this->url().encoded_query().size()`.
     861              : 
     862              :         @par Exception Safety
     863              :         Strong guarantee.
     864              :         Calls to allocate may throw.
     865              :         Exceptions thrown on invalid input.
     866              : 
     867              :         @throw system_error
     868              :         `value` contains an invalid percent-encoding.
     869              : 
     870              :         @return An iterator to the element.
     871              : 
     872              :         @param pos An iterator to the element.
     873              : 
     874              :         @param value The value to assign. The
     875              :         empty string still counts as a value.
     876              :         That is, `has_value` for the element
     877              :         is true.
     878              :     */
     879              :     iterator
     880              :     set(
     881              :         iterator pos,
     882              :         pct_string_view value);
     883              : 
     884              :     /** Set a value
     885              : 
     886              :         This function performs one of two
     887              :         actions depending on the value of
     888              :         `this->contains( key, ic )`.
     889              : 
     890              :         @li If key is contained in the view
     891              :         then one of the matching params has
     892              :         its value changed to the specified value.
     893              :         The remaining params with a matching
     894              :         key are erased. Otherwise,
     895              : 
     896              :         @li If `key` is not contained in the
     897              :         view, then the function apppends the
     898              :         param `{ key, value }`.
     899              : 
     900              :         <br>
     901              :         All iterators are invalidated.
     902              : 
     903              :         @note
     904              :         The strings passed in must not come
     905              :         from the element being replaced,
     906              :         or else the behavior is undefined.
     907              : 
     908              :         @par Example
     909              :         @code
     910              :         url u( "?id=42&id=69" );
     911              : 
     912              :         u.encoded_params().set( "id", "none" );
     913              : 
     914              :         assert( u.encoded_params().count( "id" ) == 1 );
     915              :         @endcode
     916              : 
     917              :         @par Postconditions
     918              :         @code
     919              :         this->count( key, ic ) == 1 && this->find( key, ic )->value == value
     920              :         @endcode
     921              : 
     922              :         @par Complexity
     923              :         Linear in `this->url().encoded_query().size()`.
     924              : 
     925              :         @par Exception Safety
     926              :         Strong guarantee.
     927              :         Calls to allocate may throw.
     928              :         Exceptions thrown on invalid input.
     929              : 
     930              :         @throw system_error
     931              :         `key` or `value` contain an invalid
     932              :         percent-encoding.
     933              : 
     934              :         @return An iterator to the appended
     935              :         or modified element.
     936              : 
     937              :         @param key The key to match.
     938              :         By default, a case-sensitive
     939              :         comparison is used.
     940              : 
     941              :         @param value The value to assign. The
     942              :         empty string still counts as a value.
     943              :         That is, `has_value` for the element
     944              :         is true.
     945              : 
     946              :         @param ic An optional parameter. If
     947              :         the value @ref ignore_case is passed
     948              :         here, the comparison is
     949              :         case-insensitive.
     950              :     */
     951              :     iterator
     952              :     set(
     953              :         pct_string_view key,
     954              :         pct_string_view value,
     955              :         ignore_case_param ic = {});
     956              : 
     957              : private:
     958              :     template<class FwdIt>
     959              :     void
     960              :     assign(FwdIt first, FwdIt last,
     961              :         std::forward_iterator_tag);
     962              : 
     963              :     // Doxygen cannot render ` = delete`
     964              :     template<class FwdIt>
     965              :     void
     966              :     assign(FwdIt first, FwdIt last,
     967              :            std::input_iterator_tag) = delete;
     968              : 
     969              :     template<class FwdIt>
     970              :     iterator
     971              :     insert(
     972              :         iterator before,
     973              :         FwdIt first,
     974              :         FwdIt last,
     975              :         std::forward_iterator_tag);
     976              : 
     977              :     // Doxygen cannot render ` = delete`
     978              :     template<class FwdIt>
     979              :     iterator
     980              :     insert(
     981              :         iterator before,
     982              :         FwdIt first,
     983              :         FwdIt last,
     984              :         std::input_iterator_tag) = delete;
     985              : };
     986              : 
     987              : } // urls
     988              : } // boost
     989              : 
     990              : // This is in <boost/url/url_base.hpp>
     991              : //
     992              : // #include <boost/url/impl/params_encoded_ref.hpp>
     993              : 
     994              : #endif
        

Generated by: LCOV version 2.1