Add formatting functions and examples (#177)

* Add formatting functions and examples

* Fix formatting tests

* Apply workaround for constexpr for some standard library implementations in url_format.hpp

* Drop support for clang 19 with libc++ so that we can support constexp parse function

Author: glynos

.github/workflows/skyr-url-ci.yml

@@ -47,22 +47,6 @@ jobs:
             cxx_standard: 23
           }
 
-          # Clang-18 (C++23)
-          - {
-            name: "Linux Clang 18 Debug (C++23)", artifact: "Linux.tar.xz",
-            os: ubuntu-24.04,
-            build_type: Debug,
-            cc: "clang-18", cxx: "clang++-18",
-            cxx_standard: 23
-          }
-          - {
-            name: "Linux Clang 18 Release (C++23)", artifact: "Linux.tar.xz",
-            os: ubuntu-24.04,
-            build_type: RelWithDebInfo,
-            cc: "clang-18", cxx: "clang++-18",
-            cxx_standard: 23
-          }
-
           # Clang-19 (C++23)
           - {
             name: "Linux Clang 19 Debug (C++23)", artifact: "Linux.tar.xz",
@@ -111,22 +95,6 @@ jobs:
             cxx_standard: 23
           }
 
-          # macOS Clang-18 (C++23)
-          - {
-            name: "macOS Clang 18 Debug (C++23)", artifact: "macOS.tar.xz",
-            os: macos-latest,
-            build_type: Debug,
-            cc: "clang-18", cxx: "clang++-18",
-            cxx_standard: 23
-          }
-          - {
-            name: "macOS Clang 18 Release (C++23)", artifact: "macOS.tar.xz",
-            os: macos-latest,
-            build_type: RelWithDebInfo,
-            cc: "clang-18", cxx: "clang++-18",
-            cxx_standard: 23
-          }
-
           # macOS Clang-19 (C++23)
           - {
             name: "macOS Clang 19 Debug (C++23)", artifact: "macOS.tar.xz",
@@ -255,7 +223,7 @@ jobs:
             COMMAND chmod +x ${cmake_dir}/cmake
           )
 
-      # GCC 13-14 and Clang 18 are pre-installed on ubuntu-24.04
+      # GCC 13-14 are pre-installed on ubuntu-24.04
       # Clang 19-21 need to be installed from LLVM repository
 
       - name: Install Clang and libc++ (C++23 support)
@@ -266,11 +234,9 @@ jobs:
           # Extract version number from compiler name (e.g., clang++-19 -> 19)
           CLANG_VERSION=$(echo "${{ matrix.config.cxx }}" | grep -oP '\d+')
 
-          # Add LLVM repository for newer versions
-          if [[ "$CLANG_VERSION" != "18" ]]; then
-            wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key | sudo tee /etc/apt/trusted.gpg.d/apt.llvm.org.asc
-            sudo add-apt-repository -y "deb http://apt.llvm.org/noble/ llvm-toolchain-noble-${CLANG_VERSION} main"
-          fi
+          # Add LLVM repository
+          wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key | sudo tee /etc/apt/trusted.gpg.d/apt.llvm.org.asc
+          sudo add-apt-repository -y "deb http://apt.llvm.org/noble/ llvm-toolchain-noble-${CLANG_VERSION} main"
 
           sudo apt-get update
 

README.md

@@ -136,31 +136,30 @@ URL string and to process the components:
 ```c++
 // url_parts.cpp
 
+#include <print>
+
 #include <skyr/url.hpp>
-#include <skyr/percent_encoding/percent_decode.hpp>
-#include <iostream>
+#include <skyr/url_format.hpp>
 
 int main() {
   using namespace skyr::literals;
 
   auto url =
       "http://sub.example.إختبار:8090/\xcf\x80?a=1&c=2&b=\xe2\x80\x8d\xf0\x9f\x8c\x88"_url;
 
-  std::cout << "Protocol: " << url.protocol() << std::endl;
-
-  std::cout << "Domain?   " << std::boolalpha << url.is_domain() << std::endl;
-  std::cout << "Domain:   " << url.hostname() << std::endl;
-  std::cout << "Domain:   " << url.u8domain().value() << std::endl;
-
-  std::cout << "Port:     " << url.port<std::uint16_t>().value() << std::endl;
 
-  std::cout << "Pathname: "
-            << skyr::percent_decode(url.pathname()).value() << std::endl;
+  std::println("Origin: {:o}", url);
+  std::println("Protocol: {:s}", url);
+  std::println("Domain?   {}", url.is_domain());
+  std::println("Domain:   {:h}", url);   // Encoded (punycode)
+  std::println("Domain:   {:hd}", url);  // Decoded (unicode)
+  std::println("Port:     {:p}", url);
+  std::println("Pathname: {:Pd}", url);  // Decoded pathname
 
-  std::cout << "Search parameters:" << std::endl;
+  std::println("Search parameters:");
   const auto &search = url.search_parameters();
   for (const auto &[key, value] : search) {
-    std::cout << "  " << "key: " << key << ", value = " << value << std::endl;
+    std::println("  key: {}, value = {}", key, value);
   }
 }
 ```
