### map_fragment with Example Setting New Fragment

Source: https://docs.rs/uriparse/latest/uriparse/relative_reference/struct.RelativeReference.html

Maps the fragment using the provided function. The example sets the fragment to "fragment" and asserts the resulting string starts with an absolute path.

```rust
use std::convert::TryFrom;

use uriparse::{Fragment, RelativeReference};

let mut reference = RelativeReference::try_from("/").unwrap();
reference.map_fragment(|_| Some(Fragment::try_from("fragment").unwrap()));
assert_eq!(reference.to_string(), "/#fragment");
```

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

### map_query with Example Sets Query

Source: https://docs.rs/uriparse/latest/uriparse/relative_reference/struct.RelativeReference.html

Maps the query with the given function. The example replaces an existing query with "query" on a relative reference starting with "/path".

```rust
use std::convert::TryFrom;

use uriparse::{Query, RelativeReference};

let mut reference = RelativeReference::try_from("/path").unwrap();
reference.map_query(|_| Some(Query::try_from("query").unwrap()));
assert_eq!(reference.to_string(), "/path?query");
```

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

### host() example

Source: https://docs.rs/uriparse/latest/src/uriparse/uri_reference.rs.html

Returns the host component of a URI reference. The example extracts the host from a URI with a username.

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://username@example.com").unwrap();
assert_eq!(reference.host().unwrap().to_string(), "example.com");
```

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

### Get host component with host

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Authority.html

Retrieves the host component using host. The example parses an authority with a host and asserts the host string equals "example.com".

```rust
use std::convert::TryFrom;

use uriparse::Authority;

let authority = Authority::try_from("username:password@example.com").unwrap();
assert_eq!(authority.host().to_string().as_str(), "example.com");

```

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

### path Getter Example

Source: https://docs.rs/uriparse/latest/uriparse/relative_reference/struct.RelativeReference.html

Returns the path component. The example asserts that the path of "/my/path" is "/my/path".

```rust
use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("/my/path").unwrap();
assert_eq!(reference.path(), "/my/path");
```

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

### set_password example

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Authority.html

Sets the password of the authority. The example shows that setting a password adds a ':' before the password and an '@' after it.

```rust
use std::convert::TryFrom;

use uriparse::Authority;

let mut authority = Authority::try_from("example.com").unwrap();
authority.set_password(Some("secret"));
assert_eq!(authority.to_string(), ":secret@example.com");
```

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

### Username::normalize example

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Username.html

Shows normalize() in action: it percent-decodes unreserved characters and uppercases hex digits in percent-encodings. The example asserts the before and after values.

```rust
use std::convert::TryFrom;

use uriparse::Username;

let mut username = Username::try_from("username").unwrap();
username.normalize();
assert_eq!(username, "username");

let mut username = Username::try_from("%ff%41").unwrap();
assert_eq!(username, "%ff%41");
username.normalize();
assert_eq!(username, "%FFA");
```

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

### Fragment::as_str usage example

Source: https://docs.rs/uriparse/latest/src/uriparse/fragment.rs.html

Shows how to create a Fragment from a string using TryFrom and retrieve its string representation with as_str(). The example asserts that the returned string equals the original input.

```rust
use std::convert::TryFrom;

use uriparse::Fragment;

let fragment = Fragment::try_from("fragment").unwrap();
assert_eq!(fragment.as_str(), "fragment");
```

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

### fragment() method example

Source: https://docs.rs/uriparse/latest/src/uriparse/uri_reference.rs.html

Shows how to retrieve the fragment component from a URI reference using the fragment() method. The example parses "http://example.com#fragment" and asserts the fragment equals "fragment".

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://example.com#fragment").unwrap();
assert_eq!(reference.fragment().unwrap(), "fragment");
```

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

### is_provisional example

Source: https://docs.rs/uriparse/latest/uriparse/scheme/enum.SchemeStatus.html

Checks whether a scheme's status is provisional. The example asserts that Git is provisional and RTSP is not.

```rust
use uriparse::Scheme;

assert_eq!(Scheme::Git.status().is_provisional(), true);
assert_eq!(Scheme::RTSP.status().is_provisional(), false);
```

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

### into_builder() example

Source: https://docs.rs/uriparse/latest/src/uriparse/uri_reference.rs.html

Converts a URI reference into a builder, modifies the query and fragment, and rebuilds the reference. The example removes the query and fragment, resulting in a URI without them.

```rust
use std::convert::TryFrom;

use uriparse::{Fragment, Query, URIReference};

let reference = URIReference::try_from("//example.com/path?query#fragment").unwrap();
let mut builder = reference.into_builder();
builder.query(None::<Query>).fragment(None::<Fragment>);
let reference = builder.build().unwrap();
assert_eq!(reference.to_string(), "//example.com/path");
```

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

### host: Get host from relative reference

Source: https://docs.rs/uriparse/latest/uriparse/relative_reference/struct.RelativeReference.html

Returns the host of a relative reference as an `Option<&Host>`. The example parses a URI with a host and asserts the host string equals "example.com".

```rust
use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//username@example.com").unwrap();
assert_eq!(reference.host().unwrap().to_string(), "example.com");
```

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

### set_host example

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Authority.html

Sets the host of the authority. The example shows setting an IPv4 address and an IPv6 address, with the IPv6 address being bracketed in the resulting string.

