### String::capacity example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Shows how to get the capacity of a `String` using `capacity`. The example creates a `String` with capacity 10 and asserts it is at least 10.

```rust
let s = String::with_capacity(10);

assert!(s.capacity() >= 10);
```

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

### into_ok example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Shows how to use into_ok to get the Ok value without panicking, using a Result with the never type as the error.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

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

### as_ref example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Shows how to use as_ref to get a Result with references to the original values, leaving the original intact.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

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

### as_mut example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Demonstrates using as_mut to get a Result with mutable references, allowing modification of the contained values.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

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

### trim_prefix examples

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Examples for trim_prefix, which removes a prefix if present and returns &str for chaining.

```rust
// 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/");
```

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

### is_ok() Example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Example of using the is_ok() method to check if a Result is Ok.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

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

### len() example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Shows how to get the byte length of a string. Note that the length is in bytes, not characters or graphemes.

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

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

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

### is_ok_and() Example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Example of using the is_ok_and() method to check if a Result is Ok and the value matches a predicate.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

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

### or example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Returns the Ok value of self if Ok, otherwise returns the provided result. The example shows various combinations of Ok and Err results.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Err("late error"));

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Ok(100);
assert_eq!(x.or(y), Ok(2));
```

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

### trim_start_matches with char slice

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Example for trim_start_matches using a slice of chars to remove matching characters from the start of a string.

```rust
let x: &[_] = &['1', '2'];
assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12");
```

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

### expect example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Returns the contained Ok value, panicking with a message if Err. The first example shows a panic, the second shows the recommended message style.

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
```

```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

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

### unwrap_or example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Returns the contained Ok value or a provided default. The example shows both Ok and Err cases.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

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

### strip_prefix examples

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Examples for strip_prefix, which removes a prefix exactly once and returns Option<&str>.

```rust
assert_eq!("foo:bar".strip_prefix("foo:"), Some("bar"));
assert_eq!("foo:bar".strip_prefix("bar"), None);
assert_eq!("foofoo".strip_prefix("foo"), Some("foo"));
```

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

### map example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Shows how to use map to apply a function to the Ok value of a Result, leaving Err untouched. The example parses numbers from lines and prints them doubled.

```rust
let line = "1\n2\n3\n4\n";

for num in line.lines() {
    match num.parse::<i32>().map(|i| i * 2) {
        Ok(n) => println!("{n}"),
        Err(..) => {}
    }
}
```

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

### get() example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Returns a subslice of the string without panicking. Returns `None` if the index is out of bounds or not on a UTF-8 boundary.

```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());
```

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

### trim_suffix examples

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Examples for trim_suffix, which removes a suffix if present and returns &str for chaining.

```rust
// 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");
```

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

### into_err example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Shows how to use into_err to get the Err value without panicking, using a Result with the never type as the Ok type.

```rust
fn only_bad_news() -> Result<!, String> {
    Err("Oops, it failed".into())
}

let error: String = only_bad_news().into_err();
println!("{error}");
```

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

### ok example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Demonstrates converting a Result to an Option using ok, returning Some(value) for Ok and None for Err.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

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

### is_err_and example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Shows how to use is_err_and to check if a Result is Err and the error value matches a predicate. Includes examples with different error kinds and ownership.

```rust
use std::io::{Error, ErrorKind};

let x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);

