Struct PctStr

Source

pub struct PctStr(/* private fields */);

Expand description

Percent-Encoded string slice.

This is the equivalent of str for percent-encoded strings. This is an unsized type, meaning that it must always be used behind a pointer like & or Box. For an owned version of this type, see PctString.

§Examples

use pct_str::PctStr;

let buffer = "Hello%20World%21";
let pct_str = PctStr::new(buffer).unwrap();

// You can compare percent-encoded strings with a regular string.
assert!(pct_str == "Hello World!");

// The underlying string is unchanged.
assert!(pct_str.as_str() == "Hello%20World%21");

// Just as a regular string, you can iterate over the
// encoded characters of `pct_str` with [`PctStr::chars`].
for c in pct_str.chars() {
  print!("{}", c);
}

// You can decode the string and every remove percent-encoded characters
// with the [`PctStr::decode`] method.
let decoded_string: String = pct_str.decode();
println!("{}", decoded_string);

Implementations§

Source §

impl PctStr

Source

pub fn new<S: AsRef<[u8]> + ?Sized>( input: &S, ) -> Result<&PctStr, InvalidPctString<&S>>

Create a new percent-encoded string slice.

The input slice is checked for correct percent-encoding. If the test fails, a InvalidPctString error is returned.

Examples found in repository ?

examples/str.rs (line 10)

5fn main() -> Result<(), InvalidPctString<&'static str>> {
6	// [`PctStr`] is the equivalent of [`str`] for percent-encoded strings.
7	let buffer = "Hello%20World%21";
8	// It is just a reference to `buffer`.
9	// It can fail if `buffer` is not a valid percent-encoded string.
10	let pct_str = PctStr::new(buffer)?;
11
12	// You can compare percent-encoded strings with a regular string.
13	assert!(pct_str == "Hello World!"); // => true
14
15	// The underlying string is unchanged.
16	assert!(pct_str.as_str() == "Hello%20World%21"); // => true
17
18	// Just as a regular string, you can iterate over the
19	// encoded characters of `pct_str` with [`PctStr::chars`].
20	for c in pct_str.chars() {
21		print!("{}", c);
22	}
23	// => Hello World!
24
25	println!("");
26
27	// You can decode the string and every remove percent-encoded characters
28	// with the [`PctStr::decode`] method.
29	let decoded_string: String = pct_str.decode();
30	println!("{}", decoded_string);
31	// => Hello World!
32
33	Ok(())
34}

More examples

Hide additional examples

examples/string.rs (line 20)

5fn main() -> Result<(), InvalidPctString<String>> {
6	// [`PctString`] is the equivalent of [`String`] for
7	// percent-encoded strings.
8	// The data is owned by `pct_string`.
9	let pct_string = PctString::from_string("Hello%20World%21".to_string())?;
10
11	// You can compare percent-encoded strings with a regular string.
12	assert!(pct_string == "Hello World!");
13
14	// The underlying string is percent-encoded.
15	assert!(pct_string.as_str() == "Hello%20World%21");
16
17	// You can get a reference to the string as a [`PctStr`].
18	assert!(
19		pct_string.as_pct_str()
20			== PctStr::new("Hello%20World%21").map_err(InvalidPctString::into_owned)?
21	);
22
23	// Just as a regular string, you can iterate over the
24	// encoded characters of `pct_str` with [`PctString::chars`].
25	for c in pct_string.chars() {
26		println!("{}", c);
27	}
28
29	// You can decode the string and every remove percent-encoded characters
30	// with the [`PctStr::decode`] method.
31	let decoded_string: String = pct_string.decode();
32	println!("{}", decoded_string);
33
34	Ok(())
35}

Source

pub unsafe fn new_unchecked<S: AsRef<[u8]> + ?Sized>(input: &S) -> &PctStr

Create a new percent-encoded string slice without checking for correct encoding.

This is an unsafe function. The resulting string slice will have an undefined behaviour if the input slice is not percent-encoded.

§Safety

The input str must be a valid percent-encoded string.

Source

pub fn validate(input: impl Iterator<Item = u8>) -> bool

Checks that the given iterator produces a valid percent-encoded string.

Source

pub fn len(&self) -> usize

Length of the decoded string (character count).

Computed in linear time. This is different from the byte length, which can be retrieved using value.as_bytes().len().

Source

pub fn is_empty(&self) -> bool