```rust
use std::convert::TryFrom;
use std::net::Ipv6Addr;

use uriparse::{Authority, Host};

let mut authority = Authority::try_from("example.com:8080").unwrap();
authority.set_host("127.0.0.1");
assert_eq!(authority.to_string(), "127.0.0.1:8080");
authority.set_host(Host::IPv6Address("::1".parse().unwrap()));
assert_eq!(authority.to_string(), "[::1]:8080");
```

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

### map_query example

Source: https://docs.rs/uriparse/latest/uriparse/uri_reference/struct.URIReference.html

Maps the query using a closure. The example sets the query to 'query'.

```rust
use std::convert::TryFrom;

use uriparse::{Query, URIReference};

let mut reference = URIReference::try_from("http://example.com").unwrap();
reference.map_query(|_| Some(Query::try_from("query").unwrap()));
assert_eq!(reference.to_string(), "http://example.com/?query");
```

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

### trim_prefix nightly-only example

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Shows how to use the nightly-only trim_prefix method, which returns &str instead of Option<&str> for easy chaining. Requires the trim_prefix_suffix feature gate. The example also demonstrates chaining trim_prefix and trim_suffix.

```rust
#![feature(trim_prefix_suffix)]

// Prefix present - removes it
assert_eq!("foo:bar".trim_prefix("foo:"), "bar");
assert_eq!("foofoo".trim_prefix("foo"), "foo");

// Prefix absent - returns original string
assert_eq!("foo:bar".trim_prefix("bar"), "foo:bar");

// Method chaining example
assert_eq!("<https://example.com/>".trim_prefix('<').trim_suffix('>'), "https://example.com/");
```

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

### port example

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Authority.html

Retrieves the port component of the authority. The example shows that the port is parsed as a u16.

```rust
use std::convert::TryFrom;

use uriparse::Authority;

let authority = Authority::try_from("example.com:80").unwrap();
assert_eq!(authority.port().unwrap(), 80);
```

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

### Authority::host example

Source: https://docs.rs/uriparse/latest/src/uriparse/authority.rs.html

Returns the host component of the authority. The example parses "username:password@example.com" and asserts the host string is "example.com".

```rust
use std::convert::TryFrom;

use uriparse::Authority;

let authority = Authority::try_from("username:password@example.com").unwrap();
assert_eq!(authority.host().to_string().as_str(), "example.com");
```

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

### map_scheme example

Source: https://docs.rs/uriparse/latest/uriparse/uri_reference/struct.URIReference.html

Maps the scheme using a closure. The example changes the scheme to 'https'. Panics if the resulting URI reference becomes invalid.

```rust
use std::convert::TryFrom;

use uriparse::{Scheme, URIReference};

let mut reference = URIReference::try_from("http://example.com").unwrap();
reference.map_scheme(|_| Some(Scheme::try_from("https").unwrap()));
assert_eq!(reference.to_string(), "https://example.com/");
```

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

### char_indices() examples

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Shows how to iterate over character indices of a string slice. The first example counts characters and walks through each index. The second example demonstrates that combining characters occupy multiple bytes, so indices are not always sequential.

```rust
let word = "goodbye";

let count = word.char_indices().count();
assert_eq!(7, count);

let mut char_indices = word.char_indices();

assert_eq!(Some((0, 'g')), char_indices.next());
assert_eq!(Some((1, 'o')), char_indices.next());
assert_eq!(Some((2, 'o')), char_indices.next());
assert_eq!(Some((3, 'd')), char_indices.next());
assert_eq!(Some((4, 'b')), char_indices.next());
assert_eq!(Some((5, 'y')), char_indices.next());
assert_eq!(Some((6, 'e')), char_indices.next());

assert_eq!(None, char_indices.next());
```

```rust
let yes = "y̆es";

let mut char_indices = yes.char_indices();

assert_eq!(Some((0, 'y')), char_indices.next()); // not (0, 'y̆')
assert_eq!(Some((1, '\u{0306}')), char_indices.next());

// note the 3 here - the previous character took up two bytes
assert_eq!(Some((3, 'e')), char_indices.next());
assert_eq!(Some((4, 's')), char_indices.next());

assert_eq!(None, char_indices.next());
```

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

### query Getter Example

Source: https://docs.rs/uriparse/latest/uriparse/relative_reference/struct.RelativeReference.html

Returns the query if present. The example parses a relative reference with a query "my=query" and asserts the result.

```rust
use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("?my=query").unwrap();
assert_eq!(reference.query().unwrap(), "my=query");
```

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

### password example

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Authority.html

Retrieves the password component of the authority. The example shows that the password is the part after the ':' and before the '@'.

```rust
use std::convert::TryFrom;

use uriparse::Authority;

let authority = Authority::try_from("username:password@example.com").unwrap();
assert_eq!(authority.password().unwrap(), "password");
```

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

### map_path with Example Builds Path

Source: https://docs.rs/uriparse/latest/uriparse/relative_reference/struct.RelativeReference.html

Maps the path; panics if the change makes the reference invalid. The example pushes two segments onto an initially empty path, resulting in "test/path".

```rust
use std::convert::TryFrom;

use uriparse::{Authority, URIReference};

let mut reference = URIReference::try_from("").unwrap();
reference.map_path(|mut path| {
    path.push("test").unwrap();
    path.push("path").unwrap();
    path
});
assert_eq!(reference.to_string(), "test/path");
```

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