@@ -189,7 +188,8 @@ target_link_libraries(url_parts PRIVATE skyr::skyr-url)
 The output of this program is:
 
 ```bash
-Protocol: http:
+Origin: http://sub.example.xn--kgbechtv:8090
+Protocol: http
 Domain?   true
 Domain:   sub.example.xn--kgbechtv
 Domain:   sub.example.إختبار

examples/CMakeLists.txt

@@ -19,6 +19,7 @@ foreach(
         example_10.cpp
         example_11.cpp
         example_12.cpp
+        example_13.cpp
 )
     skyr_remove_extension(${file_name} example)
     add_executable(${example} ${file_name})

examples/example_13.cpp

@@ -0,0 +1,88 @@
+// Copyright 2025 Glyn Matthews.
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt of copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+
+#include <print>
+
+#include <skyr/url.hpp>
+#include <skyr/url_format.hpp>
+
+int main() {
+  auto url = skyr::url("https://user:pass@api.example.com:8080/v1/users?filter=active&limit=10#results");
+
+  std::println("URL Formatting Examples:");
+  std::println("========================\n");
+
+  // Full URL (default)
+  std::println("Full URL:     {}", url);
+  std::println();
+
+  // Individual components (encoded by default)
+  std::println("Scheme:       {:s}", url);
+  std::println("Hostname:     {:h}", url);
+  std::println("Port:         {:p}", url);
+  std::println("Pathname:     {:P}", url);
+  std::println("Query:        {:q}", url);
+  std::println("Fragment:     {:f}", url);
+  std::println("Origin:       {:o}", url);
+  std::println();
+
+  // Practical examples
+  std::println("API Endpoint: {:o}{:P}", url, url);
+  std::println("Host:Port:    {:h}:{:p}", url, url);
+  std::println();
+
+  // Different URL types
+  auto https_url = skyr::url("https://example.com/secure");
+  auto http_url = skyr::url("http://example.org:3000/api");
+  auto file_url = skyr::url("file:///Users/test/document.txt");
+
+  std::println("HTTPS (default port): {:o}", https_url);
+  std::println("HTTP (custom port):   {:o}", http_url);
+  std::println("File path:            {:P}", file_url);
+  std::println();
+
+  // Logging examples
+  std::println("Logging Examples:");
+  std::println("-----------------");
+  std::println("[INFO] Connecting to {:h}:{:p}", url, url);
+  std::println("[DEBUG] Request path: {:P}{:q}", url, url);
+  std::println("[TRACE] Full endpoint: {:o}{:P}", url, url);
+  std::println();
+
+  // IP addresses
+  auto ipv4_url = skyr::url("http://192.168.1.1:8080/admin");
+  auto ipv6_url = skyr::url("http://[2001:db8::1]:8080/api");
+
+  std::println("IPv4: {:h}:{:p}", ipv4_url, ipv4_url);
+  std::println("IPv6: {:h}:{:p}", ipv6_url, ipv6_url);
+  std::println();
+
+  // Decoded output examples
+  auto encoded_url = skyr::url("http://example.إختبار/hello%20world?name=John%20Doe&city=Paisley#section%201");
+
+  std::println("Encoded vs Decoded:");
+  std::println("-------------------");
+  std::println("Hostname (encoded): {:h}", encoded_url);
+  std::println("Hostname (decoded): {:hd}", encoded_url);
+  std::println();
+  std::println("Pathname (encoded): {:P}", encoded_url);
+  std::println("Pathname (decoded): {:Pd}", encoded_url);
+  std::println();
+  std::println("Query (encoded):    {:q}", encoded_url);
+  std::println("Query (decoded):    {:qd}", encoded_url);
+  std::println();
+  std::println("Fragment (encoded): {:f}", encoded_url);
+  std::println("Fragment (decoded): {:fd}", encoded_url);
+  std::println();
+
+  // Human-readable logging
+  std::println("Human-Readable Logging:");
+  std::println("-----------------------");
+  std::println("[INFO] User requested: {:Pd}", encoded_url);
+  std::println("[DEBUG] Query params: {:qd}", encoded_url);
+  std::println("[TRACE] Host: {:hd}, Path: {:Pd}", encoded_url, encoded_url);
+
+  return 0;
+}