docs: add examples to normalization functions

example/router/router.hpp

@@ -28,9 +28,6 @@ namespace urls {
     @tparam T type of resource associated with
     each path template
 
-    @tparam N maximum number of replacement fields
-    in a path template
-
     @par Exception Safety
 
     @li Functions marked `noexcept` provide the

include/boost/url/url_base.hpp

@@ -2656,6 +2656,61 @@ class BOOST_URL_DECL
         Applies Syntax-based normalization to
         all components of the URL.
 
+        The scheme is normalized to lowercase.
+
+        @code
+        assert( url( "HTTP://www.example.com" ).normalize().buffer() == "http://www.example.com" );
+        @endcode
+
+        The host is normalized to lowercase.
+        Percent-encoding triplets are normalized
+        to uppercase letters. Percent-encoded
+        octets that correspond to unreserved
+        characters are decoded.
+
+        @code
+        assert( url( "http://www.Example.com" ).normalize().buffer() == "http://www.example.com" );
+        assert( url( "http://www.%65xample.com" ).normalize().buffer() == "http://www.example.com" );
+        @endcode
+
+        Percent-encoding triplets in the path
+        are normalized to uppercase letters.
+        Percent-encoded octets that correspond
+        to unreserved characters are decoded.
+        Redundant path-segments "." and ".."
+        are removed.
+
+        @code
+        assert( url( "http://www.example.com/a/b/../c" ).normalize().buffer() == "http://www.example.com/a/c" );
+        assert( url( "http://www.example.com/a/./b" ).normalize().buffer() == "http://www.example.com/a/b" );
+        assert( url( "http://www.example.com/%63ss" ).normalize().buffer() == "http://www.example.com/css" );
+        @endcode
+
+        Percent-encoding triplets in the query
+        are normalized to uppercase letters.
+        Percent-encoded octets that correspond
+        to unreserved characters are decoded.
+
+        @code
+        assert( url( "http://www.example.com?a=%62" ).normalize().buffer() == "http://www.example.com?a=b" );
+        @endcode
+
+        Percent-encoding triplets in the fragment
+        are normalized to uppercase letters.
+        Percent-encoded octets that correspond
+        to unreserved characters are decoded.
+
+        @code
+        assert( url( "http://www.example.com#%61bc" ).normalize().buffer() == "http://www.example.com#abc" );
+        @endcode
+
+        Applying normalization to a URL with all
+        components percent-encoded:
+
+        @code
+        assert( url( "HTTP://www.Example.com/%70ath?%71uery#%66rag" ).normalize().buffer() == "http://www.example.com/path?query#frag" );
+        @endcode
+
         @return `*this`
 
         @par Exception Safety
@@ -2666,6 +2721,13 @@ class BOOST_URL_DECL
         @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2"
             >6.2.2 Syntax-Based Normalization (rfc3986)</a>
 
+        @see
+            @ref normalize_scheme,
+            @ref normalize_authority,
+            @ref normalize_path,
+            @ref normalize_query,
+            @ref normalize_fragment
+
     */
     url_base&
     normalize();
@@ -2677,6 +2739,10 @@ class BOOST_URL_DECL
 
         The scheme is normalized to lowercase.
 
+        @code
+        assert( url( "HTTP://www.example.com" ).normalize_scheme().buffer() == "http://www.example.com" );
+        @endcode
+
         @return `*this`
 
         @par Exception Safety
@@ -2696,11 +2762,17 @@ class BOOST_URL_DECL
         Applies Syntax-based normalization to the
         URL authority.
 
+        The host is normalized to lowercase.
         Percent-encoding triplets are normalized
         to uppercase letters. Percent-encoded
         octets that correspond to unreserved
         characters are decoded.
 
+        @code
+        assert( url( "http://www.Example.com" ).normalize_authority().buffer() == "http://www.example.com" );
+        assert( url( "http://www.%65xample.com" ).normalize_authority().buffer() == "http://www.example.com" );
+        @endcode
+
         @return `*this`
 
         @par Exception Safety
@@ -2724,7 +2796,13 @@ class BOOST_URL_DECL
         to uppercase letters. Percent-encoded
         octets that correspond to unreserved
         characters are decoded. Redundant
-        path-segments are removed.
+        path-segments "." and ".." are removed.
+
+        @code
+        assert( url( "http://www.example.com/a/b/../c" ).normalize_path().buffer() == "http://www.example.com/a/c" );
+        assert( url( "http://www.example.com/a/./b" ).normalize_path().buffer() == "http://www.example.com/a/b" );
+        assert( url( "http://www.example.com/%63ss" ).normalize_path().buffer() == "http://www.example.com/css" );
+        @endcode
 
         @return `*this`
 
@@ -2750,6 +2828,10 @@ class BOOST_URL_DECL
         octets that correspond to unreserved
         characters are decoded.
 
+        @code
+        assert( url( "http://www.example.com?a=%62" ).normalize_query().buffer() == "http://www.example.com?a=b" );
+        @endcode
+
         @return `*this`
 
         @par Exception Safety
@@ -2774,6 +2856,10 @@ class BOOST_URL_DECL
         octets that correspond to unreserved
         characters are decoded.
 
+        @code
+        assert( url( "http://www.example.com#%61bc" ).normalize_fragment().buffer() == "http://www.example.com#abc" );
+        @endcode
+
         @return `*this`
 
         @par Exception Safety

test/unit/url_base.cpp

@@ -1823,6 +1823,41 @@ struct url_base_test
 
         // remove_origin
         assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );
