Struct WStr

pub struct WStr<E: 'static + ByteOrder> { /* private fields */ }

A UTF-16 str-like type with little- or big-endian byte order.

This mostly behaves like str does for UTF-8 encoded bytes slices, but works with UTF-16 encoded byte slices. The endianess is determined by the type parameter.

Examples

use utf16string::{LE, WStr};

let b = b"h\x00e\x00l\x00l\x00o\x00";
let s: &WStr<LE> = WStr::from_utf16le(b)?;

let chars: Vec<char> = s.chars().collect();
assert_eq!(chars, vec!['h', 'e', 'l', 'l', 'o']);

assert_eq!(s.to_utf8(), "hello");

Implementations

impl WStr<LittleEndian>

pub fn from_utf16le(raw: &[u8]) -> Result<&Self, Utf16Error>

Creates a new &WStr<LE>.

pub fn from_utf16le_mut(raw: &mut [u8]) -> Result<&mut Self, Utf16Error>

Creates a new &mut WStr<LE>.

pub unsafe fn from_utf16le_unchecked(raw: &[u8]) -> &Self

Creates a new WStr with little-endian byte-ordering.

This is a shortcut to easily create WStr<LE> without having to specify the type explicitly.

Example

use utf16string::{LE, WStr};

let b = b"h\x00i\x00";
let s: &WStr<LE> = unsafe { WStr::from_utf16_unchecked(b) };
let t = unsafe { WStr::from_utf16le_unchecked(b) };
assert_eq!(s, t);

Safety

You must guarantee that the buffer passed in is encoded correctly as UTF-16 with little-endian byte-order, otherwise you will get undefined behaviour.

pub unsafe fn from_utf16le_unchecked_mut(raw: &mut [u8]) -> &mut Self

Creates a new &mut WStr<LE>.

Safety

You must guarantee that the buffer passed in is encoded correctly as UTF-16 with little-endian byte-order, otherwise you will get undefined behaviour.

impl WStr<BigEndian>

pub fn from_utf16be(raw: &[u8]) -> Result<&Self, Utf16Error>

Creates a new &WStr<BE>.

pub fn from_utf16be_mut(raw: &mut [u8]) -> Result<&mut Self, Utf16Error>

Creates a new &mut WStr<BE>.

pub unsafe fn from_utf16be_unchecked(raw: &[u8]) -> &Self

Creates a new &WStr<BE> from an existing byte-slice with big-endian byte-ordering.

This is a shortcut to easily create WStr<BE> without having to specify the type explicitly.

Example

use utf16string::{BE, WStr};

let b = b"h\x00i\x00";
let s: &WStr<BE> = unsafe { WStr::from_utf16_unchecked(b) };
let t = unsafe { WStr::from_utf16be_unchecked(b) };
assert_eq!(s, t);

Safety

You must guarantee that the buffer passed in is encoded correctly as UTF-16 with big-endian byte-order, otherwise you will get undefined behaviour.

pub unsafe fn from_utf16be_unchecked_mut(raw: &mut [u8]) -> &mut Self

Creates a new &mut WStr<BE>.

Safety

You must guarantee that the buffer passed in is encoded correctly as UTF-16 with big-endian byte-order, otherwise you will get undefined behaviour.

impl<E> WStr<E>

where E: ByteOrder,

pub fn from_utf16(raw: &[u8]) -> Result<&Self, Utf16Error>

Creates a new &WStr<E> from an existing UTF-16 byte-slice.

If the byte-slice is not valid Utf16Error is returned.

pub fn from_utf16_mut(raw: &mut [u8]) -> Result<&mut Self, Utf16Error>

Creates a new &mut WStr<E> from an existing UTF-16 byte-slice.

If the byte-slice is not valid Utf16Error is returned.

pub unsafe fn from_utf16_unchecked(raw: &[u8]) -> &Self

Creates a new &WStr<E> from an existing UTF-16 byte-slice.

Safety

You must guarantee that the buffer passed in is encoded correctly otherwise you will get undefined behaviour. Be aware of the byte-level endianess.

pub unsafe fn from_utf16_unchecked_mut(raw: &mut [u8]) -> &mut Self

Like WStr::from_utf16_unchecked but return a mutable reference.

Safety

You must guarantee that the buffer passed in is encoded correctly otherwise you will get undefined behaviour.

