jh::serio::uri Namespace Reference

Implements URI percent-encoding and decoding utilities. More...

Functions
std::string	encode (const std::string_view &input)
	Encode a string into URI percent-encoded form.
std::string	decode (const std::string_view &input)
	Decode a percent-encoded URI string.
std::string	encode_safe (const std::string_view &input)
	Encode a string into URI percent-encoded form with legality validation.
std::string	decode_safe (const std::string_view &input)
	Decode a percent-encoded URI string with output validation.

Detailed Description

Implements URI percent-encoding and decoding utilities.

URI percent-encoding converts unsafe characters into a textual representation using the %XX hexadecimal format. This ensures that arbitrary data can be safely embedded within URI strings and transported through text-based protocols such as HTTP, REST APIs, or web forms.

This namespace provides high-level wrappers built on top of the optimized primitives in jh::detail::uri_common.

• Basic APIs assume the user passes any arbitrary string, allowing non-UTF-8 encoding or arbitrary binary data.
• Safe APIs assume that user input is always UTF-8 semantics and throw errors when encountering control characters or malformed UTF-8 concatenations.

Whether to use the unchecked version has no impact on performance. The additional checks in the *_safe functions are nearly equivalent to traversing a string_view.

Note

Although we support encoding and decoding for data representing arbitrary binary and its precent-encoding, for this particular semantics, we recommend base64 encoding from jh::serio::base64 and jh::serio::base64url. URI percent-encoding is primarily intended for encoding textual data.

See also

jh::serio::base64

jh::serio::base64url

Function Documentation

decode()

std::string jh::serio::uri::decode ( const std::string_view & input )

nodiscard

Decode a percent-encoded URI string.

This function converts percent-encoded sequences (%XX) back into their original byte representation.

The input is validated to ensure that all percent-encoded sequences are syntactically correct.

Parameters

input

Percent-encoded URI string.

Returns

Decoded URI string.

Exceptions

std::runtime_error

Thrown if the input contains malformed percent-encoding.

decode_safe()

std::string jh::serio::uri::decode_safe ( const std::string_view & input )

nodiscard

Decode a percent-encoded URI string with output validation.

This function first performs percent-decoding and then verifies that the resulting string is a legal textual representation.

• The decoded output must be valid UTF-8.
• No control characters are permitted.

Parameters

input

Percent-encoded URI string.

Returns

Decoded URI string.

Exceptions

std::runtime_error

If the input contains malformed percent-encoding. Or if the decoded result is not a legal UTF-8 string.

Note

This function should be used when decoding data from untrusted sources such as URLs, HTTP parameters, or user input.

encode()

std::string jh::serio::uri::encode ( const std::string_view & input )

nodiscard

Encode a string into URI percent-encoded form.

Characters that are not part of the unreserved URI character set are converted into their percent-encoded representation (%XX).

This function performs no input validation and assumes that the input string is already legal UTF-8.

Parameters

input

Input string to encode.

Returns

A percent-encoded URI string.

Note

• This function assumes the source intentionally permits non-UTF-8 encoding.
• Use encode_safe() when input validation is required.

encode_safe()

std::string jh::serio::uri::encode_safe ( const std::string_view & input )

nodiscard

Encode a string into URI percent-encoded form with legality validation.

This variant verifies that the input string represents a legal textual payload before performing the encoding.

• The input must be valid UTF-8.
• No control characters are permitted.

Parameters

input

Input string to encode.

Returns

A percent-encoded URI string.

Exceptions

std::runtime_error

Thrown if the input string contains invalid UTF-8 or control characters.

Note

Use this function when you want to ensure that the input is a well-formed UTF-8 string.

• This function provides a stronger safety guarantee than encode().
• Recommended for external or untrusted input.