uri_encode/

lib.rs

//! URI percent-encoding functions.
//!
//! This crate provides functions for percent-encoding strings according to RFC 3986,
//! with APIs that mirror JavaScript's `encodeURI()` and `encodeURIComponent()` functions.
//!
//! # Overview
//!
//! URI encoding (also called percent-encoding) replaces unsafe ASCII characters with
//! a `%` followed by two hexadecimal digits representing the character's byte value.
//! For example, a space becomes `%20`.
//!
//! Different contexts require different encoding rules:
//!
//! - [`encode_uri`] preserves URI structure characters, suitable for encoding complete URLs
//! - [`encode_uri_component`] encodes more aggressively, suitable for path segments or query values
//! - [`encode_query_param`] uses `+` for spaces (application/x-www-form-urlencoded style)
//!
//! # Examples
//!
//! ```
//! use uri_encode::{encode_uri, encode_uri_component, encode_query_param};
//!
//! // Encoding a complete URL preserves its structure
//! let url = "https://example.com/path?q=hello world";
//! assert_eq!(encode_uri(url), "https://example.com/path?q=hello%20world");
//!
//! // Encoding a component is more aggressive
//! let component = "hello world&foo=bar";
//! assert_eq!(encode_uri_component(component), "hello%20world%26foo%3dbar");
//!
//! // Query parameters use + for spaces
//! let param = "hello world";
//! assert_eq!(encode_query_param(param), "hello+world");
//! ```
//!
//! # Character Sets
//!
//! The following characters are never encoded by any function (unreserved characters per RFC 3986):
//!
//! - Alphanumeric: `A-Z`, `a-z`, `0-9`
//! - Special: `-`, `_`, `.`, `!`, `~`, `*`, `'`, `(`, `)`
//!
//! Additionally, [`encode_uri`] and [`encode_query_param`] preserve these reserved characters:
//!
//! - `;`, `,`, `/`, `?`, `:`, `@`, `&`, `=`, `+`, `$`, `#`
//!
//! # No Unsafe Code
//!
//! This crate uses `#![forbid(unsafe_code)]` and has zero dependencies.

#![forbid(unsafe_code)]

/// Encodes a complete URI, preserving its structural characters.
///
/// This function is equivalent to JavaScript's `encodeURI()`. It encodes all characters
/// except those that are valid in a URI, including reserved characters that have special
/// meaning in URI syntax.
///
/// # Preserved Characters
///
/// The following characters are passed through unchanged:
///
/// - Unreserved: `A-Z`, `a-z`, `0-9`, `-`, `_`, `.`, `!`, `~`, `*`, `'`, `(`, `)`
/// - Reserved: `;`, `,`, `/`, `?`, `:`, `@`, `&`, `=`, `+`, `$`, `#`
///
/// All other characters are percent-encoded.
///
/// # Use Cases
///
/// Use this function when you have a complete URL and want to ensure any unsafe
/// characters (like spaces) are encoded while preserving the URL's structure.
///
/// # Examples
///
/// ```
/// use uri_encode::encode_uri;
///
/// // Spaces are encoded, but URL structure is preserved
/// assert_eq!(
///     encode_uri("https://example.com/hello world?name=foo bar"),
///     "https://example.com/hello%20world?name=foo%20bar"
/// );
///
/// // Reserved characters are preserved
/// assert_eq!(encode_uri("a/b?c=d&e=f"), "a/b?c=d&e=f");
///
/// // Non-ASCII characters are encoded
/// assert_eq!(encode_uri("café"), "caf%c3%a9");
/// ```
pub fn encode_uri(s: impl AsRef<str>) -> String {
    let mut encoded = String::with_capacity(s.as_ref().len());
    for c in s.as_ref().as_bytes() {
        match c {
            b'A'..=b'Z'
            | b'a'..=b'z'
            | b'0'..=b'9'
            | b'-'
            | b'_'
            | b'.'
            | b'!'
            | b'~'
            | b'*'
            | b'\''
            | b'('
            | b')'
            | b';'
            | b','
            | b'/'
            | b'?'
            | b':'
            | b'@'
            | b'&'
            | b'='
            | b'+'
            | b'$'
            | b'#' => encoded.push(char::from_u32(*c as _).unwrap()),
            c => {
                encoded.push('%');
                encoded.push_str(&format!("{:02x}", c));
            }
        }
    }
    encoded
}