+
+        //----------------------------------------
+        //
+        // Normalization
+        //
+        //----------------------------------------
+
+        // normalize
+        assert( url( "HTTP://www.example.com" ).normalize().buffer() == "http://www.example.com" );
+        assert( url( "http://www.Example.com" ).normalize().buffer() == "http://www.example.com" );
+        assert( url( "http://www.%65xample.com" ).normalize().buffer() == "http://www.example.com" );
+        assert( url( "http://www.example.com/a/b/../c" ).normalize().buffer() == "http://www.example.com/a/c" );
+        assert( url( "http://www.example.com/a/./b" ).normalize().buffer() == "http://www.example.com/a/b" );
+        assert( url( "http://www.example.com/%63ss" ).normalize().buffer() == "http://www.example.com/css" );
+        assert( url( "http://www.example.com?a=%62" ).normalize().buffer() == "http://www.example.com?a=b" );
+        assert( url( "http://www.example.com#%61bc" ).normalize().buffer() == "http://www.example.com#abc" );
+        assert( url( "HTTP://www.Example.com/%70ath?%71uery#%66rag" ).normalize().buffer() == "http://www.example.com/path?query#frag" );
+
+        // normalize_scheme
+        assert( url( "HTTP://www.example.com" ).normalize_scheme().buffer() == "http://www.example.com" );
+
+        // normalize_authority
+        assert( url( "http://www.Example.com" ).normalize_authority().buffer() == "http://www.example.com" );
+        assert( url( "http://www.%65xample.com" ).normalize_authority().buffer() == "http://www.example.com" );
+
+        // normalize_path
+        assert( url( "http://www.example.com/a/b/../c" ).normalize_path().buffer() == "http://www.example.com/a/c" );
+        assert( url( "http://www.example.com/a/./b" ).normalize_path().buffer() == "http://www.example.com/a/b" );
+        assert( url( "http://www.example.com/%63ss" ).normalize_path().buffer() == "http://www.example.com/css" );
+
+        // normalize_query
+        assert( url( "http://www.example.com?a=%62" ).normalize_query().buffer() == "http://www.example.com?a=b" );
+
+        // normalize_fragment
+        assert( url( "http://www.example.com#%61bc" ).normalize_fragment().buffer() == "http://www.example.com#abc" );
     }
 
     void