Struct OwnedChar 

pub struct OwnedChar { /* private fields */ }

An owned Char.

Use Char::to_owned() to obtain this.

use mut_str::get_char;

let s = "Hello, World!";
let c = get_char(s, 1).unwrap();
let owned_c = c.to_owned();

assert_eq!(owned_c, 'e');

Implementations

impl OwnedChar

pub const unsafe fn new_unchecked(b: [u8; 4]) -> Self

Create a new OwnedChar without checking the validity of the buffer.

For a safe version, see OwnedChar::try_from().

Safety

There must be one valid UTF-8 encoded character at the start of the b.

pub unsafe fn from_bytes_unchecked(bytes: &[u8]) -> Self

Create a new OwnedChar without checking the validity of the bytes.

For a safe version, see OwnedChar::try_from().

Safety

There must be one valid UTF-8 encoded character at the start of bytes, which must be no longer than 4 bytes long.

pub unsafe fn buffer_mut(&mut self) -> &mut [u8; 4]

Get the underlying buffer as a mutable array.

Safety

The caller must ensure that when the mutable reference returned is dropped, there is a valid UTF-8 encoded character at the start of the buffer.

pub const fn into_bytes(self) -> [u8; 4]

Get the underlying buffer. This is not guaranteed to be valid UTF-8!

The first self.len() bytes will be valid UTF-8.

use mut_str::OwnedChar;

let c = OwnedChar::from('🌑');
assert_eq!(c.into_bytes(), [240, 159, 140, 145]);

Methods from Deref<Target = Char>

pub fn len(&self) -> usize

Get the length of the character in bytes.

This will be in the range 1..=4.

use mut_str::Char;

let s = "oΦ⏣🌑";

assert_eq!(Char::get(s, 0).unwrap().len(), 1);
assert_eq!(Char::get(s, 1).unwrap().len(), 2);
assert_eq!(Char::get(s, 2).unwrap().len(), 3);
assert_eq!(Char::get(s, 3).unwrap().len(), 4);

Examples found in repository

examples/iter.rs (line 8)

fn main() {
    let mut s = Box::<str>::from("oφ⏣🌑");

    // Iterate over the characters printing their length and bytes
    s.ref_iter()
        .for_each(|c| println!("{c:?}\tlength: {}, bytes: {:?}", c.len(), c.as_bytes()));

    // Iterate over each character trying to make them uppercase
    // (Result::ok is being used to ignore the result)
    s.mut_iter().for_each(|c| {
        c.try_make_uppercase().ok();
    });

    println!("\n{s:?}");
}

pub fn as_ptr(&self) -> *const u8

Get a pointer to the character (pointer).

pub fn as_mut_ptr(&mut self) -> *mut u8

Get a mutable pointer to the character (pointer).

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

Get the character as a byte slice (slice).

use mut_str::Char;

let s = "Hello, 🌍!";

let c = Char::get(s, 1).unwrap();
assert_eq!(c.as_bytes(), &[101]);

let c = Char::get(s, 7).unwrap();
assert_eq!(c.as_bytes(), &[240, 159, 140, 141]);

Examples found in repository

examples/iter.rs (line 8)

fn main() {
    let mut s = Box::<str>::from("oφ⏣🌑");

    // Iterate over the characters printing their length and bytes
    s.ref_iter()
        .for_each(|c| println!("{c:?}\tlength: {}, bytes: {:?}", c.len(), c.as_bytes()));

    // Iterate over each character trying to make them uppercase
    // (Result::ok is being used to ignore the result)
    s.mut_iter().for_each(|c| {
        c.try_make_uppercase().ok();
    });

    println!("\n{s:?}");
}

pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8]

Get the character as a mutable byte slice (slice).

Safety

See str::as_bytes_mut.

pub fn as_str(&self) -> &str

Get the character as a str.

use mut_str::Char;

let s = "Hello, 🌍!";

let c = Char::get(s, 1).unwrap();
assert_eq!(c.as_str(), "e");