let x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, Error> = Ok(123);
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, String> = Err("ownership".to_string());
assert_eq!(x.as_ref().is_err_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

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

### Product example: parsing and multiplying numbers

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Shows how to use the Product implementation on Result to multiply parsed numbers, returning Err if any parse fails.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

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

### unwrap basic usage

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Shows how to use Result::unwrap to get the contained Ok value. This example asserts that unwrap returns the value 2.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

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

### replace example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Shows how replace creates a new String and replaces all matches of a pattern with a replacement string.

```rust
let s = "this is old";
```

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

### strip_suffix examples

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Examples for strip_suffix, which removes a suffix exactly once and returns Option<&str>.

```rust
assert_eq!("bar:foo".strip_suffix(":foo"), Some("bar"));
assert_eq!("bar:foo".strip_suffix("bar"), None);
assert_eq!("foofoo".strip_suffix("foo"), Some("foo"));
```

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

### and_then with metadata example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Uses and_then to chain metadata retrieval and modified time. Shows that on Windows, "/" maps to "C:\". The example asserts that a valid path returns Ok and an invalid path returns an error of kind NotFound.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

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

### String::as_str example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Shows how to extract a string slice from a `String` using `as_str`. The example creates a `String` from "foo" and asserts the slice equals "foo".

```rust
let s = String::from("foo");

assert_eq!("foo", s.as_str());
```

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

### inspect example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Calls a function with a reference to the contained value if Ok, and returns the original result. The example chains inspect with map and expect to parse and cube a number.

```rust
let x: u8 = "4"
    .parse::<u8>()
    .inspect(|x| println!("original: {x}"))
    .map(|x| x.pow(3))
    .expect("literal `4` should parse as a `u8`");
```

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

### and_then example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Shows how to use and_then for control flow, calling a function that returns a Result only when the original Result is Ok.

```rust
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {
    x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")
}
```

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

### unwrap_or_else example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Returns the contained Ok value or computes it from a closure. The example defines a count function that returns the length of a string.

```rust
fn count(x: &str) -> usize { x.len() }

assert_eq!(Ok(2).unwrap_or_else(count), 2);
assert_eq!(Err("foo").unwrap_or_else(count), 3);
```

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

### matches example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Returns an iterator over disjoint matches of a pattern in the string. Example collects all occurrences of "abc".

```rust
let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect();
assert_eq!(v, ["abc", "abc", "abc"]);
```

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

### and_then example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Chains fallible operations that may return Err. The example uses a function sq_then_to_string that squares a number and returns a string, or an error if overflow.

```rust
assert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));
assert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));
assert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));
```

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

### String::as_mut_str example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Demonstrates converting a `String` to a mutable string slice with `as_mut_str`, then modifying it in place. The example uppercases the string and asserts the result.

```rust
let mut s = String::from("foobar");
let s_mut_str = s.as_mut_str();

s_mut_str.make_ascii_uppercase();

assert_eq!("FOOBAR", s_mut_str);
```

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

### String::try_reserve example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Shows using `try_reserve` to pre-reserve memory and handle potential errors. The example defines a function that tries to reserve memory for the input data and returns an error if it fails.

```rust
use std::collections::TryReserveError;

fn process_data(data: &str) -> Result<String, TryReserveError> {
    let mut output = String::new();

    // Pre-reserve the memory, exiting if we can't
    output.try_reserve(data.len())?;

    // Now we know this can't OOM in the middle of our complex work
    output.push_str(data);

    Ok(output)
}
```

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

### replace: basic usage and non-matching pattern

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Shows how to use str::replace to replace all occurrences of a pattern. The first example replaces "old" with "new" and "is" with "an". The second example shows that when the pattern doesn't match, the original string is returned as a String.

```rust
assert_eq!("this is new", s.replace("old", "new"));
assert_eq!("than an old", s.replace("is", "an"));
```

```rust
let s = "this is old";
assert_eq!(s, s.replace("cookie monster", "little lamb"));
```

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

### err example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Demonstrates converting a Result to an Option using err, returning Some(error) for Err and None for Ok.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.err(), None);

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.err(), Some("Nothing here"));
```

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

### repeat panic upon overflow

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

This example will panic at runtime because the capacity overflows.

```rust
// this will panic at runtime
let huge = "0123456789abcdef".repeat(usize::MAX);
```

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

### map_or_else example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Shows how to use map_or_else to apply a fallback function to Err or a function to Ok, unpacking the result.

```rust
let k = 21;

let x : Result<_, &str> = Ok("foo");
assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3);

let x : Result<&str, _> = Err("bar");
assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42);
```

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

### String::push_str example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Shows appending a string slice to the end of a `String` using `push_str`. The example appends "bar" to "foo" and asserts the result.

```rust
let mut s = String::from("foo");

s.push_str("bar");

assert_eq!("foobar", s);
```

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

### inspect_err example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Calls a function with a reference to the contained error if Err, and returns the original result. The example reads a file and prints an error message on failure.

```rust
use std::{fs, io};