pub fn len(&self) -> usize

The length in bytes, not chars or graphemes.

pub fn is_empty(&self) -> bool

Returns true if the WStr::len is zero.

pub fn is_char_boundary(&self, index: usize) -> bool

Returns true if the index into the bytes is on a char boundary.

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

Converts to a byte slice.

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

Converts to a mutable byte slice.

Safety

When mutating the bytes it must still be valid encoded UTF-16 with the correct byte-order, otherwise you will get undefined behaviour.

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

Converts to a raw pointer to the byte slice.

This is currently not const fn because this is not yet stable with a trait bound.

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

Converts to a mutable raw pointer to the byte slice.

pub fn get<I>(&self, index: I) -> Option<&<I as SliceIndex<WStr<E>>>::Output>

where I: SliceIndex<WStr<E>>,

Returns a subslice of self.

The slice indices are on byte offsets of the underlying UTF-16 encoded buffer, if the subslice is not on character boundaries or otherwise invalid this will return None.

pub fn get_mut<I>( &mut self, index: I, ) -> Option<&mut <I as SliceIndex<WStr<E>>>::Output>

where I: SliceIndex<WStr<E>>,

Returns a mutable subslice of self.

The slice indices are on byte offsets of the underlying UTF-16 encoded buffer, if the subslice is not on character boundaries or otherwise invalid this will return None.

pub unsafe fn get_unchecked<I>( &self, index: I, ) -> &<I as SliceIndex<WStr<E>>>::Output

where I: SliceIndex<WStr<E>>,

Returns a subslice of self.

Safety

Like WStr::get but this results in undefined behaviour if the sublice is not on character boundaries or otherwise invalid.

pub unsafe fn get_unchecked_mut<I>( &mut self, index: I, ) -> &mut <I as SliceIndex<WStr<E>>>::Output

where I: SliceIndex<WStr<E>>,

Returns a mutable subslice of self.

Safety

Lice WStr::get_mut but this results in undefined behaviour if the subslice is not on character boundaries or otherwise invalid.

pub fn chars(&self) -> WStrChars<'_, E>

Returns an iterator of the chars of a string slice.

pub fn char_indices(&self) -> WStrCharIndices<'_, E>

Returns and iterator over the chars of a string slice and their positions.

pub fn to_utf8(&self) -> String

Returns this WStr as a new owned String.

pub fn is_ascii(&self) -> bool

Returns true if all characters in the string are ASCII.

Trait Implementations

impl<E> AsRef<[u8]> for WStr<E>

where E: ByteOrder,

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

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

impl<E: Debug + 'static + ByteOrder> Debug for WStr<E>

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

Formats the value using the given formatter.

impl<E> Display for WStr<E>

where E: ByteOrder,

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

Formats the value using the given formatter.

impl<E: Hash + 'static + ByteOrder> Hash for WStr<E>

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

Feeds this value into the given Hasher.

impl<I, E> Index<I> for WStr<E>

where I: SliceIndex<WStr<E>>, E: ByteOrder,

type Output = <I as SliceIndex<WStr<E>>>::Output

The returned type after indexing.

fn index(&self, index: I) -> &I::Output

Performs the indexing (container[index]) operation.

impl<I, E> IndexMut<I> for WStr<E>

where I: SliceIndex<WStr<E>>, E: ByteOrder,

fn index_mut(&mut self, index: I) -> &mut I::Output

Performs the mutable indexing (container[index]) operation.

impl<E: PartialEq + 'static + ByteOrder> PartialEq for WStr<E>

fn eq(&self, other: &WStr<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> SliceIndex<WStr<E>> for Range<usize>

where E: ByteOrder,

Implements substring slicing with syntax &self[begin .. end] or &mut self[begin .. end].

type Output = WStr<E>

The result of slicing, another slice of the same type as you started with normally.

fn get(self, slice: &WStr<E>) -> Option<&Self::Output>

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut WStr<E>) -> Option<&mut Self::Output>

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked(self, slice: &WStr<E>) -> &Self::Output

Like SliceIndex::get but without bounds checking.

unsafe fn get_unchecked_mut(self, slice: &mut WStr<E>) -> &mut Self::Output

Like SliceIndex::get_mut but without bounds checking.

