### Build URIs Programmatically from Scheme

Source: https://context7.com/timothee-haudebourg/iref/llms.txt

Creates URIs programmatically starting from a scheme and then setting authority, path, query, and fragment. Demonstrates the use of predefined scheme constants.

```rust
use iref::{UriBuf, SchemeBuf, Scheme};
use iref::uri::{Authority, Path, Query, Fragment};

fn main() {
    // Create from scheme
    let scheme = SchemeBuf::new(b"https".to_vec()).unwrap();
    let mut uri = UriBuf::from_scheme(scheme);
    assert_eq!(uri, "https:");

    // Build up the URI
    uri.set_authority(Some(Authority::new("api.example.com").unwrap()));
    uri.set_path(Path::new("/v1/users").unwrap());
    uri.set_query(Some(Query::new("page=1").unwrap()));
    uri.set_fragment(Some(Fragment::new("top").unwrap()));

    assert_eq!(uri, "https://api.example.com/v1/users?page=1#top");

    // Use predefined scheme constants
    assert_eq!(Scheme::HTTPS, "https");
    assert_eq!(Scheme::HTTP, "http");
    assert_eq!(Scheme::FILE, "file");
}
```

--------------------------------

### Create and convert IRI references in Rust

Source: https://github.com/timothee-haudebourg/iref/blob/main/README.md

Demonstrates initializing an IriRefBuf, setting a scheme, and converting between Iri and IriRef types.

```rust
let mut iri_ref = IriRefBuf::default(); // an IRI reference can be empty.

// An IRI reference with a scheme is a valid IRI.
iri_ref.set_scheme(Some("https".try_into()?));
let iri: &Iri = iri_ref.as_iri().unwrap();

// An IRI can be safely converted into an IRI reference.
let iri_ref: &IriRef = iri.into();
```

--------------------------------

### Compare URIs with Normalization and Percent-Encoding

Source: https://context7.com/timothee-haudebourg/iref/llms.txt

Compares URIs after path normalization and correct percent-encoding handling. Suitable for use in HashMaps and other collections.

```rust
use iref::Uri;
use std::collections::HashSet;

fn main() {
    // Path normalization in comparison
    let a = Uri::new("http://example.org/a/b/c").unwrap();
    let b = Uri::new("http://example.org/a/../a/./b/../b/c").unwrap();
    assert_eq!(a, b);  // Equal after normalization

    // Percent-encoded characters are handled correctly
    let c = Uri::new("http://example.org").unwrap();
    let d = Uri::new("http://exa%6dple.org").unwrap();  // %6d = 'm'
    assert_eq!(c, d);

    // Use in collections
    let mut seen = HashSet::new();
    seen.insert(a.to_owned());

    // The normalized equivalent is found
    assert!(seen.contains(b));
}
```

--------------------------------

### Create and Modify IRI with IriBuf

Source: https://github.com/timothee-haudebourg/iref/blob/main/README.md

Utilize `IriBuf` for mutable IRI manipulation within a single buffer, reducing allocations. Use `try_into` to ensure syntactic correctness of components.

```rust
use iref::IriBuf;

let mut iri = IriBuf::new("https://www.rust-lang.org".to_string())?;

iri.authority_mut().unwrap().set_port(Some("40".try_into()?));
iri.set_path("/foo".try_into()?);
iri.path_mut().push("bar".try_into()?);
iri.set_query(Some("query".try_into()?));
iri.set_fragment(Some("fragment".try_into()?));

assert_eq!(iri, "https://www.rust-lang.org:40/foo/bar?query#fragment");
```

--------------------------------

### Serialize and deserialize with Serde

Source: https://context7.com/timothee-haudebourg/iref/llms.txt

Enable the serde feature to integrate iref types into data structures for JSON serialization.

```rust
use iref::{IriBuf, IriRef};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Resource {
    iri: IriBuf,
}

#[derive(Debug, Serialize, Deserialize)]
struct Link<'a> {
    #[serde(borrow)]
    iri_ref: &'a IriRef,
}

fn main() {
    // Deserialize owned IRI
    let resource: Resource = serde_json::from_str(
        r#"{ "iri": "https://example.org/foo" }"#
    ).unwrap();
    assert_eq!(resource.iri.scheme(), "https");

    // Deserialize borrowed IRI reference
    let link: Link = serde_json::from_str(
        r#"{ "iri_ref": "../bar" }"#
    ).unwrap();
    assert!(link.iri_ref.scheme().is_none());

    // Serialize back to JSON
    let json = serde_json::to_string(&resource).unwrap();
    assert!(json.contains("https://example.org/foo"));
}
```

--------------------------------

### Parse URIs at compile time

Source: https://context7.com/timothee-haudebourg/iref/llms.txt

Use uri! and iri! macros to validate URIs during compilation, preventing runtime errors.