### map_host example

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Authority.html

Maps the host of an authority using a closure. The closure receives the current host and returns a new host. The example replaces the host with an IPv4 address and verifies the resulting string.

```rust
use std::convert::TryFrom;

use uriparse::{Authority, Host};

let mut authority = Authority::try_from("example.com").unwrap();
authority.map_host(|_| Host::try_from("127.0.0.1").unwrap());
assert_eq!(authority.to_string(), "127.0.0.1");
```

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

### port Getter Example

Source: https://docs.rs/uriparse/latest/uriparse/relative_reference/struct.RelativeReference.html

Returns the port number if present. The example parses a URI with port 8080 and asserts the value.

```rust
use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//example.com:8080/").unwrap();
assert_eq!(reference.port().unwrap(), 8080);
```

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

### str::word_to_titlecase examples

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Shows the behavior of `str::word_to_titlecase` (nightly-only). The blocks demonstrate basic usage, first cased letter uppercasing, languages without case, Georgian uppercase not used, no word segmentation, and tricky sigma examples.

```rust
#![feature(titlecase)]
let s = "HELLO WORLD";

assert_eq!("Hello world", s.word_to_titlecase());
```

```rust
#![feature(titlecase)]
let the_night_before_christmas = "'twas";

assert_eq!("'Twas", the_night_before_christmas.word_to_titlecase());
```

```rust
#![feature(titlecase)]
let new_year = "农历新年";

assert_eq!(new_year, new_year.word_to_titlecase());
```

```rust
#![feature(titlecase)]
let georgian = "ერთობაშია";

assert_eq!(georgian, georgian.word_to_titlecase());
```

```rust
#![feature(titlecase)]
let blazingly_fast = "ferris and I";

assert_eq!("Ferris and i", blazingly_fast.word_to_titlecase());
```

```rust
#![feature(titlecase)]
let odysseus = "ὈΔΥΣΣΕΎΣ";

assert_eq!("Ὀδυσσεύς", odysseus.word_to_titlecase());

let odysseus_king_of_ithaca = "Ο ΟΔΥΣΣΈΑΣ ΒΑΣΙΛΙΆΣ ΤΗΣ ΙΘΆΚΗΣ";
```

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

### has_fragment() method example

Source: https://docs.rs/uriparse/latest/src/uriparse/uri_reference.rs.html

Shows checking for a fragment component. The example parses "#test" (true) and "http://example.com" (false).

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("#test").unwrap();
assert!(reference.has_fragment());

let reference = URIReference::try_from("http://example.com").unwrap();
assert!(!reference.has_fragment());
```

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

### try_scheme example: set scheme on URIBuilder

Source: https://docs.rs/uriparse/latest/uriparse/uri/struct.URIBuilder.html

Sets the scheme part of the URI. The scheme is required; not setting it results in an error during build. The example builds a URI with scheme and path, resulting in 'urn:path'.

```rust
use std::convert::TryFrom;

use uriparse::{Path, Scheme, URIBuilder};

let mut builder = URIBuilder::new();
builder
    .try_scheme("urn")
    .unwrap()
    .try_path("path")
    .unwrap();
let uri = builder.build().unwrap();
assert_eq!(uri.to_string(), "urn:path");
```

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

### trim_suffix nightly-only example

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Shows how to use the nightly-only trim_suffix method, which returns &str instead of Option<&str> for easy chaining. Requires the trim_prefix_suffix feature gate. The example demonstrates that a non-matching suffix returns the original string.

```rust
#![feature(trim_prefix_suffix)]

// Suffix present - removes it
assert_eq!("bar:foo".trim_suffix(":foo"), "bar");
assert_eq!("foofoo".trim_suffix("foo"), "foo");

// Suffix absent - returns original string
assert_eq!("bar:foo".trim_suffix("bar"), "bar:foo");
```

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

### has_password() method example

Source: https://docs.rs/uriparse/latest/src/uriparse/uri_reference.rs.html

Demonstrates checking for a password in the authority. The example parses "http://user:pass@127.0.0.1" (true) and "http://user@127.0.0.1" (false).

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://user:pass@127.0.0.1").unwrap();
assert!(reference.has_password());

let reference = URIReference::try_from("http://user@127.0.0.1").unwrap();
assert!(!reference.has_password());
```

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

### map_port example

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Authority.html

Maps the port of an authority using a closure. The closure receives the current port (as an Option) and returns a new port. The example sets port 8080 and verifies the resulting string includes the port.

```rust
use std::convert::TryFrom;

use uriparse::Authority;

let mut authority = Authority::try_from("example.com").unwrap();
authority.map_port(|_| Some(8080));
assert_eq!(authority.to_string(), "example.com:8080");
```

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

### Segment::empty Example

Source: https://docs.rs/uriparse/latest/src/uriparse/path.rs.html

Demonstrates the creation of an empty Segment.

```rust
use uriparse::Segment;

assert_eq!(Segment::empty(),  "");
```

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

### has_port() method example

Source: https://docs.rs/uriparse/latest/src/uriparse/uri_reference.rs.html