fn index(self, slice: &WStr<E>) -> &Self::Output

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut WStr<E>) -> &mut Self::Output

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl<E> SliceIndex<WStr<E>> for RangeFrom<usize>

where E: ByteOrder,

Implements substring slicing with syntax &self[begin ..] or &mut self[begin ..].

type Output = WStr<E>

The result of slicing, another slice of the same type as you started with normally.

fn get(self, slice: &WStr<E>) -> Option<&Self::Output>

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut WStr<E>) -> Option<&mut Self::Output>

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked(self, slice: &WStr<E>) -> &Self::Output

Like SliceIndex::get but without bounds checking.

unsafe fn get_unchecked_mut(self, slice: &mut WStr<E>) -> &mut Self::Output

Like SliceIndex::get_mut but without bounds checking.

fn index(self, slice: &WStr<E>) -> &Self::Output

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut WStr<E>) -> &mut Self::Output

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl<E> SliceIndex<WStr<E>> for RangeFull

where E: ByteOrder,

Implments substring slicing with syntax &self[..] or &mut self[..].

Unlike other implementations this can never panic.

type Output = WStr<E>

The result of slicing, another slice of the same type as you started with normally.

fn get(self, slice: &WStr<E>) -> Option<&Self::Output>

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut WStr<E>) -> Option<&mut Self::Output>

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked(self, slice: &WStr<E>) -> &Self::Output

Like SliceIndex::get but without bounds checking.

unsafe fn get_unchecked_mut(self, slice: &mut WStr<E>) -> &mut Self::Output

Like SliceIndex::get_mut but without bounds checking.

fn index(self, slice: &WStr<E>) -> &Self::Output

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut WStr<E>) -> &mut Self::Output

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl<E> SliceIndex<WStr<E>> for RangeInclusive<usize>

where E: ByteOrder,

Implements substring slicing with syntax &self[begin ..= end] or &mut self[begin ..= end].

type Output = WStr<E>

The result of slicing, another slice of the same type as you started with normally.

fn get(self, slice: &WStr<E>) -> Option<&Self::Output>

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut WStr<E>) -> Option<&mut Self::Output>

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked(self, slice: &WStr<E>) -> &Self::Output

Like SliceIndex::get but without bounds checking.

unsafe fn get_unchecked_mut(self, slice: &mut WStr<E>) -> &mut Self::Output

Like SliceIndex::get_mut but without bounds checking.

fn index(self, slice: &WStr<E>) -> &Self::Output

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut WStr<E>) -> &mut Self::Output

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl<E> SliceIndex<WStr<E>> for RangeTo<usize>

where E: ByteOrder,

Implements substring slicing with syntax &self[.. end] or &mut self[.. end].

type Output = WStr<E>

The result of slicing, another slice of the same type as you started with normally.

fn get(self, slice: &WStr<E>) -> Option<&Self::Output>

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut WStr<E>) -> Option<&mut Self::Output>

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked(self, slice: &WStr<E>) -> &Self::Output

Like SliceIndex::get but without bounds checking.

unsafe fn get_unchecked_mut(self, slice: &mut WStr<E>) -> &mut Self::Output

Like SliceIndex::get_mut but without bounds checking.

fn index(self, slice: &WStr<E>) -> &Self::Output

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut WStr<E>) -> &mut Self::Output

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl<E> SliceIndex<WStr<E>> for RangeToInclusive<usize>

where E: ByteOrder,

Implements substring slicing with syntax &self[..= end] or &mut self[..= end].

type Output = WStr<E>

The result of slicing, another slice of the same type as you started with normally.

fn get(self, slice: &WStr<E>) -> Option<&Self::Output>

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut WStr<E>) -> Option<&mut Self::Output>

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked(self, slice: &WStr<E>) -> &Self::Output

Like SliceIndex::get but without bounds checking.

unsafe fn get_unchecked_mut(self, slice: &mut WStr<E>) -> &mut Self::Output

Like SliceIndex::get_mut but without bounds checking.

fn index(self, slice: &WStr<E>) -> &Self::Output

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut WStr<E>) -> &mut Self::Output

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl<E: Eq + 'static + ByteOrder> Eq for WStr<E>

impl<E: 'static + ByteOrder> StructuralPartialEq for WStr<E>