/// Encodes a URI component, such as a path segment or query value.
///
/// This function is equivalent to JavaScript's `encodeURIComponent()`. It performs
/// more aggressive encoding than [`encode_uri`], encoding all characters except
/// unreserved characters.
///
/// # Preserved Characters
///
/// Only unreserved characters are passed through unchanged:
///
/// - `A-Z`, `a-z`, `0-9`, `-`, `_`, `.`, `!`, `~`, `*`, `'`, `(`, `)`
///
/// All other characters, including reserved URI characters like `/`, `?`, `&`, `=`,
/// are percent-encoded.
///
/// # Use Cases
///
/// Use this function when encoding values that will become part of a URL:
///
/// - Path segments
/// - Query parameter names and values
/// - Fragment identifiers
/// - Any user-provided input that will be embedded in a URL
///
/// # Examples
///
/// ```
/// use uri_encode::encode_uri_component;
///
/// // Reserved characters are encoded
/// assert_eq!(encode_uri_component("a/b?c=d"), "a%2fb%3fc%3dd");
///
/// // Useful for query values
/// let search = "hello world";
/// let url = format!("https://example.com/search?q={}", encode_uri_component(search));
/// assert_eq!(url, "https://example.com/search?q=hello%20world");
///
/// // Handles special characters safely
/// assert_eq!(encode_uri_component("<script>"), "%3cscript%3e");
/// ```
pub fn encode_uri_component(s: impl AsRef<str>) -> String {
    let mut encoded = String::with_capacity(s.as_ref().len());
    for c in s.as_ref().as_bytes() {
        match c {
            b'A'..=b'Z'
            | b'a'..=b'z'
            | b'0'..=b'9'
            | b'-'
            | b'_'
            | b'.'
            | b'!'
            | b'~'
            | b'*'
            | b'\''
            | b'('
            | b')' => encoded.push(char::from_u32(*c as _).unwrap()),
            c => {
                encoded.push('%');
                encoded.push_str(&format!("{:02x}", c));
            }
        }
    }
    encoded
}

/// Encodes a query parameter name or value using `+` for spaces.
///
/// This function follows the `application/x-www-form-urlencoded` encoding format,
/// which is commonly used in HTML form submissions. The key difference from
/// [`encode_uri_component`] is that spaces are encoded as `+` instead of `%20`.
///
/// # Preserved Characters
///
/// The following characters are passed through unchanged:
///
/// - Unreserved: `A-Z`, `a-z`, `0-9`, `-`, `_`, `.`, `!`, `~`, `*`, `'`, `(`, `)`
/// - Reserved: `;`, `,`, `/`, `?`, `:`, `@`, `&`, `=`, `+`, `$`, `#`
///
/// Spaces are converted to `+`, and all other characters are percent-encoded.
///
/// # Use Cases
///
/// Use this function when building query strings that will be submitted as form data
/// or when you want the more compact `+` encoding for spaces.
///
/// # Examples
///
/// ```
/// use uri_encode::encode_query_param;
///
/// // Spaces become +
/// assert_eq!(encode_query_param("hello world"), "hello+world");
///
/// // Building a query string
/// let name = "John Doe";
/// let city = "New York";
/// let query = format!("name={}&city={}", encode_query_param(name), encode_query_param(city));
/// assert_eq!(query, "name=John+Doe&city=New+York");
/// ```
pub fn encode_query_param(s: impl AsRef<str>) -> String {
    let mut encoded = String::with_capacity(s.as_ref().len());
    for c in s.as_ref().as_bytes() {
        match c {
            b' ' => encoded.push('+'),
            b'A'..=b'Z'
            | b'a'..=b'z'
            | b'0'..=b'9'
            | b'-'
            | b'_'
            | b'.'
            | b'!'
            | b'~'
            | b'*'
            | b'\''
            | b'('
            | b')'
            | b';'
            | b','
            | b'/'
            | b'?'
            | b':'
            | b'@'
            | b'&'
            | b'='
            | b'+'
            | b'$'
            | b'#' => encoded.push(char::from_u32(*c as _).unwrap()),
            c => {
                encoded.push('%');
                encoded.push_str(&format!("{:02x}", c));
            }
        }
    }
    encoded
}

