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_VIEW_HPP
      12             : #define BOOST_URL_PARAMS_VIEW_HPP
      13             : 
      14             : #include <boost/url/detail/config.hpp>
      15             : #include <boost/url/params_base.hpp>
      16             : 
      17             : namespace boost {
      18             : namespace urls {
      19             : 
      20             : /** A view representing query parameters in a URL
      21             : 
      22             :     Objects of this type are used to interpret
      23             :     the query parameters as a bidirectional view
      24             :     of key/value pairs.
      25             : 
      26             :     The view does not retain ownership of the
      27             :     elements and instead references the original
      28             :     character buffer. The caller is responsible
      29             :     for ensuring that the lifetime of the buffer
      30             :     extends until it is no longer referenced.
      31             : 
      32             :     @par Example
      33             :     @code
      34             :     url_view u( "?first=John&last=Doe" );
      35             : 
      36             :     params_view p = u.params();
      37             :     @endcode
      38             : 
      39             :     Percent escapes in strings returned when
      40             :     dereferencing iterators are automatically
      41             :     decoded.
      42             : 
      43             :     @par Iterator Invalidation
      44             :     Changes to the underlying character buffer
      45             :     can invalidate iterators which reference it.
      46             : */
      47             : class params_view
      48             :     : public params_base
      49             : {
      50             :     friend class url_view_base;
      51             :     friend class params_encoded_view;
      52             :     friend class params_ref;
      53             : 
      54             :     params_view(
      55             :         detail::query_ref const& ref,
      56             :         encoding_opts opt) noexcept;
      57             : 
      58             : public:
      59             :     /** Constructor
      60             : 
      61             :         Default-constructed params have
      62             :         zero elements.
      63             : 
      64             :         @par Example
      65             :         @code
      66             :         params_view qp;
      67             :         @endcode
      68             : 
      69             :         @par Effects
      70             :         @code
      71             :         return params_view( "" );
      72             :         @endcode
      73             : 
      74             :         @par Complexity
      75             :         Constant.
      76             : 
      77             :         @par Exception Safety
      78             :         Throws nothing.
      79             :     */
      80           1 :     params_view() = default;
      81             : 
      82             :     /** Constructor
      83             : 
      84             :         After construction both views reference
      85             :         the same character buffer.
      86             : 
      87             :         Ownership is not transferred; the caller
      88             :         is responsible for ensuring the lifetime
      89             :         of the buffer extends until it is no
      90             :         longer referenced.
      91             : 
      92             :         @par Postconditions
      93             :         @code
      94             :         this->buffer().data() == other.buffer().data()
      95             :         @endcode
      96             : 
      97             :         @par Complexity
      98             :         Constant.
      99             : 
     100             :         @par Exception Safety
     101             :         Throws nothing
     102             :     */
     103             :     params_view(
     104             :         params_view const& other) = default;
     105             : 
     106             :     /** Constructor
     107             : 
     108             :         After construction both views will
     109             :         reference the same character buffer
     110             :         but this instance will use the specified
     111             :         @ref encoding_opts when the values
     112             :         are decoded.
     113             : 
     114             :         Ownership is not transferred; the caller
     115             :         is responsible for ensuring the lifetime
     116             :         of the buffer extends until it is no
     117             :         longer referenced.
     118             : 
     119             :         @par Postconditions
     120             :         @code
     121             :         this->buffer().data() == other.buffer().data()
     122             :         @endcode
     123             : 
     124             :         @par Complexity
     125             :         Constant.
     126             : 
     127             :         @par Exception Safety
     128             :         Throws nothing
     129             :     */
     130             :     params_view(
     131             :         params_view const& other,
     132             :         encoding_opts opt) noexcept;
     133             : 
     134             :     /** Constructor
     135             : 
     136             :         This function constructs params from
     137             :         a valid query parameter string, which
     138             :         can contain percent escapes. Unlike
     139             :         the parameters in URLs, the string
     140             :         passed here should not start with "?".
     141             :         Upon construction, the view references
     142             :         the character buffer pointed to by `s`.
     143             :         The caller is responsible for ensuring
     144             :         that the lifetime of the buffer extends
     145             :         until it is no longer referenced.
     146             : 
     147             :         @par Example
     148             :         @code
     149             :         params_view qp( "first=John&last=Doe" );
     150             :         @endcode
     151             : 
     152             :         @par Effects
     153             :         @code
     154             :         return parse_query( s ).value();
     155             :         @endcode
     156             : 
     157             :         @par Postconditions
     158             :         @code
     159             :         this->buffer().data() == s.data()
     160             :         @endcode
     161             : 
     162             :         @par Complexity
     163             :         Linear in `s`.
     164             : 
     165             :         @par Exception Safety
     166             :         Exceptions thrown on invalid input.
     167             : 
     168             :         @throw system_error
     169             :         `s` contains an invalid query parameter
     170             :         string.
     171             : 
     172             :         @param s The string to parse.
     173             : 
     174             :         @par BNF
     175             :         @code
     176             :         query-params    = [ query-param ] *( "&" query-param )
     177             : 
     178             :         query-param     = key [ "=" value ]
     179             :         @endcode
     180             : 
     181             :         @par Specification
     182             :         @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
     183             :             >3.4.  Query</a>
     184             :     */
     185             :     BOOST_URL_DECL
     186             :     params_view(
     187             :         core::string_view s);
     188             : 
     189             :     /** Constructor
     190             : 
     191             :         This function constructs params from
     192             :         a valid query parameter string, which
     193             :         can contain percent escapes.
     194             : 
     195             :         This instance will use the specified
     196             :         @ref encoding_opts when the values
     197             :         are decoded.
     198             : 
     199             :         Unlike the parameters in URLs, the string
     200             :         passed here should not start with "?".
     201             :         Upon construction, the view will
     202             :         reference the character buffer pointed
     203             :         to by `s`. The caller is responsible
     204             :         for ensuring that the lifetime of the
     205             :         buffer extends until it is no longer
     206             :         referenced.
     207             : 
     208             :         @par Example
     209             :         @code
     210             :         encoding_opts opt;
     211             :         opt.space_as_plus = true;
     212             :         params_view qp( "name=John+Doe", opt );
     213             :         @endcode
     214             : 
     215             :         @par Effects
     216             :         @code
     217             :         return params_view(parse_query( s ).value(), opt);
     218             :         @endcode
     219             : 
     220             :         @par Postconditions
     221             :         @code
     222             :         this->buffer().data() == s.data()
     223             :         @endcode
     224             : 
     225             :         @par Complexity
     226             :         Linear in `s`.
     227             : 
     228             :         @par Exception Safety
     229             :         Exceptions thrown on invalid input.
     230             : 
     231             :         @throw system_error
     232             :         `s` contains an invalid query parameter
     233             :         string.
     234             : 
     235             :         @param s The string to parse.
     236             : 
     237             :         @param opt The options for decoding. If
     238             :         this parameter is omitted, `space_as_plus`
     239             :         is used.
     240             : 
     241             :         @par BNF
     242             :         @code
     243             :         query-params    = [ query-param ] *( "&" query-param )
     244             : 
     245             :         query-param     = key [ "=" value ]
     246             :         @endcode
     247             : 
     248             :         @par Specification
     249             :         @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
     250             :             >3.4.  Query</a>
     251             :     */
     252             :     BOOST_URL_DECL
     253             :     params_view(
     254             :         core::string_view s,
     255             :         encoding_opts opt);
     256             : 
     257             :     /** Assignment
     258             : 
     259             :         After assignment, both views reference
     260             :         the same underlying character buffer.
     261             : 
     262             :         Ownership is not transferred; the caller
     263             :         is responsible for ensuring the lifetime
     264             :         of the buffer extends until it is no
     265             :         longer referenced.
     266             : 
     267             :         @par Postconditions
     268             :         @code
     269             :         this->buffer().data() == other.buffer().data()
     270             :         @endcode
     271             : 
     272             :         @par Complexity
     273             :         Constant
     274             : 
     275             :         @par Exception Safety
     276             :         Throws nothing
     277             :     */
     278             :     params_view&
     279             :     operator=(
     280             :         params_view const&) = default;
     281             : };
     282             : 
     283             : } // urls
     284             : } // boost
     285             : 
     286             : #endif