Checks if the string is empty.

Source

pub fn as_bytes(&self) -> &[u8] ⓘ

Returns the underlying percent-encoding bytes.

Source

pub fn as_str(&self) -> &str

Get the underlying percent-encoded string slice.

Examples found in repository ?

examples/encode.rs (line 20)

13fn main() {
14	// You can encode any string into a percent-encoded string
15	// using the [`PctString::encode`] function.
16	// It takes a `char` iterator and a [`Encoder`] instance deciding which
17	// characters to encode.
18	let pct_string = PctString::encode("Hello World!".chars(), UriReserved::Any);
19	// [`URIReserved`] is a predefined encoder for URI-reserved characters.
20	assert_eq!(pct_string.as_str(), "Hello World%21");
21
22	// You can create your own encoder by implementing the [`Encoder`] trait.
23	let pct_string = PctString::encode("Hello World!".chars(), CustomEncoder);
24	println!("{}", pct_string.as_str());
25	assert_eq!(pct_string.as_str(), "%48ello %57orld%21");
26
27	// You can also use any function implementing `Fn(char) -> bool`.
28	let pct_string = PctString::encode("Hello World!".chars(), char::is_uppercase);
29	assert_eq!(pct_string.as_str(), "%48ello %57orld!");
30}

More examples

Hide additional examples

examples/str.rs (line 16)

5fn main() -> Result<(), InvalidPctString<&'static str>> {
6	// [`PctStr`] is the equivalent of [`str`] for percent-encoded strings.
7	let buffer = "Hello%20World%21";
8	// It is just a reference to `buffer`.
9	// It can fail if `buffer` is not a valid percent-encoded string.
10	let pct_str = PctStr::new(buffer)?;
11
12	// You can compare percent-encoded strings with a regular string.
13	assert!(pct_str == "Hello World!"); // => true
14
15	// The underlying string is unchanged.
16	assert!(pct_str.as_str() == "Hello%20World%21"); // => true
17
18	// Just as a regular string, you can iterate over the
19	// encoded characters of `pct_str` with [`PctStr::chars`].
20	for c in pct_str.chars() {
21		print!("{}", c);
22	}
23	// => Hello World!
24
25	println!("");
26
27	// You can decode the string and every remove percent-encoded characters
28	// with the [`PctStr::decode`] method.
29	let decoded_string: String = pct_str.decode();
30	println!("{}", decoded_string);
31	// => Hello World!
32
33	Ok(())
34}

examples/string.rs (line 15)

5fn main() -> Result<(), InvalidPctString<String>> {
6	// [`PctString`] is the equivalent of [`String`] for
7	// percent-encoded strings.
8	// The data is owned by `pct_string`.
9	let pct_string = PctString::from_string("Hello%20World%21".to_string())?;
10
11	// You can compare percent-encoded strings with a regular string.
12	assert!(pct_string == "Hello World!");
13
14	// The underlying string is percent-encoded.
15	assert!(pct_string.as_str() == "Hello%20World%21");
16
17	// You can get a reference to the string as a [`PctStr`].
18	assert!(
19		pct_string.as_pct_str()
20			== PctStr::new("Hello%20World%21").map_err(InvalidPctString::into_owned)?
21	);
22
23	// Just as a regular string, you can iterate over the
24	// encoded characters of `pct_str` with [`PctString::chars`].
25	for c in pct_string.chars() {
26		println!("{}", c);
27	}
28
29	// You can decode the string and every remove percent-encoded characters
30	// with the [`PctStr::decode`] method.
31	let decoded_string: String = pct_string.decode();
32	println!("{}", decoded_string);
33
34	Ok(())
35}

Source

pub fn chars(&self) -> Chars<'_> ⓘ

Iterate over the encoded characters of the string.

Examples found in repository ?

examples/str.rs (line 20)

5fn main() -> Result<(), InvalidPctString<&'static str>> {
6	// [`PctStr`] is the equivalent of [`str`] for percent-encoded strings.
7	let buffer = "Hello%20World%21";
8	// It is just a reference to `buffer`.
9	// It can fail if `buffer` is not a valid percent-encoded string.
10	let pct_str = PctStr::new(buffer)?;
11
12	// You can compare percent-encoded strings with a regular string.
13	assert!(pct_str == "Hello World!"); // => true
14
15	// The underlying string is unchanged.
16	assert!(pct_str.as_str() == "Hello%20World%21"); // => true
17
18	// Just as a regular string, you can iterate over the
19	// encoded characters of `pct_str` with [`PctStr::chars`].
20	for c in pct_str.chars() {
21		print!("{}", c);
22	}
23	// => Hello World!
24
25	println!("");
26
27	// You can decode the string and every remove percent-encoded characters
28	// with the [`PctStr::decode`] method.
29	let decoded_string: String = pct_str.decode();
30	println!("{}", decoded_string);
31	// => Hello World!
32
33	Ok(())
34}