#[cfg(test)]
mod tests {
    use super::*;

    mod encode_uri_tests {
        use super::*;

        #[test]
        fn empty_string() {
            assert_eq!(encode_uri(""), "");
        }

        #[test]
        fn alphanumeric_unchanged() {
            assert_eq!(encode_uri("ABCxyz123"), "ABCxyz123");
        }

        #[test]
        fn unreserved_chars_unchanged() {
            assert_eq!(encode_uri("-_.!~*'()"), "-_.!~*'()");
        }

        #[test]
        fn reserved_chars_unchanged() {
            assert_eq!(encode_uri(";,/?:@&=+$#"), ";,/?:@&=+$#");
        }

        #[test]
        fn spaces_encoded() {
            assert_eq!(encode_uri("hello world"), "hello%20world");
        }

        #[test]
        fn complete_url_structure_preserved() {
            assert_eq!(
                encode_uri("https://user:pass@example.com:8080/path?q=1&r=2#frag"),
                "https://user:pass@example.com:8080/path?q=1&r=2#frag"
            );
        }

        #[test]
        fn url_with_spaces() {
            assert_eq!(
                encode_uri("https://example.com/hello world?name=foo bar"),
                "https://example.com/hello%20world?name=foo%20bar"
            );
        }

        #[test]
        fn non_ascii_encoded() {
            assert_eq!(encode_uri("café"), "caf%c3%a9");
            assert_eq!(encode_uri("日本"), "%e6%97%a5%e6%9c%ac");
        }

        #[test]
        fn special_chars_encoded() {
            assert_eq!(encode_uri("<>\""), "%3c%3e%22");
            assert_eq!(encode_uri("{}|\\^`"), "%7b%7d%7c%5c%5e%60");
        }

        #[test]
        fn accepts_string_slice() {
            let s = String::from("test value");
            assert_eq!(encode_uri(&s), "test%20value");
            assert_eq!(encode_uri(s), "test%20value");
        }
    }

    mod encode_uri_component_tests {
        use super::*;

        #[test]
        fn empty_string() {
            assert_eq!(encode_uri_component(""), "");
        }

        #[test]
        fn alphanumeric_unchanged() {
            assert_eq!(encode_uri_component("ABCxyz123"), "ABCxyz123");
        }

        #[test]
        fn unreserved_chars_unchanged() {
            assert_eq!(encode_uri_component("-_.!~*'()"), "-_.!~*'()");
        }

        #[test]
        fn reserved_chars_encoded() {
            assert_eq!(
                encode_uri_component(";,/?:@&=+$#"),
                "%3b%2c%2f%3f%3a%40%26%3d%2b%24%23"
            );
        }

        #[test]
        fn spaces_encoded() {
            assert_eq!(encode_uri_component("hello world"), "hello%20world");
        }

        #[test]
        fn path_segment() {
            assert_eq!(encode_uri_component("path/to/file"), "path%2fto%2ffile");
        }

        #[test]
        fn query_value_with_special_chars() {
            assert_eq!(encode_uri_component("a=1&b=2"), "a%3d1%26b%3d2");
        }

        #[test]
        fn html_entities_encoded() {
            assert_eq!(encode_uri_component("<script>"), "%3cscript%3e");
            assert_eq!(encode_uri_component("\"alert\""), "%22alert%22");
        }

        #[test]
        fn non_ascii_encoded() {
            assert_eq!(encode_uri_component("é"), "%c3%a9");
            assert_eq!(encode_uri_component("émoji"), "%c3%a9moji");
        }

