Struct encode_unicode::Utf16Char

pub struct Utf16Char { /* fields omitted */ }

An unicode codepoint stored as UTF-16.

It can be borrowed as an u16 slice, and has the same size as char.

Methods

impl Utf16Char

pub fn from_str_start(s: &str) -> Result<(Self, usize), EmptyStrError>

Create an Utf16Char from the first codepoint in a string slice, converting from UTF-8 to UTF-16.

The returned usize is the number of UTF-8 bytes used from the str, and not the number of UTF-16 units.

Returns an error if the str is empty.

Examples

use encode_unicode::Utf16Char;

assert_eq!(Utf16Char::from_str_start("a"), Ok((Utf16Char::from('a'),1)));
assert_eq!(Utf16Char::from_str_start("ab"), Ok((Utf16Char::from('a'),1)));
assert_eq!(Utf16Char::from_str_start("🂠 "), Ok((Utf16Char::from('🂠'),4)));
assert_eq!(Utf16Char::from_str_start("é"), Ok((Utf16Char::from('e'),1)));// 'e'+u301 combining mark
assert!(Utf16Char::from_str_start("").is_err());

pub fn from_slice_start(src: &[u16]) -> Result<(Self, usize), InvalidUtf16Slice>

Validate and store the first UTF-16 codepoint in the slice. Also return how many units were needed.

pub unsafe fn from_slice_start_unchecked(src: &[u16]) -> (Self, usize)

Store the first UTF-16 codepoint of the slice.

Safety

The slice must be non-empty and start with a valid UTF-16 codepoint.
The length of the slice is never checked.

pub fn from_array(units: [u16; 2]) -> Result<Self, InvalidUtf16Array>

Validate and store an UTF-16 array as returned from char.to_utf16_array().

Examples

use encode_unicode::Utf16Char;
use encode_unicode::error::InvalidUtf16Array;

assert_eq!(Utf16Char::from_array(['x' as u16, 'y' as u16]), Ok(Utf16Char::from('x')));
assert_eq!(Utf16Char::from_array(['睷' as u16, 0]), Ok(Utf16Char::from('睷')));
assert_eq!(Utf16Char::from_array([0xda6f, 0xdcde]), Ok(Utf16Char::from('\u{abcde}')));
assert_eq!(Utf16Char::from_array([0xf111, 0xdbad]), Ok(Utf16Char::from('\u{f111}')));
assert_eq!(Utf16Char::from_array([0xdaaf, 0xdaaf]), Err(InvalidUtf16Array::SecondIsNotTrailingSurrogate));
assert_eq!(Utf16Char::from_array([0xdcac, 0x9000]), Err(InvalidUtf16Array::FirstIsTrailingSurrogate));

pub unsafe fn from_array_unchecked(units: [u16; 2]) -> Self

Create an Utf16Char from an array as returned from char.to_utf16_array().

Safety

The units must form a valid codepoint, and the second unit must be 0 when a surrogate pair is not required. Violating this can easily lead to undefined behavior, although unlike char bad Utf16Chars simply existing is not immediately UB.

pub fn from_tuple(utf16: (u16, Option<u16>)) -> Result<Self, InvalidUtf16Tuple>

Validate and store a UTF-16 pair as returned from char.to_utf16_tuple().

pub unsafe fn from_tuple_unchecked(utf16: (u16, Option<u16>)) -> Self

Create an Utf16Char from a tuple as returned from char.to_utf16_tuple().

Safety

The units must form a valid codepoint with the second being 0 when a surrogate pair is not required. Violating this can easily lead to undefined behavior.

pub fn from_bmp(bmp_codepoint: u16) -> Result<Self, NonBMPError>

Create an Utf16Char from a single unit.

Codepoints < '\u{1_0000}' (which fit in a u16) are part of the basic multilingual plane unless they are reserved for surrogate pairs.

Errors