Shows checking for a port in the authority. The example parses "http://127.0.0.1:8080" (true) and "http://127.0.0.1" (false).

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://127.0.0.1:8080").unwrap();
assert!(reference.has_port());

let reference = URIReference::try_from("http://127.0.0.1").unwrap();
assert!(!reference.has_port());
```

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

### is_relative_reference example

Source: https://docs.rs/uriparse/latest/uriparse/uri_reference/struct.URIReference.html

Checks if a URI reference is a relative reference (no scheme). The example uses a path starting with a slash.

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("/my/path").unwrap();
assert!(reference.is_relative_reference());
```

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

### Set path with Path::try_from

Source: https://docs.rs/uriparse/latest/uriparse/relative_reference/struct.RelativeReferenceBuilder.html

Example for the path method, showing how to set the required path and build the reference.

```rust
use std::convert::TryFrom;

use uriparse::{Path, RelativeReferenceBuilder};

let mut builder = RelativeReferenceBuilder::new();
builder
    .path(Path::try_from("/my/path").unwrap());
let reference = builder.build().unwrap();
assert_eq!(reference.to_string(), "/my/path");
```

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

### Set query with Query::try_from

Source: https://docs.rs/uriparse/latest/uriparse/relative_reference/struct.RelativeReferenceBuilder.html

Example for the query method, showing how to set a query and build the reference.

```rust
use std::convert::TryFrom;

use uriparse::{Path, Query, RelativeReferenceBuilder};

let mut builder = RelativeReferenceBuilder::new();
builder
    .path(Path::try_from("/my/path").unwrap())
    .query(Some(Query::try_from("query").unwrap()));
let reference = builder.build().unwrap();
assert_eq!(reference.to_string(), "/my/path?query");
```

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

### Get subslice with str::get

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Gets a subslice of a string using `get()` with a range. The example shows that valid ranges return `Some` with the subslice, while ranges that are not on UTF-8 boundaries or are out of bounds return `None`.

```rust
let v = String::from("🗻∈🌏");

assert_eq!(Some("🗻"), v.get(0..4));

// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());

// out of bounds
assert!(v.get(..42).is_none());
```

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

### starts_with() with &str

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Shows checking if a string starts with a prefix.

```rust
let bananas = "bananas";

assert!(bananas.starts_with("bana"));
assert!(!bananas.starts_with("nana"));
```

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

### Get URI authority

Source: https://docs.rs/uriparse/latest/uriparse/uri/struct.URI.html

Shows how to get the authority component of a URI using the authority() method. The example parses a URI with a port and asserts the authority string.

```rust
use std::convert::TryFrom;

use uriparse::URI;

let uri = URI::try_from("http://example.com:80/my/path").unwrap();
assert_eq!(uri.authority().unwrap().to_string(), "example.com:80");
```

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

### RegisteredName::normalize usage

Source: https://docs.rs/uriparse/latest/src/uriparse/authority.rs.html

Example showing the initialization of a RegisteredName for normalization.

```rust
use std::convert::TryFrom;

use uriparse::RegisteredName;

let mut name = RegisteredName::try_from("example.com").unwrap();
```

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

### try_path example: set path on URIBuilder

Source: https://docs.rs/uriparse/latest/uriparse/uri/struct.URIBuilder.html

Sets the path part of the URI. The path is required; if conversion fails, the error is stored and checked during build. The example builds a URI with scheme and path, resulting in 'urn:path'.

```rust
use uriparse::URIBuilder;

let mut builder = URIBuilder::new();
builder
    .try_scheme("urn")
    .unwrap()
    .try_path("path")
    .unwrap();
let uri = builder.build().unwrap();
assert_eq!(uri.to_string(), "urn:path");
```

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

### Path::is_relative example

Source: https://docs.rs/uriparse/latest/uriparse/path/struct.Path.html

Checks if the path is relative, meaning it does not start with a '/'.

```rust
use std::convert::TryFrom;

use uriparse::Path;

let path = Path::try_from("my/path").unwrap();
assert_eq!(path.is_relative(), true);
```

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

### Query::as_str example

Source: https://docs.rs/uriparse/latest/src/uriparse/query.rs.html

Shows how to create a Query from a string and retrieve its string representation using as_str.

```rust
use std::convert::TryFrom;

use uriparse::Query;

let query = Query::try_from("query").unwrap();
assert_eq!(query.as_str(), "query");
```

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

### try_query example: set query on URIBuilder

Source: https://docs.rs/uriparse/latest/uriparse/uri/struct.URIBuilder.html

Sets the query part of the URI. The query is optional; if conversion fails, the error is stored and checked during build. The example builds a URI with scheme, path, and query, resulting in 'urn:path?query'.

```rust
use uriparse::URIBuilder;

let mut builder = URIBuilder::new();
builder
    .try_scheme("urn")
    .unwrap()
    .try_path("path")
    .unwrap()
    .try_query(Some("query"))
    .unwrap();
let uri = builder.build().unwrap();
assert_eq!(uri.to_string(), "urn:path?query");
```

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

### map_password example

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Authority.html

Maps the password of an authority using a closure. The closure receives the current password (as an Option) and returns a new password. The example sets a password and verifies the resulting string includes the password and an '@'.

```rust
use std::convert::TryFrom;

use uriparse::{Authority, Password};

let mut authority = Authority::try_from("example.com").unwrap();
authority.map_password(|_| Some(Password::try_from("password").unwrap()));
assert_eq!(authority.to_string(), ":password@example.com");
```

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