let c = Char::get(s, 7).unwrap();
assert_eq!(c.as_str(), "🌍");

pub fn as_str_mut(&mut self) -> &mut str

Get the character as a mutable str.

use mut_str::Char;

let mut s = Box::<str>::from("Hello, 🌍!");

let c = Char::get_mut(&mut *s, 1).unwrap();
assert_eq!(c.as_str_mut(), "e");

let c = Char::get_mut(&mut *s, 7).unwrap();
assert_eq!(c.as_str_mut(), "🌍");

pub fn as_char(&self) -> char

Get the character as a char.

use mut_str::Char;

let s = "Hello, 🌍!";

let c = Char::get(s, 1).unwrap();
assert_eq!(c.as_char(), 'e');

let c = Char::get(s, 7).unwrap();
assert_eq!(c.as_char(), '🌍');

pub fn as_owned(&self) -> OwnedChar

Creates an OwnedChar from a borrowed Char.

use mut_str::{Char, OwnedChar};

let s = "Hello, 🌍!";

let c = Char::get(s, 1).unwrap();
assert_eq!(c.as_owned(), OwnedChar::from('e'));

let c = Char::get(s, 7).unwrap();
assert_eq!(c.as_owned(), OwnedChar::from('🌍'));

pub fn copy_to<'a>(&self, buffer: &'a mut [u8]) -> Option<&'a mut Self>

Copy the character to a byte buffer and get the str containing the inserted character. Returns None if buffer is shorter than self.

use mut_str::Char;

let s = "Hello, World!";
let c = Char::get(s, 1).unwrap();

let mut buffer = [0; 4];
let c2 = c.copy_to(&mut buffer).unwrap();

assert_eq!(c2, c);

pub fn replace<C>(&mut self, r: C) -> Result<(), LenNotEqual>

where C: Into<char>,

Replace the character with another of the same length.

use mut_str::Char;

let mut s = Box::<str>::from("oΦ⏣🌑");

let c = Char::get_mut(&mut *s, 0).unwrap();
assert!(c.replace('e').is_ok());
assert_eq!(&*s, "eΦ⏣🌑");

let c = Char::get_mut(&mut *s, 1).unwrap();
assert!(c.replace('a').is_err());

Errors

• If r, when utf8 encoded, does not have the same length as self, LenNotEqual will be returned.

Examples found in repository

examples/iter2.rs (line 10)

fn main() {
    let mut s = Box::<str>::from("Hello, World!");
    print!("{s:?}");

    // Capitalise all the 'l's.
    s.mut_iter()
        .filter(|c| c == &'l')
        .for_each(|c| c.replace('L').unwrap());

    println!(" -> {s:?}");
}

pub fn replace_with_pad_space<C>( &mut self, r: C, ) -> Result<(), ReplacementTooLong>

where C: Into<char>,

Replace the character with another of the same length or shorter. The remaining bytes will be filled with spaces.

use mut_str::Char;

let mut s = Box::<str>::from("oΦ⏣🌑");

let c = Char::get_mut(&mut *s, 0).unwrap();
assert!(c.replace_with_pad_space('e').is_ok());
assert_eq!(&*s, "eΦ⏣🌑");

let c = Char::get_mut(&mut *s, 1).unwrap();
assert!(c.replace_with_pad_space('a').is_ok());
assert_eq!(&*s, "ea ⏣🌑");

Errors

• If r, when utf8 encoded, is longer than self, ReplacementTooLong will be returned.

pub fn replace_with_pad<C>( &mut self, r: C, pad: u8, ) -> Result<(), ReplaceWithPadError>

where C: Into<char>,

Replace the character with another of the same length or shorter. The remaining bytes will be filled with pad.

use mut_str::Char;

let mut s = Box::<str>::from("oΦ⏣🌑");

let c = Char::get_mut(&mut *s, 0).unwrap();
assert!(c.replace_with_pad('e', b'b').is_ok());
assert_eq!(&*s, "eΦ⏣🌑");

