Struct widestring::UStr

pub struct UStr<C: UChar> { /* fields omitted */ }

String slice reference for U16String.

UStr is to UString as str is to String.

UStr is not aware of nul values. Strings may or may not be nul-terminated, and may contain invalid and ill-formed UTF-16 or UTF-32 data. These strings are intended to be used with FFI functions that directly use string length, where the strings are known to have proper nul-termination already, or where strings are merely being passed through without modification.

UCStr should be used instead of nul-aware strings are required.

UStr can be converted to many other string types, including OsString and String, making proper Unicode FFI safe and easy.

Please prefer using the type aliases U16Str or U32Str or WideStr to using this type directly.

Methods

impl<C: UChar> UStr<C>

pub fn new<S: AsRef<Self> + ?Sized>(s: &S) -> &Self

Coerces a value into a UStr.

pub unsafe fn from_ptr<'a>(p: *const C, len: usize) -> &'a Self

Constructs a UStr from a pointer and a length.

The len argument is the number of elements, not the number of bytes.

Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements.

Panics

This function panics if p is null.

Caveat

The lifetime for the returned string is inferred from its usage. To prevent accidental misuse, it's suggested to tie the lifetime to whichever source lifetime is safe in the context, such as by providing a helper function taking the lifetime of a host value for the string, or by explicit annotation.

pub fn from_slice(slice: &[C]) -> &Self

Constructs a UStr from a slice of code points.

No checks are performed on the slice.

pub fn to_ustring(&self) -> UString<C>

Copies the wide string to a new owned UString.

pub fn as_slice(&self) -> &[C]

Converts to a slice of the wide string.

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

Returns a raw pointer to the wide string.

The pointer is valid only as long as the lifetime of this reference.

pub fn len(&self) -> usize

Returns the length of the wide string as number of elements (not number of bytes).

pub fn is_empty(&self) -> bool

Returns whether this wide string contains no data.

pub fn into_ustring(self: Box<Self>) -> UString<C>

Converts a Box<UStr> into a UString without copying or allocating.

impl UStr<u16>

pub fn to_os_string(&self) -> OsString

Decodes a wide string to an owned OsString.

This makes a string copy of the U16Str. Since U16Str makes no guarantees that it is valid UTF-16, there is no guarantee that the resulting OsString will be valid data.

Examples

use widestring::U16String;
use std::ffi::OsString;
let s = "MyString";
// Create a wide string from the string
let wstr = U16String::from_str(s);
// Create an OsString from the wide string
let osstr = wstr.to_os_string();

assert_eq!(osstr, OsString::from(s));

pub fn to_string(&self) -> Result<String, FromUtf16Error>

Copies the wide string to a String if it contains valid UTF-16 data.

Failures

Returns an error if the string contains any invalid UTF-16 data.

Examples

use widestring::U16String;
let s = "MyString";
// Create a wide string from the string
let wstr = U16String::from_str(s);
// Create a regular string from the wide string
let s2 = wstr.to_string().unwrap();

assert_eq!(s2, s);

pub fn to_string_lossy(&self) -> String

Copies the wide string to a String.

Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.

Examples

use widestring::U16String;
let s = "MyString";
// Create a wide string from the string
let wstr = U16String::from_str(s);
// Create a regular string from the wide string
let lossy = wstr.to_string_lossy();

assert_eq!(lossy, s);

impl UStr<u32>

pub unsafe fn from_char_ptr<'a>(p: *const char, len: usize) -> &'a Self

Constructs a U32Str from a char pointer and a length.

The len argument is the number of char elements, not the number of bytes.

Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements.

Panics

This function panics if p is null.

Caveat

The lifetime for the returned string is inferred from its usage. To prevent accidental misuse, it's suggested to tie the lifetime to whichever source lifetime is safe in the context, such as by providing a helper function taking the lifetime of a host value for the string, or by explicit annotation.

pub fn from_char_slice(slice: &[char]) -> &Self

Constructs a U32Str from a slice of u32 code points.

No checks are performed on the slice.

pub fn to_os_string(&self) -> OsString

Decodes a wide string to an owned OsString.

This makes a string copy of the U32Str. Since U32Str makes no guarantees that it is valid UTF-32, there is no guarantee that the resulting OsString will be valid data.