### password Getter Example (Deprecated Usage)

Source: https://docs.rs/uriparse/latest/uriparse/relative_reference/struct.RelativeReference.html

Returns the password if present. Usage of passwords in URIs is deprecated. The example extracts "pass" from a userinfo containing both user and password.

```rust
use std::convert::TryFrom;

use uriparse::RelativeReference;

let reference = RelativeReference::try_from("//user:pass@example.com").unwrap();
assert_eq!(reference.password().unwrap(), "pass");
```

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

### Set fragment with Fragment::try_from

Source: https://docs.rs/uriparse/latest/uriparse/relative_reference/struct.RelativeReferenceBuilder.html

Example for the fragment method, showing how to set a fragment and build the reference.

```rust
use std::convert::TryFrom;

use uriparse::{Fragment, Path, RelativeReferenceBuilder};

let mut builder = RelativeReferenceBuilder::new();
builder
    .path(Path::try_from("/my/path").unwrap())
    .fragment(Some(Fragment::try_from("fragment").unwrap()));
let reference = builder.build().unwrap();
assert_eq!(reference.to_string(), "/my/path#fragment");
```

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

### Path::is_absolute example

Source: https://docs.rs/uriparse/latest/uriparse/path/struct.Path.html

Checks if the path is absolute, meaning it starts with a '/'.

```rust
use std::convert::TryFrom;

use uriparse::Path;

let path = Path::try_from("/my/path").unwrap();
assert_eq!(path.is_absolute(), true);
```

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

### map_username example

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Authority.html

Maps the username of an authority using a closure. The closure receives the current username (as an Option) and returns a new username. The example sets a username and verifies the resulting string includes the username and an '@'.

```rust
use std::convert::TryFrom;

use uriparse::{Authority, Username};

let mut authority = Authority::try_from("example.com").unwrap();
authority.map_username(|_| Some(Username::try_from("username").unwrap()));
assert_eq!(authority.to_string(), "username@example.com");
```

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

### into_parts example

Source: https://docs.rs/uriparse/latest/uriparse/uri_reference/struct.URIReference.html

Consumes the URI reference and returns its parts: scheme, authority, path, query, and fragment. Asserts each part's value.

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from(
    "http://username:password@example.com:80/my/path?my=query#fragment",
).unwrap();
let (scheme, authority, path, query, fragment) = reference.into_parts();

assert_eq!(scheme.unwrap(), "http");
assert_eq!(authority.unwrap().to_string(), "username:password@example.com:80");
assert_eq!(path, "/my/path");
assert_eq!(query.unwrap(), "my=query");
assert_eq!(fragment.unwrap(), "fragment");
```

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

### str::find examples: simple, closure, and no-match patterns

Source: https://docs.rs/uriparse/latest/uriparse/path/struct.Segment.html

Shows `str::find` returning the byte index of the first match for simple patterns (`char`, `&str`), for closures and point-free style, and for a slice of `char`s that does not match. The examples use non-ASCII characters to illustrate byte indices.

```rust
let s = "Löwe 老虎 Léopard Gepardi";

assert_eq!(s.find('L'), Some(0));
assert_eq!(s.find('é'), Some(14));
assert_eq!(s.find("pard"), Some(17));
```

```rust
let s = "Löwe 老虎 Léopard";

assert_eq!(s.find(char::is_whitespace), Some(5));
assert_eq!(s.find(char::is_lowercase), Some(1));
assert_eq!(s.find(|c: char| c.is_whitespace() || c.is_lowercase()), Some(1));
assert_eq!(s.find(|c: char| (c < 'o') && (c > 'a')), Some(4));
```

```rust
let s = "Löwe 老虎 Léopard";
let x: &[_] = &['1', '2'];

assert_eq!(s.find(x), None);
```

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

### Get URI username with username

Source: https://docs.rs/uriparse/latest/uriparse/uri/struct.URI.html

Returns the username of a URI if present. The example extracts the username from a URI with userinfo.

```rust
use std::convert::TryFrom;

use uriparse::URI;

let uri = URI::try_from("http://username@example.com").unwrap();
assert_eq!(uri.username().unwrap(), "username");
```

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

### Username::as_str() example

Source: https://docs.rs/uriparse/latest/src/uriparse/authority.rs.html

Shows how to create a Username from a string and retrieve its string representation with as_str().

```rust
use std::convert::TryFrom;

use uriparse::Username;

let username = Username::try_from("username").unwrap();
assert_eq!(username.as_str(), "username");
```

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

### Build error when path starts with // and no authority

Source: https://docs.rs/uriparse/latest/uriparse/uri/struct.URIBuilder.html

Demonstrates the second error type: a URI with no authority cannot have a path starting with "//". The example uses scheme URN and path //path, resulting in an error.

```rust
use std::convert::TryFrom;

use uriparse::{Scheme, Path, URIBuilder};

let result = URIBuilder::new()
    .with_scheme(Scheme::URN)
    .with_path(Path::try_from("//path").unwrap())
    .build();