let c = Char::get_mut(&mut *s, 1).unwrap();
assert!(c.replace_with_pad('a', b'b').is_ok());
assert_eq!(&*s, "eab⏣🌑");

Errors

• If pad is not valid utf8, ReplaceWithPadError::InvalidPad will be returned.
• If r, when utf8 encoded, is longer than self, ReplaceWithPadError::ReplacementLen will be returned.

pub fn replace_with_pad_char<C1, C2>( &mut self, r: C1, pad_char: C2, ) -> Result<(), ReplaceWithPadCharError>

where C1: Into<char>, C2: Into<char>,

Replace the character with another of the same length or shorter. The remaining bytes will be filled with pad, which must be one byte long.

use mut_str::Char;

let mut s = Box::<str>::from("oΦ⏣🌑");

let c = Char::get_mut(&mut *s, 0).unwrap();
assert!(c.replace_with_pad_char('e', 'b').is_ok());
assert_eq!(&*s, "eΦ⏣🌑");

let c = Char::get_mut(&mut *s, 1).unwrap();
assert!(c.replace_with_pad_char('a', 'b').is_ok());
assert_eq!(&*s, "eab⏣🌑");

Errors

• If pad_char, when utf8 encoded, is longer than Self, ReplaceWithPadCharError::PadCharTooLong will be returned.
• If r, when utf8 encoded, is longer than self, ReplaceWithPadCharError::ReplacementLen will be returned.

Examples found in repository

examples/char_replace.rs (line 13)

fn main() {
    let mut s = Box::<str>::from("👋🌍");
    println!("Original string:       {s:?}"); // "👋🌍"

    // Get a mutable reference to the second character
    let world = s.get_char_mut(1).unwrap();
    println!("Original character:    {world:?}"); // '🌍'

    // Replace '🌍' with 'w' and '_' as padding
    // '🌍' is 4 bytes long and 'w' is 1, so 3 '_'s will be added after.
    world.replace_with_pad_char('w', '_').unwrap();
    println!("Replacement character: {world:?}"); // 'w'

    println!("Final string:          {s:?}"); // "👋w___"
}

pub fn replace_with_pad_left_space<C>( &mut self, r: C, ) -> Result<&mut Self, ReplacementTooLong>

where C: Into<char>,

Replace the character with another of the same length or shorter, right aligned. The remaining bytes before the character will be filled with spaces.

use mut_str::Char;

let mut s = Box::<str>::from("oΦ⏣🌑");

let c = Char::get_mut(&mut *s, 0).unwrap();
assert!(c.replace_with_pad_left_space('e').is_ok());
assert_eq!(&*s, "eΦ⏣🌑");

let c = Char::get_mut(&mut *s, 1).unwrap();
let c2 = c.replace_with_pad_left_space('a').unwrap();
assert_eq!(c2, 'a');
assert_eq!(c, ' ');
assert_eq!(&*s, "e a⏣🌑");

Errors

• If r, when utf8 encoded, is longer than self, ReplacementTooLong will be returned.

pub fn replace_with_pad_left<C>( &mut self, r: C, pad: u8, ) -> Result<&mut Self, ReplaceWithPadError>

where C: Into<char>,

Replace the character with another of the same length or shorter, right aligned. The remaining bytes before the character will be filled with pad.

use mut_str::Char;

let mut s = Box::<str>::from("oΦ⏣🌑");

let c = Char::get_mut(&mut *s, 0).unwrap();
assert!(c.replace_with_pad_left('e', b'b').is_ok());
assert_eq!(&*s, "eΦ⏣🌑");

let c = Char::get_mut(&mut *s, 1).unwrap();
let c2 = c.replace_with_pad_left('a', b'b').unwrap();
assert_eq!(c2, 'a');
assert_eq!(c, 'b');
assert_eq!(&*s, "eba⏣🌑");

Errors