fn read() -> io::Result<String> {
    fs::read_to_string("address.txt")
        .inspect_err(|e| eprintln!("failed to read file: {e}"))
}
```

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

### Sum example: summing integers with error handling

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Shows how to use the Sum implementation on Result to sum integers, returning Err if any element is negative.

```rust
let f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) };
let v = vec![1, 2];
let res: Result<i32, _> = v.iter().map(f).sum();
assert_eq!(res, Ok(3));
let v = vec![1, -2];
let res: Result<i32, _> = v.iter().map(f).sum();
assert_eq!(res, Err("Negative element found"));
```

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

### and method example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Demonstrates the behavior of Result::and, which returns the second Result if the first is Ok, otherwise returns the first Err.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));

let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("not a 2"));

let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));
```

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

### map_or_default example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Demonstrates using map_or_default to apply a function to Ok or return the default value for the type on Err.

```rust
let x: Result<_, &str> = Ok("foo");
let y: Result<&str, _> = Err("bar");

assert_eq!(x.map_or_default(|x| x.len()), 3);
assert_eq!(y.map_or_default(|y| y.len()), 0);
```

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

### is_empty() example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Checks if a string has zero bytes. Returns `true` for an empty string and `false` otherwise.

```rust
let s = "";
assert!(s.is_empty());

let s = "not empty";
assert!(!s.is_empty());
```

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

### escape_default examples

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Demonstrates escape_default as an iterator, with println! directly, and with to_string. The output is equivalent to printing the escaped string.

```rust
for c in "❤\n!".escape_default() {
    print!("{c}");
}
println!();
```

```rust
println!("{}", "❤\n!".escape_default());
```

```rust
println!("\\u{{2764}}\\n!");
```

```rust
assert_eq!("❤\n!".escape_default().to_string(), "\\u{2764}\\n!");
```

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

### unwrap_or_default example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Shows how to use unwrap_or_default to convert a string to an integer, returning 0 for poorly-formed strings.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

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

### trim_ascii_start example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Shows how trim_ascii_start removes leading ASCII whitespace, excluding U+000B, and preserves non-ASCII whitespace like U+3000.

```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(), "");
```

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

### as_bytes() example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Converts a string slice to a byte slice. The byte slice can be converted back using `from_utf8`.

```rust
let bytes = "bors".as_bytes();
assert_eq!(b"bors", bytes);
```

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

### Feed byte buffers asynchronously with build_uninit, feed_bytes, and try_init

Source: https://docs.rs/jxl-oxide/latest/index.html

In async contexts, create an uninitialized image with build_uninit, feed byte buffers with feed_bytes, and call try_init to check initialization. The loop continues until InitializeResult::Initialized is returned, then prints the image header.

```rust
let mut uninit_image = JxlImage::builder().build_uninit();
let image = loop {
    uninit_image.feed_bytes(reader.read().await?);
    match uninit_image.try_init()? {
        InitializeResult::NeedMoreData(uninit) => {
            uninit_image = uninit;
        }
        InitializeResult::Initialized(image) => {
            break image;
        }
    }
};
println!("{:?}", image.image_header()); // Prints the image header
```

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

### escape_unicode examples

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Demonstrates escape_unicode as an iterator, with println! directly, and with to_string. The output is equivalent to printing the escaped string.

```rust
for c in "❤\n!".escape_unicode() {
    print!("{c}");
}
println!();
```

```rust
println!("{}", "❤\n!".escape_unicode());
```

```rust
println!("\\u{{2764}}\\u{{a}}\\u{{21}}");
```

```rust
assert_eq!("❤\n!".escape_unicode().to_string(), "\\u{2764}\\u{a}\\u{21}");
```

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

### is_char_boundary() example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Checks if a byte index is a valid UTF-8 code point boundary. The start and end of the string are considered boundaries, and `false` is returned for indices greater than the string length.

```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));
```

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

### is_err() Example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Example of using the is_err() method to check if a Result is Err.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

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

### trim_start basic usage

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Removes leading whitespace from a string slice. The example shows trimming a string with leading spaces and a Hebrew character.

```rust
let s = "  עברית  ";
assert!(Some('ע') == s.trim_start().chars().next());
```

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

### Feed bytes and initialize an UninitializedJxlImage

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/struct.UninitializedJxlImage.html

Shows how to build an uninitialized image, feed bytes incrementally, and loop until initialization completes. The loop handles NeedMoreData by reassigning the uninitialized image and breaks when Initialized is returned, then prints the image header.

```rust
let mut uninit_image = JxlImage::builder().build_uninit();
let image = loop {
    let buf = read_bytes()?;
    uninit_image.feed_bytes(buf)?;
    match uninit_image.try_init()? {
        InitializeResult::NeedMoreData(uninit) => {
            uninit_image = uninit;
        }
        InitializeResult::Initialized(image) => {
            break image;
        }
    }
};
println!("{:?}", image.image_header());
```

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

