Struct EStr

pub struct EStr<E: Encoder> { /* private fields */ }

Percent-encoded string slices.

The owned counterpart of EStr is EString. See its documentation if you want to build a percent-encoded string from scratch.

Type parameter

The EStr<E> type is parameterized over a type E that implements Encoder. The associated constant E::TABLE of type Table specifies the byte patterns allowed in a string. In short, the underlying byte sequence of an EStr<E> slice can be formed by joining any number of the following byte sequences:

• ch.encode_utf8(&mut [0; 4]) where E::TABLE.allows(ch).
• [b'%', hi, lo] where E::TABLE.allows_pct_encoded() && hi.is_ascii_hexdigit() && lo.is_ascii_hexdigit().

Comparison

EStr slices are compared lexicographically by their byte values. Normalization is not performed prior to comparison.

Examples

Parse key-value pairs from a query string into a hash map:

use fluent_uri::{encoding::EStr, UriRef};
use std::collections::HashMap;

let s = "?name=%E5%BC%A0%E4%B8%89&speech=%C2%A1Ol%C3%A9%21";
let query = UriRef::parse(s)?.query().unwrap();
let map: HashMap<_, _> = query
    .split('&')
    .map(|s| s.split_once('=').unwrap_or((s, EStr::EMPTY)))
    .map(|(k, v)| (k.decode().into_string_lossy(), v.decode().into_string_lossy()))
    .collect();
assert_eq!(map["name"], "张三");
assert_eq!(map["speech"], "¡Olé!");

Implementations

impl<E: Encoder> EStr<E>

pub const EMPTY: &'static Self = _

An empty EStr slice.

pub const fn new_or_panic(s: &str) -> &Self

Converts a string slice to an EStr slice.

Panics

Panics if the string is not properly encoded with E. For a non-panicking variant, use new.

pub const fn new(s: &str) -> Option<&Self>

Converts a string slice to an EStr slice, returning None if the conversion fails.

pub fn as_str(&self) -> &str

Yields the underlying string slice.

pub fn len(&self) -> usize

Returns the length of the EStr slice in bytes.

pub fn is_empty(&self) -> bool

Checks whether the EStr slice is empty.

pub fn decode(&self) -> Decode<'_>

Decodes the EStr slice.

Always split before decoding, as otherwise the data may be mistaken for component delimiters.

This method allocates only when the slice contains any percent-encoded octet.

Note that this method will not decode U+002B (+) as 0x20 (space).

Panics

Panics at compile time if E::TABLE does not allow percent-encoded octets.

Examples

use fluent_uri::encoding::{encoder::Path, EStr};

let dec = EStr::<Path>::new_or_panic("%C2%A1Hola%21").decode();
assert_eq!(dec.as_bytes(), &[0xc2, 0xa1, 0x48, 0x6f, 0x6c, 0x61, 0x21]);
assert_eq!(dec.into_string().unwrap(), "¡Hola!");

pub fn split(&self, delim: char) -> Split<'_, E>

Returns an iterator over subslices of the EStr slice separated by the given delimiter.

Panics

Panics if the delimiter is not a reserved character.

Examples

use fluent_uri::encoding::{encoder::Path, EStr};

assert!(EStr::<Path>::new_or_panic("a,b,c").split(',').eq(["a", "b", "c"]));
assert!(EStr::<Path>::new_or_panic(",").split(',').eq(["", ""]));
assert!(EStr::<Path>::EMPTY.split(',').eq([""]));

pub fn split_once(&self, delim: char) -> Option<(&Self, &Self)>

Splits the EStr slice on the first occurrence of the given delimiter and returns prefix before delimiter and suffix after delimiter.

Returns None if the delimiter is not found.

Panics

Panics if the delimiter is not a reserved character.

Examples

use fluent_uri::encoding::{encoder::Path, EStr};

assert_eq!(
    EStr::<Path>::new_or_panic("foo;bar;baz").split_once(';'),
    Some((EStr::new_or_panic("foo"), EStr::new_or_panic("bar;baz")))
);