```rust
use iref::{uri, iri, Uri, Iri};

// Parse at compile time - invalid URIs cause compilation errors
const EXAMPLE_URI: &Uri = uri!("https://example.org/path");
const EXAMPLE_IRI: &Iri = iri!("https://example.org/日本語");

fn main() {
    assert_eq!(EXAMPLE_URI.scheme(), "https");
    assert_eq!(EXAMPLE_IRI.path(), "/日本語");

    // Also works in regular code
    let uri = uri!("https://api.example.com/v1/users");
    assert_eq!(uri.authority().unwrap().host(), "api.example.com");
}
```

--------------------------------

### Manipulate URI paths

Source: https://context7.com/timothee-haudebourg/iref/llms.txt

Iterate, modify, and normalize URI path segments using IriBuf.

```rust
use iref::{IriBuf, IriError};
use std::borrow::Cow;

fn main() -> Result<(), IriError<Cow<'static, str>>> {
    let mut iri = IriBuf::new("https://rust-lang.org/a/c".to_string())?;

    // Get path segments
    for segment in iri.path().segments() {
        println!("{}", segment);
    }

    // Manipulate path segments
    let mut path = iri.path_mut();
    path.pop();                          // Remove "c"
    path.push("b".try_into()?);         // Add "b"
    path.push("c".try_into()?);         // Add "c"
    path.push("".try_into()?);          // Add trailing slash

    assert_eq!(iri.path(), "/a/b/c/");

    // Path normalization (removes . and .. segments)
    let mut iri2 = IriBuf::new("https://example.org/a/b/../c/./d".to_string())?;
    iri2.path_mut().normalize();
    assert_eq!(iri2.path(), "/a/c/d");

    // Iterate normalized segments without modifying the path
    let path = iref::uri::Path::new("/foo/bar/../baz").unwrap();
    let segments: Vec<_> = path.normalized_segments().map(|s| s.as_str()).collect();
    assert_eq!(segments, vec!["foo", "baz"]);

    Ok(())
}
```

--------------------------------

### Access and modify authority components

Source: https://context7.com/timothee-haudebourg/iref/llms.txt

Manage host, port, and user info within URI authority components.

```rust
use iref::{UriBuf, Uri};
use iref::uri::{Authority, Host};

fn main() {
    let uri = Uri::new("https://user:pass@example.org:8080/path").unwrap();

    // Access authority components
    let authority = uri.authority().unwrap();
    assert_eq!(authority.host(), "example.org");
    assert_eq!(authority.port().unwrap(), "8080");
    assert_eq!(authority.user_info().unwrap(), "user:pass");

    // Modify authority in a buffer
    let mut uri_buf = UriBuf::new("https://example.org:8080/path".to_string()).unwrap();

    if let Some(mut authority) = uri_buf.authority_mut() {
        authority.set_host("other.com".try_into().unwrap());
        authority.set_port(Some("443".try_into().unwrap()));
    }

    assert_eq!(uri_buf, "https://other.com:443/path");

    // Set or remove authority entirely
    let mut uri_buf2 = UriBuf::new("https://example.org/path".to_string()).unwrap();
    uri_buf2.set_authority(Some(Authority::new("newhost.com").unwrap()));
    assert_eq!(uri_buf2, "https://newhost.com/path");
}
```

--------------------------------

### Create and Modify Owned URI Buffers in Rust

Source: https://context7.com/timothee-haudebourg/iref/llms.txt

Utilize `IriBuf` or `UriBuf` for owned, mutable URIs. These buffers allow in-place modifications to minimize allocations and provide methods for setting individual components.

```rust
use std::borrow::Cow;
use iref::{IriBuf, IriError};

fn main() -> Result<(), IriError<Cow<'static, str>>> {
    let mut iri = IriBuf::new("https://www.rust-lang.org".to_string())?;

    // Modify the authority's port
    iri.authority_mut()
        .unwrap()
        .set_port(Some("40".try_into()?));

    // Set the path
    iri.set_path("/foo".try_into()?);

    // Append a path segment
    iri.path_mut().push("bar".try_into()?);

    // Set query and fragment
    iri.set_query(Some("query".try_into()?));
    iri.set_fragment(Some("fragment".try_into()?));

    assert_eq!(iri, "https://www.rust-lang.org:40/foo/bar?query#fragment");
    Ok(())
}
```

--------------------------------

### Parse and Access IRI Components

Source: https://github.com/timothee-haudebourg/iref/blob/main/README.md

Use `Iri::new` to parse an IRI string slice without memory allocation. Access components like scheme, authority, path, query, and fragment.

```rust
use iref::Iri;

let iri = Iri::new("https://www.rust-lang.org/foo/bar?query#frag")?;

println!("scheme: {}", iri.scheme());
println!("authority: {}", iri.authority().unwrap());
println!("path: {}", iri.path());
println!("query: {}", iri.query().unwrap());
println!("fragment: {}", iri.fragment().unwrap());
```

--------------------------------

### Parse URI/IRI Components in Rust

Source: https://context7.com/timothee-haudebourg/iref/llms.txt

Use `Iri::new` or `Uri::new` to parse a URI or IRI string and access its components. This method validates the input and returns a borrowed reference without memory allocation.

