Struct UString

pub struct UString<C: UChar> { /* private fields */ }

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.

Trait Implementations

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

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

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

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

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

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

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 duplicate 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 From<&String> for UString<u16>

fn from(s: &String) -> Self

Converts to this type from the input type.

impl From<&String> for UString<u32>

fn from(s: &String) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl From<&str> for UString<u16>

fn from(s: &str) -> Self

Converts to this type from the input type.

impl From<&str> for UString<u32>

fn from(s: &str) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl From<OsString> for UString<u16>

fn from(s: OsString) -> Self

Converts to this type from the input type.

impl From<OsString> for UString<u32>

fn from(s: OsString) -> Self

Converts to this type from the input type.

impl From<String> for UString<u16>

fn from(s: String) -> Self

Converts to this type from the input type.

impl From<String> for UString<u32>

fn from(s: String) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl From<UString<u16>> for OsString

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl From<UString<u32>> for OsString

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

Converts to this type from the input type.

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, Self: Sized,

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>

Converts this type into the (usually inferred) input type.

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

fn into(self) -> UString<u32>

Converts this type into the (usually inferred) input type.

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

fn into(self) -> UString<u32>

Converts this type into the (usually inferred) input type.

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

fn into(self) -> Vec<C>

Converts this type into the (usually inferred) input type.

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

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

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

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

fn eq(&self, other: &Cow<'a, UStr<C>>) -> 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<C: UChar> PartialEq<UStr<C>> for UString<C>

fn eq(&self, other: &UStr<C>) -> 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<C: PartialEq + UChar> PartialEq for UString<C>

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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.

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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.

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<C: PartialOrd + UChar> PartialOrd 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: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

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

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