### JxlImage::open_with_defaults

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/struct.JxlImage.html

Opens an image in the filesystem with default options.

```APIDOC
## JxlImage::open_with_defaults

### Description
Opens an image in the filesystem with default options.

### Method
`pub fn open_with_defaults(path: impl AsRef<Path>) -> Result<JxlImage>`

### Parameters
- `path` (impl AsRef<Path>) - Required - The path to the image file.

### Returns
- `Result<JxlImage>` - The decoded image or an error.

```

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

### strip_circumfix examples

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Examples for strip_circumfix, which removes both a prefix and suffix exactly once, returning Option<&str>.

```rust
assert_eq!("bar:hello:foo".strip_circumfix("bar:", ":foo"), Some("hello"));
assert_eq!("bar:foo".strip_circumfix("foo", "foo"), None);
assert_eq!("foo:bar;".strip_circumfix("foo:", ';'), Some("bar"));
assert_eq!("foo:bar:baz".strip_circumfix("foo:bar:", ":bar:baz"), None);
```

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

### split: Separators at start or end

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.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", ""]);
```

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

### is_ascii example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Checks if a string contains only ASCII characters. The example includes a non-ASCII string with 'ü' and '❤'.

```rust
let ascii = "hello!\n";
let non_ascii = "Grüße, Jürgen ❤";
```

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

### split: Simple patterns

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Demonstrates splitting a string slice by `char`, `&str`, and closures, collecting into a `Vec<&str>`. Includes edge cases like empty strings and no matches.

```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"]);
```

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

### Set a custom CMS and request a color encoding

Source: https://docs.rs/jxl-oxide/latest/src/jxl_oxide/lib.rs.html

Shows how to set an external CMS using set_cms and request a color encoding (Display P3 with perceptual intent) using request_color_encoding.

```rust
//! # use jxl_oxide::{EnumColourEncoding, JxlImage, RenderingIntent};
//! # use jxl_oxide::NullCms as MyCustomCms;
//! # let reader = std::io::empty();
//! let mut image = JxlImage::builder().read(reader).expect("Failed to read image header");
//! image.set_cms(MyCustomCms);
//!
//! let color_encoding = EnumColourEncoding::display_p3(RenderingIntent::Perceptual);
//! image.request_color_encoding(color_encoding);
```

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

### Open a JPEG XL image from a file with JxlImage::builder().open

Source: https://docs.rs/jxl-oxide/latest/index.html

Constructs a JxlImage by opening a file path. The builder's open method reads the file and returns a JxlImage after parsing the header. The example prints the image header.

```rust
let image = JxlImage::builder().open("input.jxl").expect("Failed to read image header");
println!("{:?}", image.image_header()); // Prints the image header
```

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

### iter example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Returns an iterator over the possibly contained value, yielding one value if Ok and none if Err. The example shows both cases.

```rust
let x: Result<u32, &str> = Ok(7);
assert_eq!(x.iter().next(), Some(&7));

let x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter().next(), None);
```

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

### pub fn repeat(&self, n: usize) -> String

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Creates a new String by repeating a string n times. Panics if the capacity would overflow.

```APIDOC
## pub fn repeat(&self, n: usize) -> String

### Description
Creates a new `String` by repeating a string `n` times.

### Method
pub fn repeat(&self, n: usize) -> String

### Parameters
- **self** (&str) - The string to repeat.
- **n** (usize) - The number of times to repeat the string.

### Return Value
- **String** - The repeated string.

### Panics
This function will panic if the capacity would overflow.