        #[test]
        fn all_bytes_handled() {
            // Test that control characters are encoded
            assert_eq!(encode_uri_component("\x00"), "%00");
            assert_eq!(encode_uri_component("\x1f"), "%1f");
            assert_eq!(encode_uri_component("\x7f"), "%7f");
        }
    }

    mod encode_query_param_tests {
        use super::*;

        #[test]
        fn empty_string() {
            assert_eq!(encode_query_param(""), "");
        }

        #[test]
        fn alphanumeric_unchanged() {
            assert_eq!(encode_query_param("ABCxyz123"), "ABCxyz123");
        }

        #[test]
        fn spaces_become_plus() {
            assert_eq!(encode_query_param("hello world"), "hello+world");
            assert_eq!(encode_query_param("  "), "++");
        }

        #[test]
        fn reserved_chars_unchanged() {
            assert_eq!(encode_query_param(";,/?:@&=+$#"), ";,/?:@&=+$#");
        }

        #[test]
        fn form_data_encoding() {
            assert_eq!(encode_query_param("John Doe"), "John+Doe");
            assert_eq!(encode_query_param("New York"), "New+York");
        }

        #[test]
        fn non_ascii_encoded() {
            assert_eq!(encode_query_param("naïve"), "na%c3%afve");
        }

        #[test]
        fn mixed_content() {
            assert_eq!(
                encode_query_param("value with spaces & special <chars>"),
                "value+with+spaces+&+special+%3cchars%3e"
            );
        }
    }

    mod comparison_tests {
        use super::*;

        #[test]
        fn encode_uri_vs_component_slash() {
            assert_eq!(encode_uri("/"), "/");
            assert_eq!(encode_uri_component("/"), "%2f");
        }

        #[test]
        fn encode_uri_vs_component_question() {
            assert_eq!(encode_uri("?"), "?");
            assert_eq!(encode_uri_component("?"), "%3f");
        }

        #[test]
        fn encode_uri_vs_component_ampersand() {
            assert_eq!(encode_uri("&"), "&");
            assert_eq!(encode_uri_component("&"), "%26");
        }

        #[test]
        fn encode_uri_vs_query_param_space() {
            assert_eq!(encode_uri(" "), "%20");
            assert_eq!(encode_uri_component(" "), "%20");
            assert_eq!(encode_query_param(" "), "+");
        }

        #[test]
        fn all_functions_same_on_alphanumeric() {
            let s = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
            assert_eq!(encode_uri(s), s);
            assert_eq!(encode_uri_component(s), s);
            assert_eq!(encode_query_param(s), s);
        }

        #[test]
        fn all_functions_same_on_unreserved() {
            let s = "-_.!~*'()";
            assert_eq!(encode_uri(s), s);
            assert_eq!(encode_uri_component(s), s);
            assert_eq!(encode_query_param(s), s);
        }
    }

    mod edge_cases {
        use super::*;

        #[test]
        fn percent_sign_encoded() {
            assert_eq!(encode_uri("%"), "%25");
            assert_eq!(encode_uri_component("%"), "%25");
            assert_eq!(encode_query_param("%"), "%25");
        }

        #[test]
        fn already_encoded_gets_double_encoded() {
            // This is correct behavior - we encode the input as-is
            assert_eq!(encode_uri("%20"), "%2520");
            assert_eq!(encode_uri_component("%20"), "%2520");
        }

        #[test]
        fn unicode_multi_byte() {
            // 3-byte UTF-8 character
            assert_eq!(encode_uri("€"), "%e2%82%ac");
            // 4-byte UTF-8 character (emoji)
            assert_eq!(encode_uri("🦀"), "%f0%9f%a6%80");
        }

        #[test]
        fn long_string() {
            let input = "a".repeat(10000);
            assert_eq!(encode_uri(&input), input);
        }

        #[test]
        fn many_encoded_chars() {
            let input = " ".repeat(1000);
            let expected_uri = "%20".repeat(1000);
            let expected_query = "+".repeat(1000);
            assert_eq!(encode_uri(&input), expected_uri);
            assert_eq!(encode_query_param(&input), expected_query);
        }
    }
}