• If pad is not valid utf8, ReplaceWithPadError::InvalidPad will be returned.
• If r, when utf8 encoded, is longer than self, ReplaceWithPadError::ReplacementLen will be returned.

pub fn replace_with_pad_left_char<C1, C2>( &mut self, r: C1, pad_char: C2, ) -> Result<&mut Self, ReplaceWithPadCharError>

where C1: Into<char>, C2: Into<char>,

Replace the character with another of the same length or shorter, right aligned. The remaining bytes before the character will be filled with char, which must be one byte long.

use mut_str::Char;

let mut s = Box::<str>::from("oΦ⏣🌑");

let c = Char::get_mut(&mut *s, 0).unwrap();
assert!(c.replace_with_pad_left_char('e', 'b').is_ok());
assert_eq!(&*s, "eΦ⏣🌑");

let c = Char::get_mut(&mut *s, 1).unwrap();
let c2 = c.replace_with_pad_left_char('a', 'b').unwrap();
assert_eq!(c2, 'a');
assert_eq!(c, 'b');
assert_eq!(&*s, "eba⏣🌑");

Errors

• If pad_char, when utf8 encoded, is longer than Self, ReplaceWithPadCharError::PadCharTooLong will be returned.
• If r, when utf8 encoded, is longer than self, ReplaceWithPadCharError::ReplacementLen will be returned.

pub fn is_ascii(&self) -> bool

Checks if the value is within ASCII range.

use mut_str::Char;

let s = "oΦ⏣🌑";

let c = Char::get(s, 0).unwrap();
assert!(c.is_ascii());

let c = Char::get(s, 1).unwrap();
assert!(!c.is_ascii());

pub fn make_ascii_uppercase(&mut self)

Converts this type to its ASCII upper case equivalent in-place.

ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, but non-ASCII letters are unchanged.

use mut_str::Char;

let mut s = Box::<str>::from("oφ⏣🌑");

let c = Char::get_mut(&mut *s, 0).unwrap();
c.make_ascii_uppercase();

let c = Char::get_mut(&mut *s, 1).unwrap();
c.make_ascii_uppercase();

assert_eq!(&*s, "Oφ⏣🌑");

pub fn make_ascii_lowercase(&mut self)

Converts this type to its ASCII lower case equivalent in-place.

ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, but non-ASCII letters are unchanged.

use mut_str::Char;

let mut s = Box::<str>::from("OΦ⏣🌑");

let c = Char::get_mut(&mut *s, 0).unwrap();
c.make_ascii_lowercase();

let c = Char::get_mut(&mut *s, 1).unwrap();
c.make_ascii_lowercase();

assert_eq!(&*s, "oΦ⏣🌑");

pub fn try_make_uppercase(&mut self) -> Result<(), LenNotEqual>

Converts this type to its Unicode upper case equivalent in-place.

use mut_str::Char;

let mut s = Box::<str>::from("oφ⏣🌑");

let c = Char::get_mut(&mut *s, 0).unwrap();
c.try_make_uppercase().unwrap();

let c = Char::get_mut(&mut *s, 1).unwrap();
c.try_make_uppercase().unwrap();

assert_eq!(&*s, "OΦ⏣🌑");

Errors

If the character and its uppercase version is not the same length when utf8 encoded, LenNotEqual will be returned.

Examples found in repository

examples/iter.rs (line 13)

fn main() {
    let mut s = Box::<str>::from("oφ⏣🌑");

    // Iterate over the characters printing their length and bytes
    s.ref_iter()
        .for_each(|c| println!("{c:?}\tlength: {}, bytes: {:?}", c.len(), c.as_bytes()));

    // Iterate over each character trying to make them uppercase
    // (Result::ok is being used to ignore the result)
    s.mut_iter().for_each(|c| {
        c.try_make_uppercase().ok();
    });

    println!("\n{s:?}");
}

pub fn try_make_lowercase(&mut self) -> Result<(), LenNotEqual>

Converts this type to its Unicode lower case equivalent in-place.