assert_eq!(EStr::<Path>::new_or_panic("foo").split_once(';'), None);

pub fn rsplit_once(&self, delim: char) -> Option<(&Self, &Self)>

Splits the EStr slice on the last occurrence of the given delimiter and returns prefix before delimiter and suffix after delimiter.

Returns None if the delimiter is not found.

Panics

Panics if the delimiter is not a reserved character.

Examples

use fluent_uri::encoding::{encoder::Path, EStr};

assert_eq!(
    EStr::<Path>::new_or_panic("foo;bar;baz").rsplit_once(';'),
    Some((EStr::new_or_panic("foo;bar"), EStr::new_or_panic("baz")))
);

assert_eq!(EStr::<Path>::new_or_panic("foo").rsplit_once(';'), None);

impl<E: PathEncoder> EStr<E>

Extension methods for the path component.

pub fn is_absolute(&self) -> bool

Checks whether the path is absolute, i.e., starting with '/'.

pub fn is_rootless(&self) -> bool

Checks whether the path is rootless, i.e., not starting with '/'.

pub fn segments_if_absolute(&self) -> Option<Split<'_, E>>

Returns an iterator over the path segments, separated by '/'.

Returns None if the path is rootless. Use split instead if you need to split a rootless path on occurrences of '/'.

Note that the path can be empty when authority is present, in which case this method will return None.

Examples

use fluent_uri::Uri;

// Segments are separated by '/'.
// The empty string before a leading '/' is not a segment.
// However, segments can be empty in the other cases.
let path = Uri::parse("file:///path/to//dir/")?.path();
assert_eq!(path, "/path/to//dir/");
assert!(path.segments_if_absolute().unwrap().eq(["path", "to", "", "dir", ""]));

let path = Uri::parse("foo:bar/baz")?.path();
assert_eq!(path, "bar/baz");
assert!(path.segments_if_absolute().is_none());

let path = Uri::parse("http://example.com")?.path();
assert!(path.is_empty());
assert!(path.segments_if_absolute().is_none());

Trait Implementations

impl<E: Encoder> AsRef<EStr<E>> for EStr<E>

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl<E: Encoder> AsRef<EStr<E>> for EString<E>

fn as_ref(&self) -> &EStr<E>

Converts this type into a shared reference of the (usually inferred) input type.

impl<E: Encoder> AsRef<str> for EStr<E>

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl<E: Encoder> Borrow<EStr<E>> for EString<E>

fn borrow(&self) -> &EStr<E>

Immutably borrows from an owned value.

impl<E: Encoder> Debug for EStr<E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<E: Encoder> Default for &EStr<E>

fn default() -> Self

Creates an empty EStr slice.

impl<E: Encoder> Display for EStr<E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<E: Encoder> From<&EStr<E>> for EString<E>

fn from(s: &EStr<E>) -> Self

Converts to this type from the input type.

impl<E: Encoder> Hash for EStr<E>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

impl<E: Encoder> Ord for EStr<E>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

impl<E: Encoder> PartialEq<&EStr<E>> for EString<E>

fn eq(&self, other: &&EStr<E>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<E: Encoder> PartialEq<EStr<E>> for EString<E>

fn eq(&self, other: &EStr<E>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<E: Encoder> PartialEq<EStr<E>> for str

fn eq(&self, other: &EStr<E>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<E: Encoder> PartialEq<EString<E>> for &EStr<E>

fn eq(&self, other: &EString<E>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<E: Encoder> PartialEq<EString<E>> for EStr<E>

fn eq(&self, other: &EString<E>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<E: Encoder> PartialEq<str> for EStr<E>

fn eq(&self, other: &str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<E: Encoder> PartialEq for EStr<E>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<E: Encoder> PartialOrd for EStr<E>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<E: Encoder> ToOwned for EStr<E>

type Owned = EString<E>

The resulting type after obtaining ownership.

fn to_owned(&self) -> EString<E>

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut EString<E>)

Uses borrowed data to replace owned data, usually by cloning.

impl<E: Encoder> Eq for EStr<E>