```rust
use iref::{Iri, IriError};

fn main() -> Result<(), IriError<&'static str>> {
    let iri = Iri::new("https://www.rust-lang.org/foo/bar?query#frag")?;

    println!("scheme: {}", iri.scheme());           // "https"
    println!("authority: {}", iri.authority().unwrap()); // "www.rust-lang.org"
    println!("path: {}", iri.path());               // "/foo/bar"
    println!("query: {}", iri.query().unwrap());    // "query"
    println!("fragment: {}", iri.fragment().unwrap()); // "frag"

    Ok(())
}
```

--------------------------------

### Resolve Relative URI References in Rust

Source: https://context7.com/timothee-haudebourg/iref/llms.txt

Resolve relative URI references against a base URI using the RFC 3986 algorithm. This is crucial for processing links within documents. Both non-mutating and in-place resolution methods are available.

```rust
use std::borrow::Cow;
use iref::{Iri, IriError, IriRefBuf};

fn main() -> Result<(), IriError<Cow<'static, str>>> {
    let base_iri = Iri::new("http://a/b/c/d;p?q")?;
    let mut iri_ref = IriRefBuf::new("g;x=1/../y".to_string())?;

    // Non-mutating resolution returns a new IRI
    assert_eq!(iri_ref.resolved(base_iri), "http://a/b/c/y");

    // In-place resolution modifies the reference
    iri_ref.resolve(base_iri);
    assert_eq!(iri_ref, "http://a/b/c/y");

    // Join a reference to a base URI
    let base = Iri::new("https://example.org/foo/bar")?;
    let reference = iref::IriRef::new("../baz")?;
    assert_eq!(base.joined(reference), "https://example.org/baz");

    Ok(())
}
```

--------------------------------

### Compute relative URIs

Source: https://context7.com/timothee-haudebourg/iref/llms.txt

Calculate the relative path between two URIs using the relative_to method.

```rust
use iref::UriRef;

fn main() {
    let base = UriRef::new("https://example.org/foo/bar").unwrap();
    let target = UriRef::new("https://example.org/foo/baz").unwrap();

    // Compute relative path from base to target
    assert_eq!(target.relative_to(base), "baz");

    // Works with parent directories
    let other = UriRef::new("https://example.org/other").unwrap();
    assert_eq!(other.relative_to(base), "../other");

    // Different schemes return the full URI
    let different_scheme = UriRef::new("http://example.org/foo").unwrap();
    assert_eq!(different_scheme.relative_to(base), "http://example.org/foo");
}
```

--------------------------------

### Manipulate IRI Path Segments with IriBuf

Source: https://github.com/timothee-haudebourg/iref/blob/main/README.md

Modify an IRI's path by pushing, popping, or adding segments using `path_mut`. This allows in-place modification of the path, including handling empty segments.

```rust
let mut iri = IriBuf::new("https://rust-lang.org/a/c".to_string())?;
let mut path = iri.path_mut();

path.pop();
path.push("b".try_into()?);
path.push("c".try_into()?);
path.push("".try_into()?); // the empty segment is valid.

assert_eq!(iri.path(), "/a/b/c/");
```

--------------------------------

### Resolve IRI references against a base IRI in Rust

Source: https://github.com/timothee-haudebourg/iref/blob/main/README.md

Shows both non-mutating and in-place resolution of relative IRI references using a base IRI.

```rust
let base_iri = Iri::new("http://a/b/c/d;p?q")?;
let mut iri_ref = IriRefBuf::new("g;x=1/../y".to_string())?;

// non mutating resolution.
assert_eq!(iri_ref.resolved(base_iri), "http://a/b/c/y");

// in-place resolution.
iri_ref.resolve(base_iri);
assert_eq!(iri_ref, "http://a/b/c/y");
```

--------------------------------

### Handle Absolute and Relative IRI References in Rust

Source: https://context7.com/timothee-haudebourg/iref/llms.txt

Use `IriRefBuf` to manage both absolute IRIs and relative references. This snippet demonstrates creating an empty reference, converting it to an IRI, and checking the type of a reference.

```rust
use iref::{Iri, IriRef, IriRefBuf};

fn main() {
    // Create an empty IRI reference
    let mut iri_ref = IriRefBuf::default();

    // Add a scheme to convert it to a valid IRI
    iri_ref.set_scheme(Some("https".try_into().unwrap()));
    let iri: &Iri = iri_ref.as_iri().unwrap();

    // An IRI can be safely converted into an IRI reference
    let _iri_ref: &IriRef = iri.into();

    // Check if a reference is relative or absolute
    let relative = IriRef::new("/path/to/resource").unwrap();
    assert!(relative.scheme().is_none());

    let absolute = IriRef::new("https://example.org/path").unwrap();
    assert!(absolute.scheme().is_some());
}
```

--------------------------------

### Iterate Over IRI Path Segments

Source: https://github.com/timothee-haudebourg/iref/blob/main/README.md

Access individual segments of an IRI's path using the `segments` iterator. This method provides access to each part of the path.

```rust
for segment in iri.path().segments() {
  println!("{}", segment);
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.