assert!(result.is_err());
```

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

### Get unchecked subslice with str::get_unchecked

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Gets an unchecked subslice of a string using `get_unchecked()` inside an `unsafe` block. The example shows that the method returns the correct substrings for valid ranges, but the caller must ensure the indices are within bounds and on UTF-8 boundaries.

```rust
let v = "🗻∈🌏";
unsafe {
    assert_eq!("🗻", v.get_unchecked(0..4));
    assert_eq!("∈", v.get_unchecked(4..7));
    assert_eq!("🌏", v.get_unchecked(7..11));
}
```

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

### Get byte length of a string with str::len

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Shows how to get the byte length of a string slice using `len()`. The example demonstrates that `len()` returns bytes, not characters, and that a string with a non-ASCII character like 'ƒ' has a byte length of 4 but a character count of 3.

```rust
let len = "foo".len();
assert_eq!(3, len);

assert_eq!("ƒoo".len(), 4); // fancy f!
assert_eq!("ƒoo".chars().count(), 3);
```

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

### Get the port of a URI reference with URIReference::port

Source: https://docs.rs/uriparse/latest/src/uriparse/uri_reference.rs.html

Returns the port of the URI reference if present. The example parses a URI with an explicit port and asserts that the port is 8080.

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://example.com:8080/").unwrap();
assert_eq!(reference.port().unwrap(), 8080);
```

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

### trim_ascii_start examples

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Demonstrates trim_ascii_start, which removes leading ASCII whitespace but not U+000B.

```rust
assert_eq!(" \t \u{3000}hello world\n".trim_ascii_start(), "\u{3000}hello world\n");
assert_eq!("  ".trim_ascii_start(), "");
assert_eq!("".trim_ascii_start(), "");
```

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

### match_indices with string patterns

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Shows `match_indices` returning start indices and matched substrings. The last example demonstrates that overlapping matches are not returned; only the first `aba` is included.

```rust
let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);

let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
assert_eq!(v, [(1, "abc"), (4, "abc")]);

let v: Vec<_> = "ababa".match_indices("aba").collect();
assert_eq!(v, [(0, "aba")]); // only the first `aba`
```

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

### Get authority from URIReference

Source: https://docs.rs/uriparse/latest/uriparse/uri_reference/struct.URIReference.html

Shows how to parse a URI reference and retrieve its authority component using the authority() method. The example uses URIReference::try_from and asserts the authority string.

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("//example.com/my/path").unwrap();
assert_eq!(reference.authority().unwrap().to_string(), "example.com");
```

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

### Segment::as_str Example

Source: https://docs.rs/uriparse/latest/src/uriparse/path.rs.html

Demonstrates how to retrieve the string representation of a Segment.

```rust
use std::convert::TryFrom;

use uriparse::Segment;

let segment = Segment::try_from("segment").unwrap();
assert_eq!(segment.as_str(), "segment");
```

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

### split examples: simple, slice, closure, and edge cases

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Username.html

Examples for the `split` method on string slices. The first block covers simple patterns with characters, string literals, and closures. Subsequent blocks show splitting on a slice of characters, a closure, contiguous separators, separators at edges, empty string separator, and whitespace behavior.

```rust
let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);

let v: Vec<&str> = "".split('X').collect();
assert_eq!(v, [""]);

let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
assert_eq!(v, ["lion", "", "tiger", "leopard"]);

let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
assert_eq!(v, ["lion", "tiger", "leopard"]);

let v: Vec<&str> = "AABBCC".split("DD").collect();
assert_eq!(v, ["AABBCC"]);

let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect();
assert_eq!(v, ["abc", "def", "ghi"]);

let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect();
assert_eq!(v, ["lion", "tiger", "leopard"]);
```

```rust
let v: Vec<&str> = "2020-11-03 23:59".split(&['-', ' ', ':', '@'][..]).collect();
assert_eq!(v, ["2020", "11", "03", "23", "59"]);
```

```rust
let v: Vec<&str> = "abc1defXghi".split(|c| c == '1' || c == 'X').collect();
assert_eq!(v, ["abc", "def", "ghi"]);
```

```rust
let x = "||||a||b|c".to_string();
let d: Vec<_> = x.split('|').collect();

assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
```

```rust
let x = "(///)".to_string();
let d: Vec<_> = x.split('/').collect();

assert_eq!(d, &["(", "", "", ")"]);
```

```rust
let d: Vec<_> = "010".split("0").collect();
assert_eq!(d, &["", "1", ""]);
```

```rust
let f: Vec<_> = "rust".split("").collect();
assert_eq!(f, &["", "r", "u", "s", "t", ""]);
```

```rust
let x = "    a  b c".to_string();
let d: Vec<_> = x.split(' ').collect();

assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
```

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

### Get the scheme of a URI reference with URIReference::scheme

Source: https://docs.rs/uriparse/latest/src/uriparse/uri_reference.rs.html

Returns the scheme of the URI reference if present. The example parses a URI with an http scheme and asserts that the scheme is "http".

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://127.0.0.1/").unwrap();
assert_eq!(reference.scheme().unwrap(), "http");
```

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

### pub fn starts_with<P>(&self, pat: P) -> bool where P: Pattern

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Username.html

Returns `true` if the given pattern matches a prefix of this string slice. Returns `false` if it does not.

