urlable

A comprehensive URL manipulation library for Rust, providing utilities for parsing, encoding, and manipulating URLs.

Features

⚠️ Breaking Changes in 0.2.0

Warning: If you are upgrading from urlable 0.1.0 to 0.2.0, please be aware of the following breaking changes:

• Query string parsing now returns QueryObject instead of HashMap
• Query parameter values now use serde_json::Value type to support more complex data structures
• Some method names and signatures have changed for better API experience
• Removed several deprecated methods

Note: urlable 0.1.0 is no longer maintained. We strongly recommend upgrading to the latest 0.2.0 version for better functionality and security updates.

• 🔍 URL parsing and manipulation
• 🔒 Safe encoding/decoding of URL components
• 🧩 Query string handling
• 🌐 Punycode domain encoding
• 🛠 Path manipulation utilities

Installation

Add this to your Cargo.toml:

[dependencies]
urlable = "0.1.0"

Usage Examples

URL Parsing

use urlable::parse_url;

let url = parse_url("https://example.com/path?query=1#hash");
assert_eq!(url.protocol, Some("https".to_string()));
assert_eq!(url.pathname, "/path");
assert_eq!(url.search, "?query=1");
assert_eq!(url.hash, "#hash");

Query String Handling

use urlable::{parse_query, stringify_query};
use std::collections::HashMap;

// Parse query string
let query = parse_query::<HashMap<String, String>>("foo=bar&baz=qux");
assert_eq!(query.get("foo").unwrap(), "bar");

// Build query string
let mut query = HashMap::new();
query.insert("key".to_string(), "value".to_string());
let query_string = stringify_query(&query); // "key=value"

URL Encoding/Decoding

use urlable::{encode_path, decode_path, encode_query_value, decode_query_value};

// Path encoding
assert_eq!(encode_path("/path with spaces/"), "/path%20with%20spaces/");
assert_eq!(decode_path("/path%20with%20spaces/"), "/path with spaces/");

// Query value encoding
assert_eq!(encode_query_value("hello world"), "hello+world");
assert_eq!(decode_query_value("hello+world"), "hello world");

Path Manipulation

use urlable::{with_trailing_slash, without_trailing_slash, clean_double_slashes};

assert_eq!(with_trailing_slash("/path", false), "/path/");
assert_eq!(without_trailing_slash("/path/", false), "/path");
assert_eq!(clean_double_slashes("//path//to////file"), "/path/to/file");

Query String Processing

use urlable::{get_query, with_query};

// Parse query parameters
let query = get_query("https://example.com/path?foo=bar&baz=qux");
assert_eq!(query.get("foo").unwrap(), "bar");

// Build query string
let query = HashMap::new();
query.insert("key".to_string(), "value".to_string());
let query_string = with_query(&query); // "foo=bar&baz=qux"

API Reference

Parsing Functions

• parse_url(input: &str) -> ParsedURL
• parse_url_with_protocol(input: &str, proto: &str) -> ParsedURL
• parse_path(input: &str) -> ParsedURL
• parse_auth(input: &str) -> ParsedAuth
• parse_host(input: &str) -> ParsedHost

Encoding Functions

• encode(text: &str) -> String
• encode_hash(text: &str) -> String
• encode_query_value(input: &str) -> String
• encode_query_key(text: &str) -> String
• encode_path(text: &str) -> String
• encode_param(text: &str) -> String
• encode_host(text: &str) -> String

Decoding Functions

• decode(text: &str) -> String
• decode_path(text: &str) -> String
• decode_query_key(text: &str) -> String
• decode_query_value(text: &str) -> String

URL Manipulation Functions

• with_trailing_slash(input: &str, respect_query_fragment: bool) -> String
• without_trailing_slash(input: &str, respect_query_fragment: bool) -> String
• with_leading_slash(input: &str) -> String
• without_leading_slash(input: &str) -> String
• clean_double_slashes(input: &str) -> String
• join_url(base: &str, input: &str) -> String
• join_relative_url(inputs: &[&str]) -> String

Query String Functions

• parse_query<T: Default>(parameters_string: &str) -> T
• stringify_query(query: &QueryObject) -> String
• encode_query_item(key: &str, value: &QueryValue) -> String
• get_query(url: &str) -> QueryObject
• with_query(query: &QueryObject) -> String