Struct utfx::UString

#[repr(transparent)]pub struct UString<C: UChar> { /* fields omitted */ }

An owned, mutable "wide" string for FFI that is not nul-aware.

UString 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.

UCString should be used instead if nul-aware strings are required.

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

Please prefer using the type aliases U16String or U32String or WideString to using this type directly.

Examples

The following example constructs a U16String and shows how to convert a U16String to a regular Rust String.

use widestring::U16String;
let s = "Test";
// Create a wide string from the rust string
let wstr = U16String::from_str(s);
// Convert back to a rust string
let rust_str = wstr.to_string_lossy();
assert_eq!(rust_str, "Test");

The same example using U32String instead:

use widestring::U32String;
let s = "Test";
// Create a wide string from the rust string
let wstr = U32String::from_str(s);
// Convert back to a rust string
let rust_str = wstr.to_string_lossy();
assert_eq!(rust_str, "Test");

Implementations

impl<C: UChar> UString<C>

pub fn new() -> Self

Constructs a new empty UString.

pub fn from_vec(raw: impl Into<Vec<C>>) -> Self

Constructs a UString from a vector of possibly invalid or ill-formed UTF-16 or UTF-32 data.

No checks are made on the contents of the vector.

Examples

use widestring::U16String;
let v = vec![84u16, 104u16, 101u16]; // 'T' 'h' 'e'
// Create a wide string from the vector
let wstr = U16String::from_vec(v);

use widestring::U32String;
let v = vec![84u32, 104u32, 101u32]; // 'T' 'h' 'e'
// Create a wide string from the vector
let wstr = U32String::from_vec(v);

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

Constructs a UString 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

Panics if len is greater than 0 but p is a null pointer.

pub fn with_capacity(capacity: usize) -> Self

Creates a UString with the given capacity.

The string will be able to hold exactly capacity partial code units without reallocating. If capacity is set to 0, the string will not initially allocate.

pub fn capacity(&self) -> usize

Returns the capacity this UString can hold without reallocating.

pub fn clear(&mut self)

Truncate the UString to zero length.

pub fn reserve(&mut self, additional: usize)

Reserves the capacity for at least additional more capacity to be inserted in the given UString.

More space may be reserved to avoid frequent allocations.

pub fn reserve_exact(&mut self, additional: usize)

Reserves the minimum capacity for exactly additional more capacity to be inserted in the given UString. Does nothing if the capcity is already sufficient.

Note that the allocator may give more space than is requested. Therefore capacity can not be relied upon to be precisely minimal. Prefer reserve if future insertions are expected.

pub fn into_vec(self) -> Vec<C>

Converts the wide string into a Vec, consuming the string in the process.

pub fn as_ustr(&self) -> &UStr<C>

Converts to a UStr reference.

pub fn push(&mut self, s: impl AsRef<UStr<C>>)

Extends the wide string with the given &UStr.

No checks are performed on the strings. It is possible to end up nul values inside the string, and it is up to the caller to determine if that is acceptable.

Examples

use widestring::U16String;
let s = "MyString";
let mut wstr = U16String::from_str(s);
let cloned = wstr.clone();
// Push the clone to the end, repeating the string twice.
wstr.push(cloned);

assert_eq!(wstr.to_string().unwrap(), "MyStringMyString");

use widestring::U32String;
let s = "MyString";
let mut wstr = U32String::from_str(s);
let cloned = wstr.clone();
// Push the clone to the end, repeating the string twice.
wstr.push(cloned);

assert_eq!(wstr.to_string().unwrap(), "MyStringMyString");

pub fn push_slice(&mut self, s: impl AsRef<[C]>)

Extends the wide string with the given slice.

No checks are performed on the strings. It is possible to end up nul values inside the string, and it is up to the caller to determine if that is acceptable.

Examples

use widestring::U16String;
let s = "MyString";
let mut wstr = U16String::from_str(s);
let cloned = wstr.clone();
// Push the clone to the end, repeating the string twice.
wstr.push_slice(cloned);

assert_eq!(wstr.to_string().unwrap(), "MyStringMyString");

use widestring::U32String;
let s = "MyString";
let mut wstr = U32String::from_str(s);
let cloned = wstr.clone();
// Push the clone to the end, repeating the string twice.
wstr.push_slice(cloned);