```APIDOC
## pub fn starts_with<P>(&self, pat: P) -> bool where P: Pattern

### Description
Returns `true` if the given pattern matches a prefix of this string slice. Returns `false` if it does not. The pattern can be a `&str`, in which case this function will return true if the `&str` is a prefix of this string slice. The pattern can also be a `char`, a slice of `char`s, or a function or closure that determines if a character matches. These will only be checked against the first character of this string slice. Look at the second example below regarding behavior for slices of `char`s.

### Method
starts_with

### Signature
pub fn starts_with<P>(&self, pat: P) -> bool where P: Pattern

### Parameters
- `self` (&str) - The string slice to check.
- `pat` (P) - The pattern to match against the prefix. Can be a `&str`, `char`, a slice of `char`s, or a function or closure.

### Returns
- `bool` - `true` if the pattern matches a prefix, `false` otherwise.

### Examples
```rust
let bananas = "bananas";

assert!(bananas.starts_with("bana"));
assert!(!bananas.starts_with("nana"));
```

```rust
let bananas = "bananas";

// Note that both of these assert successfully.
assert!(bananas.starts_with(&['b', 'a', 'n', 'a']));
assert!(bananas.starts_with(&['a', 'b', 'c', 'd']));
```

### Version
1.0.0
```

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

### Get the query of a URI reference with URIReference::query

Source: https://docs.rs/uriparse/latest/src/uriparse/uri_reference.rs.html

Returns the query component of a URI reference if present. The example parses a URI with a query and asserts that the query is "my=query".

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://127.0.0.1?my=query").unwrap();
assert_eq!(reference.query().unwrap(), "my=query");
```

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

### Get the password of a URI reference with URIReference::password

Source: https://docs.rs/uriparse/latest/src/uriparse/uri_reference.rs.html

Returns the password from the authority of a URI reference. The example parses a URI with user:pass@ and asserts that the password is "pass".

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://user:pass@example.com").unwrap();
assert_eq!(reference.password().unwrap(), "pass");
```

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

### Get the path of a URI reference with URIReference::path

Source: https://docs.rs/uriparse/latest/src/uriparse/uri_reference.rs.html

Returns the path component of a URI reference. The example parses a URI with a path and asserts that the returned path is "/my/path".

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://127.0.0.1/my/path").unwrap();
assert_eq!(reference.path(), "/my/path");
```

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

### Construct URIReference from parts

Source: https://docs.rs/uriparse/latest/uriparse/uri_reference/struct.URIReference.html

Demonstrates using from_parts to create a URI reference from individual components. The example passes None for scheme, Some for authority, path, query, and fragment, and asserts the resulting string.

```rust
use std::convert::TryFrom;

use uriparse::{Scheme, URIReference};

let reference = URIReference::from_parts(
    None::<Scheme>,
    Some("example.com"),
    "/my/path",
    Some("query"),
    Some("fragment")
).unwrap();
assert_eq!(reference.to_string(), "//example.com/my/path?query#fragment");
```

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

### Set the authority of a URI reference with set_authority()

Source: https://docs.rs/uriparse/latest/uriparse/uri_reference/struct.URIReference.html

Sets the authority component. The path is forced to be absolute (starts with '/') when an authority is set. The example sets an authority and asserts the resulting string.

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let mut reference = URIReference::try_from("http://example.com").unwrap();
reference.set_authority(Some("user@example.com:80"));
assert_eq!(reference.to_string(), "http://user@example.com:80/");
```

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

### pub fn split_at(&self, mid: usize) -> (&str, &str)

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Username.html

Divides one string slice into two at an index. The argument, `mid`, should be a byte offset from the start of the string. It must also be on the boundary of a UTF-8 code point. The two slices returned go from the start of the string slice to `mid`, and from `mid` to the end of the string slice. To get mutable string slices instead, see the `split_at_mut` method.

```APIDOC
## pub fn split_at(&self, mid: usize) -> (&str, &str)

### Description
Divides one string slice into two at an index. The argument, `mid`, should be a byte offset from the start of the string. It must also be on the boundary of a UTF-8 code point. The two slices returned go from the start of the string slice to `mid`, and from `mid` to the end of the string slice. To get mutable string slices instead, see the `split_at_mut` method.

### Panics
Panics if `mid` is not on a UTF-8 code point boundary, or if it is past the end of the last code point of the string slice. For a non-panicking alternative see `split_at_checked`.

### Examples
```rust
let s = "Per Martin-Löf";

let (first, last) = s.split_at(3);

assert_eq!("Per", first);
assert_eq!(" Martin-Löf", last);
```
```

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

### with_path example

Source: https://docs.rs/uriparse/latest/uriparse/relative_reference/struct.RelativeReferenceBuilder.html

Consumes the builder and sets the path part using with_path. The path is required; omitting it results in an error during build.

```rust
use std::convert::TryFrom;

use uriparse::{Path, RelativeReferenceBuilder};

let reference = RelativeReferenceBuilder::new()
    .with_path(Path::try_from("/").unwrap())
    .build()
    .unwrap();
assert_eq!(reference.to_string(), "/")
```

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

### Get username from URIReference

Source: https://docs.rs/uriparse/latest/src/uriparse/uri_reference.rs.html

Shows how to extract the username from a URI reference that includes user information. The example parses "http://username@example.com" and asserts that username() returns "username". Requires the TryFrom trait in scope.

