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>

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: (unsized)