use mut_str::Char;

let mut s = Box::<str>::from("OΦ⏣🌑");

let c = Char::get_mut(&mut *s, 0).unwrap();
c.try_make_lowercase().unwrap();

let c = Char::get_mut(&mut *s, 1).unwrap();
c.try_make_lowercase().unwrap();

assert_eq!(&*s, "oφ⏣🌑");

Errors

If the character and its lowercase version is not the same length when utf8 encoded, LenNotEqual will be returned.

Trait Implementations

impl AsMut<Char> for OwnedChar

fn as_mut(&mut self) -> &mut Char

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

impl AsRef<Char> for OwnedChar

fn as_ref(&self) -> &Char

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

impl Borrow<Char> for OwnedChar

fn borrow(&self) -> &Char

Immutably borrows from an owned value.

impl BorrowMut<Char> for OwnedChar

fn borrow_mut(&mut self) -> &mut Char

Mutably borrows from an owned value.

impl Clone for OwnedChar

fn clone(&self) -> OwnedChar

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for OwnedChar

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

Formats the value using the given formatter.

impl Deref for OwnedChar

type Target = Char

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for OwnedChar

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Display for OwnedChar

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

Formats the value using the given formatter.

impl<'a> Extend<&'a OwnedChar> for String

fn extend<T: IntoIterator<Item = &'a OwnedChar>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a> Extend<&'a mut OwnedChar> for String

fn extend<T: IntoIterator<Item = &'a mut OwnedChar>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl Extend<OwnedChar> for String

fn extend<T: IntoIterator<Item = OwnedChar>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<&Char> for OwnedChar

fn from(value: &Char) -> Self

Converts to this type from the input type.

impl From<char> for OwnedChar

fn from(value: char) -> Self

Converts to this type from the input type.

impl<'a> FromIterator<&'a OwnedChar> for Box<str>

fn from_iter<T: IntoIterator<Item = &'a OwnedChar>>(iter: T) -> Self

Creates a value from an iterator.

impl<'a> FromIterator<&'a OwnedChar> for String

fn from_iter<T: IntoIterator<Item = &'a OwnedChar>>(iter: T) -> Self

Creates a value from an iterator.

impl<'a> FromIterator<&'a mut OwnedChar> for Box<str>

fn from_iter<T: IntoIterator<Item = &'a mut OwnedChar>>(iter: T) -> Self

Creates a value from an iterator.

impl<'a> FromIterator<&'a mut OwnedChar> for String

fn from_iter<T: IntoIterator<Item = &'a mut OwnedChar>>(iter: T) -> Self

Creates a value from an iterator.

impl FromIterator<OwnedChar> for Box<str>

fn from_iter<T: IntoIterator<Item = OwnedChar>>(iter: T) -> Self

Creates a value from an iterator.

impl FromIterator<OwnedChar> for String

fn from_iter<T: IntoIterator<Item = OwnedChar>>(iter: T) -> Self

Creates a value from an iterator.

impl Ord for OwnedChar

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<OwnedChar> for Char

fn eq(&self, other: &OwnedChar) -> 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<T> PartialEq<T> for OwnedChar

where Char: PartialEq<T>,

fn eq(&self, other: &T) -> 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 PartialOrd<OwnedChar> for Char

fn partial_cmp(&self, other: &OwnedChar) -> 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<T> PartialOrd<T> for OwnedChar

where Char: PartialOrd<T>,

fn partial_cmp(&self, other: &T) -> 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 TryFrom<&[u8]> for OwnedChar

type Error = TryFromBytesError

The type returned in the event of a conversion error.

fn try_from(value: &[u8]) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&str> for OwnedChar

type Error = TryFromStrError

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<[u8; 4]> for OwnedChar

type Error = TryFromBytesError

The type returned in the event of a conversion error.

fn try_from(value: [u8; 4]) -> Result<Self, Self::Error>

Performs the conversion.

impl Eq for OwnedChar