```rust
use std::convert::TryFrom;

use uriparse::URIReference;

let reference = URIReference::try_from("http://username@example.com").unwrap();
assert_eq!(reference.username().unwrap(), "username");
```

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

### Find ceil char boundary with str::ceil_char_boundary

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Finds the closest valid UTF-8 boundary at or above a given index using `ceil_char_boundary()`. The example shows that for a string of emojis, the method returns the byte index of the start of the next character, allowing safe truncation without splitting a character.

```rust
let s = "❤️🧡💛💚💙💜";
assert_eq!(s.len(), 26);
assert!(!s.is_char_boundary(13));

let closest = s.ceil_char_boundary(13);
assert_eq!(closest, 14);
assert_eq!(&s[..closest], "❤️🧡💛");
```

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

### Find floor char boundary with str::floor_char_boundary

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Finds the closest valid UTF-8 boundary at or below a given index using `floor_char_boundary()`. The example shows that for a string of emojis, the method returns the byte index of the start of the next character, allowing safe truncation without splitting a character.

```rust
let s = "❤️🧡💛💚💙💜";
assert_eq!(s.len(), 26);
assert!(!s.is_char_boundary(13));

let closest = s.floor_char_boundary(13);
assert_eq!(closest, 10);
assert_eq!(&s[..closest], "❤️🧡");
```

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

### Construct Authority from parts

Source: https://docs.rs/uriparse/latest/uriparse/authority/index.html

Shows how to create an Authority from a host string and then from parts, including username, password, host, and port. The resulting string is 'username:password@example.com:80'.

```rust
use std::convert::TryFrom;

use uriparse::Authority;

let authority = Authority::try_from("example.com").unwrap();
let host = authority.into_parts().2;
let authority =
    Authority::from_parts(Some("username"), Some("password"), host, Some(80)).unwrap();
assert_eq!(authority.to_string(), "username:password@example.com:80");
```

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

### Check UTF-8 boundaries with str::is_char_boundary

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Checks whether a byte index is a valid UTF-8 code point boundary using `is_char_boundary()`. The example shows that the start, end, and boundaries of multi-byte characters return `true`, while byte positions inside a multi-byte character return `false`.

```rust
let s = "Löwe 老虎 Léopard";
assert!(s.is_char_boundary(0));
// start of `老`
assert!(s.is_char_boundary(6));
assert!(s.is_char_boundary(s.len()));

// second byte of `ö`
assert!(!s.is_char_boundary(2));

// third byte of `老`
assert!(!s.is_char_boundary(8));
```

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

### pub fn split_at_checked(&self, mid: usize) -> Option<(&str, &str)>

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Username.html

Divides one string slice into two at an index. The argument, `mid`, should be a valid byte offset from the start of the string. It must also be on the boundary of a UTF-8 code point. The method returns `None` if that’s not the case. The two slices returned go from the start of the string slice to `mid`, and from `mid` to the end of the string slice. To get mutable string slices instead, see the `split_at_mut_checked` method.

```APIDOC
## pub fn split_at_checked(&self, mid: usize) -> Option<(&str, &str)>

### Description
Divides one string slice into two at an index. The argument, `mid`, should be a valid byte offset from the start of the string. It must also be on the boundary of a UTF-8 code point. The method returns `None` if that’s not the case. The two slices returned go from the start of the string slice to `mid`, and from `mid` to the end of the string slice. To get mutable string slices instead, see the `split_at_mut_checked` method.

### Examples
```rust
let s = "Per Martin-Löf";

let (first, last) = s.split_at_checked(3).unwrap();
assert_eq!("Per", first);
assert_eq!(" Martin-Löf", last);

assert_eq!(None, s.split_at_checked(13));  // Inside “ö”
assert_eq!(None, s.split_at_checked(16));  // Beyond the string length
```
```

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

### trim_start directionality example

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Shows `trim_start` on a string with leading spaces, then checks that the first character after trimming is 'E'.

```rust
let s = "  English  ";
assert!(Some('E') == s.trim_start().chars().next());
```

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

### split_ascii_whitespace() examples

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Splits a string slice by ASCII whitespace only. The first example shows basic splitting. The second example demonstrates that various ASCII whitespace characters (space, tab, newline) are recognized. The third example shows that empty or all-ASCII-whitespace strings yield no slices.

```rust
let mut iter = "A few words".split_ascii_whitespace();

assert_eq!(Some("A"), iter.next());
assert_eq!(Some("few"), iter.next());
assert_eq!(Some("words"), iter.next());

assert_eq!(None, iter.next());
```

```rust
let mut iter = " Mary   had\ta little  \n\t lamb".split_ascii_whitespace();
assert_eq!(Some("Mary"), iter.next());
assert_eq!(Some("had"), iter.next());
assert_eq!(Some("a"), iter.next());
assert_eq!(Some("little"), iter.next());
assert_eq!(Some("lamb"), iter.next());

assert_eq!(None, iter.next());
```

```rust
assert_eq!("".split_ascii_whitespace().next(), None);
assert_eq!("   ".split_ascii_whitespace().next(), None);
```

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

### split with separators at start or end

Source: https://docs.rs/uriparse/latest/uriparse/authority/struct.Password.html

Shows that separators at the start or end of a string are neighbored by empty strings.

```rust
let d: Vec<_> = "010".split("0").collect();
assert_eq!(d, &["", "1", ""]);
```