### Examples
```rust
assert_eq!("abc".repeat(4), String::from("abcabcabcabc"));

// this will panic at runtime
let huge = "0123456789abcdef".repeat(usize::MAX);
```
```

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

### Incremental decoding with UninitializedJxlImage and try_init

Source: https://docs.rs/jxl-oxide/latest/src/jxl_oxide/lib.rs.html

Shows the recommended pattern for incremental decoding: feed bytes into an uninitialized image, call try_init, and loop until initialization completes. The example uses a helper read_bytes() that returns a byte slice; the loop breaks when InitializeResult::Initialized is returned, then prints the image header.

```rust
/// Empty, uninitialized JPEG XL image.
///
/// # Examples
/// ```no_run
/// # fn read_bytes() -> jxl_oxide::Result<&'static [u8]> { Ok(&[]) }
/// # use jxl_oxide::{JxlImage, InitializeResult};
/// # fn main() -> jxl_oxide::Result<()> {
/// let mut uninit_image = JxlImage::builder().build_uninit();
/// let image = loop {
///     let buf = read_bytes()?;
///     uninit_image.feed_bytes(buf)?;
///     match uninit_image.try_init()? {
///         InitializeResult::NeedMoreData(uninit) => {
///             uninit_image = uninit;
///         }
///         InitializeResult::Initialized(image) => {
///             break image;
///         }
///     }
/// };
/// println!("{:?}", image.image_header());
/// # Ok(())
/// # }
/// ```
```

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

### as_deref example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Converts Result<T, E> to Result<&<T as Deref>::Target, &E> by dereferencing the Ok variant. The example shows both Ok and Err cases.

```rust
let x: Result<String, u32> = Ok("hello".to_string());
let y: Result<&str, &u32> = Ok("hello");
assert_eq!(x.as_deref(), y);

let x: Result<String, u32> = Err(42);
let y: Result<&str, &u32> = Err(&42);
assert_eq!(x.as_deref(), y);
```

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

### pub fn is_loading_done(&self) -> bool

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/struct.Frame.html

Checks if loading is done.

```APIDOC
## is_loading_done

### Description
Checks if loading is done.

### Method
is_loading_done

### Signature
`pub fn is_loading_done(&self) -> bool`

### Parameters
None

### Returns
- `bool` - `true` if loading is done, `false` otherwise.
```

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

### to_lowercase: basic usage, sigma, and no-case languages

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Shows how to use str::to_lowercase to convert a string to lowercase. Includes basic usage, handling of Greek sigma (context-dependent), and languages without case (Chinese).

```rust
let s = "HELLO WORLD";

assert_eq!("hello world", s.to_lowercase());
```

```rust
let sigma = "Σ";

assert_eq!("σ", sigma.to_lowercase());

// but at the end of a word, it's ς, not σ:
let odysseus = "ὈΔΥΣΣΕΎΣ";

assert_eq!("ὀδυσσεύς", odysseus.to_lowercase());

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

assert_eq!("ο οδυσσέας βασιλιάς της ιθάκης", odysseus_king_of_ithaca.to_lowercase());
```

```rust
let new_year = "农历新年";

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

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

### iter_mut example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Returns a mutable iterator over the possibly contained value, allowing modification of the Ok value. The example shows modifying the value and the Err case.

```rust
let mut x: Result<u32, &str> = Ok(7);
match x.iter_mut().next() {
    Some(v) => *v = 40,
    None => {},
}
assert_eq!(x, Ok(40));

let mut x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter_mut().next(), None);
```

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

### starts_with() - Check prefix with &str

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Returns `true` if the pattern matches a prefix of the string. The pattern can be a `&str`, `char`, slice of `char`s, or closure.

```rust
let bananas = "bananas";

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

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

### match_indices: collect matches with start indices

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Uses `match_indices` to collect matches along with their starting indices. Overlapping matches are not included; only the first match is reported.

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

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

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

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

### pub const fn is_ok(&self) -> bool

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Returns true if the result is Ok.

```APIDOC
## pub const fn is_ok(&self) -> bool

### Description
Returns `true` if the result is `Ok`.

### Signature
```rust
pub const fn is_ok(&self) -> bool
```

### Examples
```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

```

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

### chars basic usage example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Returns an iterator over the `char`s of a string slice. The example counts characters and iterates through them, showing that `char` represents Unicode scalar values.

```rust
let word = "goodbye";

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

let mut chars = word.chars();

assert_eq!(Some('g'), chars.next());
assert_eq!(Some('o'), chars.next());
assert_eq!(Some('o'), chars.next());
assert_eq!(Some('d'), chars.next());
assert_eq!(Some('b'), chars.next());
assert_eq!(Some('y'), chars.next());
assert_eq!(Some('e'), chars.next());

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

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

### String::extend_from_within example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Demonstrates copying elements from a range within the string to the end using `extend_from_within`. The example shows three different range operations and their effects.

```rust
let mut string = String::from("abcde");

string.extend_from_within(2..);
assert_eq!(string, "abcdecde");

