I've changed the name of the default branch from master to main. Please make future PRs to the main branch on the cpp-netlib repo.

This library provides:

• A skyr::url class that implements a generic URL parser, conforming with the WhatWG URL specification
• URL serialization and comparison
• Percent encoding and decoding functions
• IDNA and Punycode functions for domain name parsing
• Unicode conversion utilities

This library has been modernized to use C++23 exclusively, leveraging the latest standard library features:

• std::expected for error handling (no external dependency needed!)
• std::format for string formatting
• std::ranges for functional-style operations
• Minimal external dependencies - only uni-algo required for Unicode/IDNA support

This project requires:

• A C++23 compliant compiler (GCC 13+, Clang 16+, MSVC 2022 17.6+)
• uni-algo library (optional but recommended for full IDNA support)

skyr::url is available on vcpkg. It can be installed by executing the following steps:

> cd ${VCPKG_ROOT}
> git init
> git remote add origin https://github.com/Microsoft/vcpkg.git
> git fetch origin master
> git checkout -b master origin/master
> ./bootstrap-vcpkg.sh
> ./vcpkg install skyr-url

On Windows - for example, using Powershell - replace the call to bootstrap-vcpkg.sh with bootstrap-vcpkg.bat.

Using vcpkg, install the library dependencies:

> cd ${VCPKG_ROOT}
> git init
> git remote add origin https://github.com/Microsoft/vcpkg.git
> git fetch origin master
> git checkout -b master origin/master
> ./bootstrap-vcpkg.sh
> ./vcpkg install uni-algo catch2 nlohmann-json

Note: Only uni-algo is required for the library itself. catch2 and nlohmann-json are only needed for tests and JSON functionality.

From a terminal, execute the following sequence of commands:

> mkdir _build
> cmake \
    -B _build \
    -G "Ninja" \
    -DCMAKE_TOOLCHAIN_FILE=${VCPKG_ROOT}/vcpkg/scripts/buildsystems/vcpkg.cmake \
    .
> cmake --build _build

To run the tests:

> cmake --build _build --target test

On Windows, replace the target with RUN_TESTS:

> cmake --build _build --target RUN_TESTS

To install the library:

> cmake --build _build --target install

> cmake .. \
    -G "Ninja" \
    -DCMAKE_TOOLCHAIN_FILE=${VCPKG_ROOT}/vcpkg/scripts/buildsystems/vcpkg.cmake \
    -DCMAKE_INSTALL_PREFIX=$PREFIX
> ninja
> ninja test
> ninja install

Where $PREFIX is the location where you want to install the library. Depending on the location of $PREFIX, you may need to run the install command as an administrator (e.g. on Linux as sudo).

Here is an example of how to use the skyr::url class to parse a URL string and to process the components:

// url_parts.cpp
#include <skyr/url.hpp>
#include <skyr/percent_encoding/percent_decode.hpp>
#include <iostream>
int main() {
  using namespace skyr::literals;
  auto url =
      "https://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::cout << "Search parameters:" << std::endl;
  const auto &search = url.search_parameters();
  for (const auto &[key, value] : search) {
    std::cout << "  " << "key: " << key << ", value = " << value << std::endl;
  }
}

Here is the CMake script to build the example:

# CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
project(my_project)
find_package(skyr-url CONFIG REQUIRED)
set(CMAKE_CXX_STANDARD 23)
add_executable(url_parts url_parts.cpp)
target_link_libraries(url_parts PRIVATE skyr::skyr-url)

The output of this program is:

Protocol: http:
Domain?   true
Domain:   sub.example.xn--kgbechtv
Domain:   sub.example.إختبار
Port:     8090
Pathname: /π
Search parameters:
  key: a, value = 1
  key: c, value = 2
  key: b, value = ‍🌈

This library leverages C++23 standard library features:

• std::expected (C++23) - Error handling
• std::format (C++23) - String formatting
• std::ranges (C++20/23) - Range algorithms and views

External dependencies:

• uni-algo - Unicode algorithms and IDNA processing (optional but recommended)

Test dependencies (optional):

• Catch2 - Testing framework
• nlohmann-json - JSON support (for optional JSON features)

The library passes 21 out of 22 test suites with 240 out of 242 assertions (99.2% pass rate):

✅ All core functionality tests pass ✅ Unicode, IDNA, and Punycode tests pass ✅ Network (IPv4/IPv6) parsing tests pass ✅ Percent encoding/decoding tests pass ✅ URL parsing and serialization tests pass ⚠️ 2 edge case assertions in dot-segment path normalization (minor regression)

This library includes Unicode processing support from uni-algo.

Look at the GitHub Actions Status for all of the configurations for which this library is tested.

This library is released under the Boost Software License (please see https://boost.org/LICENSE_1_0.txt or the accompanying LICENSE_1_0.txt file for the full text).

This name was chosen by a random project name generator, which itself was randomly chosen.

Any questions about this library can be addressed to the cpp-netlib developers mailing list. Issues can be filed on our GitHub page.

You can also contact me via Twitter @glynos.