assert_eq!(wstr.to_string().unwrap(), "MyStringMyString");

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the UString to match its length.

Examples

use widestring::U16String;

let mut s = U16String::from_str("foo");

s.reserve(100);
assert!(s.capacity() >= 100);

s.shrink_to_fit();
assert_eq!(3, s.capacity());

use widestring::U32String;

let mut s = U32String::from_str("foo");

s.reserve(100);
assert!(s.capacity() >= 100);

s.shrink_to_fit();
assert_eq!(3, s.capacity());

pub fn into_boxed_ustr(self) -> Box<UStr<C>>

Converts this UString into a boxed UStr.

Examples

use widestring::{U16String, U16Str};

let s = U16String::from_str("hello");

let b: Box<U16Str> = s.into_boxed_ustr();

use widestring::{U32String, U32Str};

let s = U32String::from_str("hello");

let b: Box<U32Str> = s.into_boxed_ustr();

impl UString<u16>

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

Encodes a U16String copy from a str.

This makes a wide string copy of the str. Since str will always be valid UTF-8, the resulting U16String will also be valid UTF-16.

Examples

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

assert_eq!(wstr.to_string().unwrap(), s);

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

Encodes a U16String copy from an OsStr.

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

Examples

use widestring::U16String;
let s = "MyString";
// Create a wide string from the string
let wstr = U16String::from_os_str(s);

assert_eq!(wstr.to_string().unwrap(), s);

pub fn push_str(&mut self, s: impl AsRef<str>)

Extends the string with the given &str.

No checks are performed on the strings. It is possible to end up nul values inside the string, and it is up to the caller to determine if that is acceptable.

Examples

use widestring::U16String;
let s = "MyString";
let mut wstr = U16String::from_str(s);
// Push the original to the end, repeating the string twice.
wstr.push_str(s);

assert_eq!(wstr.to_string().unwrap(), "MyStringMyString");

pub fn push_os_str(&mut self, s: impl AsRef<OsStr>)

Extends the string with the given &OsStr.

No checks are performed on the strings. It is possible to end up nul values inside the string, and it is up to the caller to determine if that is acceptable.

Examples

use widestring::U16String;
let s = "MyString";
let mut wstr = U16String::from_str(s);
// Push the original to the end, repeating the string twice.
wstr.push_os_str(s);

assert_eq!(wstr.to_string().unwrap(), "MyStringMyString");

impl UString<u32>

pub fn from_chars(raw: Vec<char>) -> Self

Constructs a U32String from a vector of UTF-32 data.

No checks are made on the contents of the vector.

Examples

use widestring::U32String;
let v: Vec<char> = "Test".chars().collect();
// Create a wide string from the vector
let wstr = U32String::from_chars(v);

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

Encodes a U32String copy from a str.

This makes a wide string copy of the str. Since str will always be valid UTF-8, the resulting U32String will also be valid UTF-32.

Examples

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

assert_eq!(wstr.to_string().unwrap(), s);

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

Encodes a U32String copy from an OsStr.

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

Examples

use widestring::U32String;
let s = "MyString";
// Create a wide string from the string
let wstr = U32String::from_os_str(s);

assert_eq!(wstr.to_string().unwrap(), s);

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

Constructs a U32String 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

Panics if len is greater than 0 but p is a null pointer.

pub fn push_str(&mut self, s: impl AsRef<str>)

Extends the string with the given &str.

No checks are performed on the strings. It is possible to end up nul values inside the string, and it is up to the caller to determine if that is acceptable.

Examples

use widestring::U32String;
let s = "MyString";
let mut wstr = U32String::from_str(s);
// Push the original to the end, repeating the string twice.
wstr.push_str(s);

assert_eq!(wstr.to_string().unwrap(), "MyStringMyString");

pub fn push_os_str(&mut self, s: impl AsRef<OsStr>)

Extends the string with the given &OsStr.

No checks are performed on the strings. It is possible to end up nul values inside the string, and it is up to the caller to determine if that is acceptable.

Examples

use widestring::U32String;
let s = "MyString";
let mut wstr = U32String::from_str(s);
// Push the original to the end, repeating the string twice.
wstr.push_os_str(s);