string.extend_from_within(..2);
assert_eq!(string, "abcdecdeab");

string.extend_from_within(4..8);
assert_eq!(string, "abcdecdeabecde");
```

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

### or_else example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Calls the provided closure if the result is Err, otherwise returns the Ok value. The example defines sq and err functions and shows chaining or_else calls.

```rust
fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
fn err(x: u32) -> Result<u32, u32> { Err(x) }

assert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2));
assert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2));
assert_eq!(Err(3).or_else(sq).or_else(err), Ok(9));
assert_eq!(Err(3).or_else(err).or_else(err), Err(3));
```

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

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

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

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`, `char`, a slice of `char`s, or a function or closure that determines if a character matches.

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

### Method
starts_with

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

### Parameters
- `self` (reference) - 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/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
```

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

### as_deref_mut example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Converts Result<T, E> to Result<&mut <T as DerefMut>::Target, &mut E> by mutably dereferencing the Ok variant. The example shows mutating the contained value.

```rust
let mut s = "HELLO".to_string();
let mut x: Result<String, u32> = Ok("hello".to_string());
let y: Result<&mut str, &mut u32> = Ok(&mut s);
assert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);

let mut i = 42;
let mut x: Result<String, u32> = Err(42);
let y: Result<&mut str, &mut u32> = Err(&mut i);
assert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);
```

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

### map_err example

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/type.Result.html

Maps a Result<T, E> to Result<T, F> by applying a function to the contained Err value. The example shows that Ok values pass through unchanged, while Err values are transformed.

```rust
fn stringify(x: u32) -> String { format!("error code: {x}") }

let x: Result<u32, u32> = Ok(2);
assert_eq!(x.map_err(stringify), Ok(2));

let x: Result<u32, u32> = Err(13);
assert_eq!(x.map_err(stringify), Err("error code: 13".to_string()));
```

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

### split_at_checked example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Divides a string slice into two at a byte offset, returning `None` if the offset is not a valid UTF-8 boundary or is past the end. The example shows valid and invalid offsets.

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

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

### JxlImage::try_init

Source: https://docs.rs/jxl-oxide

Attempts to initialize the JxlImage from fed byte buffers. Returns an InitializeResult indicating whether more data is needed or the image is initialized.

```APIDOC
## JxlImage::try_init

### Description
Attempts to initialize the JxlImage from fed byte buffers. Returns an InitializeResult indicating whether more data is needed or the image is initialized.

### Method
try_init

### Endpoint
JxlImage::try_init

### Parameters
None

### Request Example
```rust
match uninit_image.try_init()? {
    InitializeResult::NeedMoreData(uninit) => {
        uninit_image = uninit;
    }
    InitializeResult::Initialized(image) => {
        break image;
    }
}
```

### Response
#### Success Response
Returns an InitializeResult enum with variants NeedMoreData or Initialized.

```

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

### JxlImageBuilder::build_uninit

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/struct.JxlImageBuilder.html

Consumes the builder and creates an empty, uninitialized JPEG XL image decoder.

```APIDOC
## JxlImageBuilder::build_uninit

### Description
Consumes the builder and creates an empty, uninitialized JPEG XL image decoder.

### Method
`pub fn build_uninit(self) -> UninitializedJxlImage`

### Returns
- `UninitializedJxlImage` - An uninitialized JPEG XL image decoder.

```

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

### first_exif

Source: https://docs.rs/jxl-oxide/latest/jxl_oxide/struct.AuxBoxList.html

Returns the first Exif metadata from the auxiliary box list, if any.

```APIDOC
## first_exif

### Description
Returns the first Exif metadata from the auxiliary box list, if any.

### Method
first_exif

### Signature
pub fn first_exif(&self) -> Result<AuxBoxData<RawExif<'_>>>

### Parameters
None

### Returns
- `Result<AuxBoxData<RawExif<'_>>>` - The first Exif metadata, if any.
```

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

### eq_ignore_ascii_case example

Source: https://docs.rs/jxl-oxide-common/1.0.0/jxl_oxide_common/struct.Name.html

Checks ASCII case-insensitive equality.

```rust
assert!("Ferris".eq_ignore_ascii_case("FERRIS"));
assert!("Ferrös".eq_ignore_ascii_case("FERRöS"));
assert!(!"Ferrös".eq_ignore_ascii_case("FERRÖS"));
```