Returns NonBMPError if the unit is in the range 0xd800..0xe000 (which means that it's part of a surrogat pair)

Examples

assert_eq!(Utf16Char::from_bmp(0x40).unwrap(), '@');
assert_eq!(Utf16Char::from_bmp('ø' as u16).unwrap(), 'ø');
assert!(Utf16Char::from_bmp(0xdddd).is_err());

pub unsafe fn from_bmp_unchecked(bmp_codepoint: u16) -> Self

Create an Utf16Char from a single unit without checking that it's a valid codepoint on its own.

Safety

The unit must be less than 0xd800 or greater than 0xdfff. In other words, not part of a surrogate pair.
Violating this can easily lead to undefined behavior.

pub fn is_bmp(&self) -> bool

Checks that the codepoint is in the basic multilingual plane.

Examples

assert_eq!(Utf16Char::from('e').is_bmp(), true);
assert_eq!(Utf16Char::from('€').is_bmp(), true);
assert_eq!(Utf16Char::from('𝔼').is_bmp(), false);

pub fn len(self) -> usize

The number of units this character is made up of.

Is either 1 or 2 and identical to .as_char().len_utf16() or .as_ref().len().

pub fn is_ascii(&self) -> bool

Checks that the codepoint is an ASCII character.

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

Checks that two characters are an ASCII case-insensitive match.

Is equivalent to a.to_ascii_lowercase() == b.to_ascii_lowercase().

pub fn to_ascii_uppercase(&self) -> Self

Converts the character to its ASCII upper case equivalent.

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

pub fn to_ascii_lowercase(&self) -> Self

Converts the character to its ASCII lower case equivalent.

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

pub fn make_ascii_uppercase(&mut self)

Converts the character 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.

pub fn make_ascii_lowercase(&mut self)

Converts the character 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.

pub fn to_char(self) -> char

Convert from UTF-16 to UTF-32

pub fn to_slice(self, dst: &mut [u16]) -> usize

Write the internal representation to a slice, and then returns the number of u16s written.

Panics

Will panic the buffer is too small; You can get the required length from .len(), but a buffer of length two is always large enough.

pub fn to_array(self) -> [u16; 2]

Get the character represented as an array of two units.

The second u16 is zero for codepoints that fit in one unit.

pub fn to_tuple(self) -> (u16, Option<u16>)

The second u16 is used for surrogate pairs.

Trait Implementations

impl From<Utf16Char> for Utf8Char

fn from(utf16: Utf16Char) -> Utf8Char

Performs the conversion.

impl From<char> for Utf16Char

fn from(c: char) -> Self

Performs the conversion.

impl From<Utf8Char> for Utf16Char

fn from(utf8: Utf8Char) -> Utf16Char

Performs the conversion.

impl From<Utf16Char> for char

fn from(uc: Utf16Char) -> char

Performs the conversion.

impl From<AsciiChar> for Utf16Char

Requires the feature "ascii".

fn from(ac: AsciiChar) -> Self

Performs the conversion.

impl From<Utf16Char> for Utf16Iterator

fn from(uc: Utf16Char) -> Self

Performs the conversion.

impl Ord for Utf16Char

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

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

Restrict a value to a certain interval.

impl PartialOrd<Utf16Char> for Utf8Char

fn partial_cmp(&self, u16c: &Utf16Char) -> Option<Ordering>

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

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

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

impl PartialOrd<Utf16Char> for Utf16Char

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

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

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

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

impl PartialOrd<char> for Utf16Char

fn partial_cmp(&self, u32c: &char) -> Option<Ordering>

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

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

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

impl PartialOrd<Utf16Char> for char

fn partial_cmp(&self, u16c: &Utf16Char) -> Option<Ordering>

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

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

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

impl PartialOrd<Utf8Char> for Utf16Char

fn partial_cmp(&self, u8c: &Utf8Char) -> Option<Ordering>

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

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

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

impl PartialOrd<AsciiChar> for Utf16Char

Utf16Chars that are not ASCII always compare greater.

fn partial_cmp(&self, ascii: &AsciiChar) -> Option<Ordering>

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

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

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

impl PartialOrd<Utf16Char> for AsciiChar

Utf16Chars that are not ASCII always compare greater.

fn partial_cmp(&self, u16c: &Utf16Char) -> Option<Ordering>

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

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

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

impl PartialEq<Utf16Char> for Utf8Char

fn eq(&self, u16c: &Utf16Char) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<Utf16Char> for Utf16Char

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl PartialEq<char> for Utf16Char

fn eq(&self, u32c: &char) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<Utf16Char> for char

fn eq(&self, u16c: &Utf16Char) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<Utf8Char> for Utf16Char

fn eq(&self, u8c: &Utf8Char) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<u16> for Utf16Char

Only considers the unit equal if the codepoint of the Utf16Char is not made up of a surrogate pair.

There is no impl in the opposite direction, as this should only be used to compare Utf16Chars against constants.

Examples

assert!(Utf16Char::from('6') == b'6' as u16);
assert!(Utf16Char::from('\u{FFFF}') == 0xffff_u16);
assert!(Utf16Char::from_tuple((0xd876, Some(0xdef9))).unwrap() != 0xd876_u16);

fn eq(&self, unit: &u16) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<u8> for Utf16Char

Only considers the byte equal if the codepoint of the Utf16Char is <= U+FF.

Examples

assert!(Utf16Char::from('6') == b'6');
assert!(Utf16Char::from('\u{00FF}') == b'\xff');
assert!(Utf16Char::from('\u{0100}') != b'\0');

fn eq(&self, byte: &u8) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<AsciiChar> for Utf16Char

Utf16Chars that are not ASCII never compare equal.

fn eq(&self, ascii: &AsciiChar) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<Utf16Char> for AsciiChar

Utf16Chars that are not ASCII never compare equal.

fn eq(&self, u16c: &Utf16Char) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Default for Utf16Char

fn default() -> Utf16Char

Returns the "default value" for a type.

impl IntoIterator for Utf16Char

type Item = u16

The type of the elements being iterated over.

type IntoIter = Utf16Iterator

Which kind of iterator are we turning this into?

Important traits for Utf16Iterator

impl Iterator for Utf16Iterator type Item = u16;

fn into_iter(self) -> Utf16Iterator

Iterate over the units.

impl Extend<Utf16Char> for Vec<u16>

fn extend<I: IntoIterator<Item = Utf16Char>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

impl<'a> Extend<&'a Utf16Char> for Vec<u16>

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

Extends a collection with the contents of an iterator.

impl Extend<Utf16Char> for String

fn extend<I: IntoIterator<Item = Utf16Char>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

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

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

Extends a collection with the contents of an iterator.

impl Clone for Utf16Char

fn clone(&self) -> Utf16Char

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Eq for Utf16Char

impl AsRef<[u16]> for Utf16Char

fn as_ref(&self) -> &[u16]

Performs the conversion.

impl Copy for Utf16Char

impl Deref for Utf16Char

type Target = [u16]

The resulting type after dereferencing.

fn deref(&self) -> &[u16]

Dereferences the value.

impl Display for Utf16Char

fn fmt(&self, fmtr: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Debug for Utf16Char

fn fmt(&self, fmtr: &mut Formatter) -> Result

Formats the value using the given formatter.

impl FromStr for Utf16Char

type Err = FromStrError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, FromStrError>

Create an Utf16Char from a string slice. The string must contain exactly one codepoint.

Examples

use encode_unicode::error::FromStrError::*;
use encode_unicode::Utf16Char;
use std::str::FromStr;

assert_eq!(Utf16Char::from_str("a"), Ok(Utf16Char::from('a')));
assert_eq!(Utf16Char::from_str("🂠"), Ok(Utf16Char::from('🂠')));
assert_eq!(Utf16Char::from_str(""), Err(Empty));
assert_eq!(Utf16Char::from_str("ab"), Err(MultipleCodepoints));
assert_eq!(Utf16Char::from_str("é"), Err(MultipleCodepoints));// 'e'+u301 combining mark

impl Hash for Utf16Char

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

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl FromIterator<Utf16Char> for Vec<u16>

fn from_iter<I: IntoIterator<Item = Utf16Char>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a> FromIterator<&'a Utf16Char> for Vec<u16>

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

Creates a value from an iterator.

impl FromIterator<Utf16Char> for String

fn from_iter<I: IntoIterator<Item = Utf16Char>>(iter: I) -> Self

Creates a value from an iterator.

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

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

Creates a value from an iterator.

impl Borrow<[u16]> for Utf16Char

fn borrow(&self) -> &[u16]

Immutably borrows from an owned value.

impl AsciiExt for Utf16Char

type Owned = Self

Deprecated since 1.26.0:

use inherent methods instead

Container type for copied ASCII characters.

fn is_ascii(&self) -> bool

Deprecated since 1.26.0:

use inherent methods instead

Checks if the value is within the ASCII range.

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

Deprecated since 1.26.0:

use inherent methods instead

Checks that two values are an ASCII case-insensitive match.

fn to_ascii_uppercase(&self) -> Self

Deprecated since 1.26.0:

use inherent methods instead

Makes a copy of the value in its ASCII upper case equivalent.

fn to_ascii_lowercase(&self) -> Self

Deprecated since 1.26.0:

use inherent methods instead

Makes a copy of the value in its ASCII lower case equivalent.

fn make_ascii_uppercase(&mut self)

Deprecated since 1.26.0:

use inherent methods instead

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

fn make_ascii_lowercase(&mut self)

Deprecated since 1.26.0:

use inherent methods instead

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

impl ToAsciiChar for Utf16Char

Requires the feature "ascii".

fn to_ascii_char(self) -> Result<AsciiChar, ToAsciiCharError>

Convert to AsciiChar.

unsafe fn to_ascii_char_unchecked(self) -> AsciiChar

Convert to AsciiChar without checking that it is an ASCII character.