# urlable

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

[![Crates.io](https://img.shields.io/crates/v/urlable.svg)](https://crates.io/crates/urlable)
[![Documentation](https://docs.rs/urlable/badge.svg)](https://docs.rs/urlable)
[![License](https://img.shields.io/crates/l/urlable.svg)](LICENSE)

## 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`:

```toml
[dependencies]
urlable = "0.1.0"
```

## Usage Examples

### URL Parsing

```rust
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

```rust
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

```rust
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

```rust
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

```rust
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`