assert_eq!(wstr.to_string().unwrap(), "MyStringMyString");

Methods from Deref<Target = UStr<C>>

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 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);

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: UChar> AsRef<[C]> for UString<C>

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

Performs the conversion.

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

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

Performs the conversion.

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

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

Immutably borrows from an owned value.

impl<C: Clone + UChar> Clone for UString<C>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl<C: Default + UChar> Default for UString<C>

fn default() -> UString<C>

Returns the "default value" for a type.

impl<C: UChar> Deref for UString<C>

type Target = UStr<C>

The resulting type after dereferencing.

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

Dereferences the value.

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

impl<'_> From<&'_ String> for UString<u16>

fn from(s: &String) -> Self

Performs the conversion.

impl<'_> From<&'_ String> for UString<u32>

fn from(s: &String) -> Self

Performs the conversion.

impl<'_> From<&'_ str> for UString<u16>

fn from(s: &str) -> Self

Performs the conversion.

impl<'_> From<&'_ str> for UString<u32>

fn from(s: &str) -> Self

Performs the conversion.

impl<'a, C: UChar, T: ?Sized + AsRef<UStr<C>>> From<&'a T> for UString<C>

fn from(s: &'a T) -> Self

Performs the conversion.

impl<C: UChar> From<Box<UStr<C>>> for UString<C>

fn from(boxed: Box<UStr<C>>) -> Self

Performs the conversion.

impl From<OsString> for UString<u16>

fn from(s: OsString) -> Self

Performs the conversion.

impl From<OsString> for UString<u32>

fn from(s: OsString) -> Self

Performs the conversion.

impl From<String> for UString<u16>

fn from(s: String) -> Self

Performs the conversion.

impl From<String> for UString<u32>

fn from(s: String) -> Self

Performs the conversion.

impl<C: UChar> From<UCString<C>> for UString<C>

fn from(s: UCString<C>) -> Self

Performs the conversion.

impl<C: UChar> From<UString<C>> for Box<UStr<C>>

fn from(s: UString<C>) -> Self

Performs the conversion.

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

fn from(s: UString<u16>) -> Self

Performs the conversion.

impl From<UString<u16>> for OsString

fn from(s: UString<u16>) -> Self

Performs the conversion.

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

fn from(s: UString<u32>) -> Self

Performs the conversion.

impl From<UString<u32>> for OsString

fn from(s: UString<u32>) -> Self

Performs the conversion.

impl FromStr for UString<u16>

type Err = Infallible

The associated error which can be returned from parsing.

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

Parses a string s to return a value of this type.

impl FromStr for UString<u32>

type Err = Infallible

The associated error which can be returned from parsing.

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

Parses a string s to return a value of this type.

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

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<C: UChar> Index<RangeFull> for UString<C>

type Output = UStr<C>

The returned type after indexing.

fn index(&self, _index: RangeFull) -> &UStr<C>

Performs the indexing (container[index]) operation.

impl Into<UString<u16>> for Vec<u16>

fn into(self) -> UString<u16>

Performs the conversion.

impl Into<UString<u32>> for Vec<u32>

fn into(self) -> UString<u32>

Performs the conversion.

impl Into<UString<u32>> for Vec<char>

fn into(self) -> UString<u32>

Performs the conversion.

impl<C: UChar> Into<Vec<C>> for UString<C>

fn into(self) -> Vec<C>

Performs the conversion.

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

fn cmp(&self, other: &UString<C>) -> Ordering

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

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

Restrict a value to a certain interval.

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 ==.

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

This method tests for !=.

impl<'a, C: UChar> PartialEq<Cow<'a, UStr<C>>> for UString<C>

fn eq(&self, other: &Cow<'a, UStr<C>>) -> 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<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 ==.

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

This method tests for !=.

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

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

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

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

#[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<'a, C: UChar> PartialOrd<Cow<'a, UStr<C>>> for UString<C>

fn partial_cmp(&self, other: &Cow<'a, UStr<C>>) -> 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<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.

#[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<C: PartialOrd + UChar> PartialOrd<UString<C>> for UString<C>

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

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

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

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

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

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

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

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

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

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

impl<C: UChar> StructuralEq for UString<C>

impl<C: UChar> StructuralPartialEq for UString<C>