More examples

Hide additional examples

examples/string.rs (line 25)

5fn main() -> Result<(), InvalidPctString<String>> {
6	// [`PctString`] is the equivalent of [`String`] for
7	// percent-encoded strings.
8	// The data is owned by `pct_string`.
9	let pct_string = PctString::from_string("Hello%20World%21".to_string())?;
10
11	// You can compare percent-encoded strings with a regular string.
12	assert!(pct_string == "Hello World!");
13
14	// The underlying string is percent-encoded.
15	assert!(pct_string.as_str() == "Hello%20World%21");
16
17	// You can get a reference to the string as a [`PctStr`].
18	assert!(
19		pct_string.as_pct_str()
20			== PctStr::new("Hello%20World%21").map_err(InvalidPctString::into_owned)?
21	);
22
23	// Just as a regular string, you can iterate over the
24	// encoded characters of `pct_str` with [`PctString::chars`].
25	for c in pct_string.chars() {
26		println!("{}", c);
27	}
28
29	// You can decode the string and every remove percent-encoded characters
30	// with the [`PctStr::decode`] method.
31	let decoded_string: String = pct_string.decode();
32	println!("{}", decoded_string);
33
34	Ok(())
35}

Source

pub fn bytes(&self) -> Bytes<'_> ⓘ

Iterate over the encoded bytes of the string.

Source

pub fn decode(&self) -> String

Decoding.

Return the string with the percent-encoded characters decoded.

Examples found in repository ?

examples/str.rs (line 29)

5fn main() -> Result<(), InvalidPctString<&'static str>> {
6	// [`PctStr`] is the equivalent of [`str`] for percent-encoded strings.
7	let buffer = "Hello%20World%21";
8	// It is just a reference to `buffer`.
9	// It can fail if `buffer` is not a valid percent-encoded string.
10	let pct_str = PctStr::new(buffer)?;
11
12	// You can compare percent-encoded strings with a regular string.
13	assert!(pct_str == "Hello World!"); // => true
14
15	// The underlying string is unchanged.
16	assert!(pct_str.as_str() == "Hello%20World%21"); // => true
17
18	// Just as a regular string, you can iterate over the
19	// encoded characters of `pct_str` with [`PctStr::chars`].
20	for c in pct_str.chars() {
21		print!("{}", c);
22	}
23	// => Hello World!
24
25	println!("");
26
27	// You can decode the string and every remove percent-encoded characters
28	// with the [`PctStr::decode`] method.
29	let decoded_string: String = pct_str.decode();
30	println!("{}", decoded_string);
31	// => Hello World!
32
33	Ok(())
34}

More examples

Hide additional examples

examples/string.rs (line 31)

5fn main() -> Result<(), InvalidPctString<String>> {
6	// [`PctString`] is the equivalent of [`String`] for
7	// percent-encoded strings.
8	// The data is owned by `pct_string`.
9	let pct_string = PctString::from_string("Hello%20World%21".to_string())?;
10
11	// You can compare percent-encoded strings with a regular string.
12	assert!(pct_string == "Hello World!");
13
14	// The underlying string is percent-encoded.
15	assert!(pct_string.as_str() == "Hello%20World%21");
16
17	// You can get a reference to the string as a [`PctStr`].
18	assert!(
19		pct_string.as_pct_str()
20			== PctStr::new("Hello%20World%21").map_err(InvalidPctString::into_owned)?
21	);
22
23	// Just as a regular string, you can iterate over the
24	// encoded characters of `pct_str` with [`PctString::chars`].
25	for c in pct_string.chars() {
26		println!("{}", c);
27	}
28
29	// You can decode the string and every remove percent-encoded characters
30	// with the [`PctStr::decode`] method.
31	let decoded_string: String = pct_string.decode();
32	println!("{}", decoded_string);
33
34	Ok(())
35}