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_ENCODING_OPTS_HPP
      12              : #define BOOST_URL_ENCODING_OPTS_HPP
      13              : 
      14              : #include <boost/url/detail/config.hpp>
      15              : 
      16              : namespace boost {
      17              : namespace urls {
      18              : 
      19              : /** Percent-encoding options
      20              : 
      21              :     These options are used to customize
      22              :     the behavior of algorithms which use
      23              :     percent escapes, such as encoding
      24              :     or decoding.
      25              : 
      26              :     @see
      27              :         @ref encode,
      28              :         @ref encoded_size,
      29              :         @ref pct_string_view.
      30              : */
      31              : struct encoding_opts
      32              : {
      33              :     /** True if spaces encode to and from plus signs
      34              : 
      35              :         Although not prescribed by RFC 3986,
      36              :         many applications decode plus signs
      37              :         in URL queries as spaces. In particular,
      38              :         the form-urlencoded Media Type in HTML
      39              :         for submitting forms uses this convention.
      40              : 
      41              :         This option controls whether
      42              :         the PLUS character ("+") is used to
      43              :         represent the SP character (" ") when
      44              :         encoding or decoding.
      45              : 
      46              :         When this option is `true`, both the
      47              :         encoded SP ("%20") and the PLUS
      48              :         character ("+") represent a space (" ")
      49              :         when decoding. To represent a plus sign,
      50              :         its encoded form ("%2B") is used.
      51              : 
      52              :         The @ref encode and @ref encoded_size functions
      53              :         will encode spaces as plus signs when
      54              :         this option is `true`, regardless of the
      55              :         allowed character set. They will also
      56              :         encode plus signs as "%2B" when this
      57              :         option is `true`, regardless of the
      58              :         allowed character set.
      59              : 
      60              :         Note that when a URL is normalized,
      61              :         all unreserved percent-encoded characters are
      62              :         replaced with their unreserved equivalents.
      63              :         However, normalizing the URL query maintains
      64              :         the decoded and encoded "&=+" as they are
      65              :         because they might have different meanings.
      66              : 
      67              :         This behavior is not optional because
      68              :         normalization can only mitigate false
      69              :         negatives, but it should eliminate
      70              :         false positives.
      71              :         Making it optional would allow
      72              :         a false positive because there's
      73              :         at least one very relevant schema (HTTP)
      74              :         where a decoded or encoded "&=+" has different
      75              :         meanings and represents different resources.
      76              : 
      77              :         The same considerations apply to URL comparison
      78              :         algorithms in the library, as they treat URLs
      79              :         as if they were normalized.
      80              : 
      81              :         @par Specification
      82              :         @li <a href="https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1">
      83              :             application/x-www-form-urlencoded (w3.org)</a>
      84              :         @li <a href="https://datatracker.ietf.org/doc/html/rfc1866#section-8.2.1">
      85              :             The form-urlencoded Media Type (RFC 1866)</a>
      86              :         @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.2">
      87              :             Section 6.2.2.2. Percent-Encoding Normalization (RFC 3986)</a>
      88              :     */
      89              :     bool space_as_plus = false;
      90              : 
      91              :     /** True if hexadecimal digits are emitted as lower case
      92              : 
      93              :         By default, percent-encoding algorithms
      94              :         emit hexadecimal digits A through F as
      95              :         uppercase letters. When this option is
      96              :         `true`, lowercase letters are used.
      97              :     */
      98              :     bool lower_case = false;
      99              : 
     100              :     /** True if nulls are not allowed
     101              : 
     102              :         Normally all possible character values
     103              :         (from 0 to 255) are allowed, with reserved
     104              :         characters being replaced with escapes
     105              :         upon encoding. When this option is true,
     106              :         attempting to decode a null will result
     107              :         in an error.
     108              :     */
     109              :     bool disallow_null = false;
     110              : 
     111              :     /** Constructs an `encoding_opts` object with the specified options.
     112              : 
     113              :         @param space_as_plus If true, spaces will be encoded as plus signs.
     114              :         @param lower_case If true, hexadecimal digits will be emitted as lower case.
     115              :         @param disallow_null If true, null characters will not be allowed.
     116              :      */
     117              :     BOOST_CXX14_CONSTEXPR
     118              :     inline
     119         8025 :     encoding_opts(
     120              :         bool const space_as_plus = false,
     121              :         bool const lower_case = false,
     122              :         bool const disallow_null = false) noexcept
     123         8025 :         : space_as_plus(space_as_plus)
     124         8025 :         , lower_case(lower_case)
     125         8025 :         , disallow_null(disallow_null) {}
     126              : };
     127              : 
     128              : } // urls
     129              : } // boost
     130              : 
     131              : #endif