TLA  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 HIT        8408 :     encoding_opts(
     120                 :         bool const space_as_plus = false,
     121                 :         bool const lower_case = false,
     122                 :         bool const disallow_null = false) noexcept
     123            8408 :         : space_as_plus(space_as_plus)
     124            8408 :         , lower_case(lower_case)
     125            8408 :         , disallow_null(disallow_null) {}
     126                 : };
     127                 : 
     128                 : } // urls
     129                 : } // boost
     130                 : 
     131                 : #endif