Examples

use widestring::U32String;
use std::ffi::OsString;
let s = "MyString";
// Create a wide string from the string
let wstr = U32String::from_str(s);
// Create an OsString from the wide string
let osstr = wstr.to_os_string();

assert_eq!(osstr, OsString::from(s));

pub fn to_string(&self) -> Result<String, FromUtf32Error>

Copies the wide string to a String if it contains valid UTF-32 data.

Failures

Returns an error if the string contains any invalid UTF-32 data.

Examples

use widestring::U32String;
let s = "MyString";
// Create a wide string from the string
let wstr = U32String::from_str(s);
// Create a regular string from the wide string
let s2 = wstr.to_string().unwrap();

assert_eq!(s2, s);

pub fn to_string_lossy(&self) -> String

Copies the wide string to a String.

Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.

Examples

use widestring::U32String;
let s = "MyString";
// Create a wide string from the string
let wstr = U32String::from_str(s);
// Create a regular string from the wide string
let lossy = wstr.to_string_lossy();

assert_eq!(lossy, s);

Trait Implementations

impl<C: Debug + UChar> Debug for UStr<C>

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

Formats the value using the given formatter.

impl<C: PartialEq + UChar> PartialEq for UStr<C>

fn eq(&self, other: &UStr<C>) -> bool

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

fn ne(&self, other: &UStr<C>) -> bool

This method tests for !=.

impl<C: Eq + UChar> Eq for UStr<C>

impl<C: PartialOrd + UChar> PartialOrd for UStr<C>

fn partial_cmp(&self, other: &UStr<C>) -> Option<Ordering>

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

fn lt(&self, other: &UStr<C>) -> bool

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

fn le(&self, other: &UStr<C>) -> bool

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

fn gt(&self, other: &UStr<C>) -> bool

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

fn ge(&self, other: &UStr<C>) -> bool

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

impl<C: Ord + UChar> Ord for UStr<C>

fn cmp(&self, other: &UStr<C>) -> 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.

impl<C: Hash + UChar> Hash for UStr<C>

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

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<C: UChar> PartialEq<UStr<C>> for UString<C>

fn eq(&self, other: &UStr<C>) -> bool

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

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

This method tests for !=.

impl<C: UChar> PartialOrd<UStr<C>> for UString<C>

fn partial_cmp(&self, other: &UStr<C>) -> Option<Ordering>

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

fn lt(&self, other: &Rhs) -> bool

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

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

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

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<'a, C: UChar> PartialEq<&'a UStr<C>> for UString<C>

fn eq(&self, other: &&'a UStr<C>) -> bool

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

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

This method tests for !=.

impl<'a, C: UChar> PartialOrd<&'a UStr<C>> for UString<C>

fn partial_cmp(&self, other: &&'a UStr<C>) -> Option<Ordering>

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

fn lt(&self, other: &Rhs) -> bool

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

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

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

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<C: UChar> Borrow<UStr<C>> for UString<C>

fn borrow(&self) -> &UStr<C>

Immutably borrows from an owned value.

impl<C: UChar> ToOwned for UStr<C>

type Owned = UString<C>

fn to_owned(&self) -> UString<C>

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

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

recently added

Uses borrowed data to replace owned data, usually by cloning.

impl<'a> From<&'a UStr<u16>> for Cow<'a, UStr<u16>>

fn from(s: &'a UStr<u16>) -> Self

Performs the conversion.

impl<'a> From<&'a UStr<u32>> for Cow<'a, UStr<u32>>

fn from(s: &'a UStr<u32>) -> Self

Performs the conversion.

impl<C: UChar> AsRef<UStr<C>> for UStr<C>

fn as_ref(&self) -> &Self

Performs the conversion.

impl<C: UChar> AsRef<UStr<C>> for UString<C>

fn as_ref(&self) -> &UStr<C>

Performs the conversion.

impl<C: UChar> AsRef<[C]> for UStr<C>

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

Performs the conversion.

impl<'a, C: UChar> From<&'a UStr<C>> for Box<UStr<C>>

fn from(s: &'a UStr<C>) -> Self

Performs the conversion.