Struct widestring::WideString

pub struct WideString { /* fields omitted */ }

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

WideString is not aware of nul values. Strings may or may not be nul-terminated, and may contain invalid and ill-formed UTF-16 data. These strings are intended to be used with windows 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.

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

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

Examples

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

use widestring::WideString;
let v = vec![84u16, 104u16, 101u16]; // 'T' 'h' 'e'
// Create a wide string from the vector
let wstr = WideString::from_vec(v);
// Convert to a rust string!
let rust_str = wstr.to_string_lossy();
assert_eq!(rust_str, "The");

Methods

impl WideString

fn new() -> WideString

Constructs a new empty WideString.

fn from_vec<T: Into<Vec<u16>>>(raw: T) -> WideString

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

No checks are made on the contents of the vector.

Examples

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

fn from_str<S: AsRef<OsStr> + ?Sized>(s: &S) -> WideString

Encodes a WideString copy from an OsStr.

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

Examples

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

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

unsafe fn from_ptr(p: *const u16, len: usize) -> WideString

Constructs a WideString from a u16 pointer and a length.

The len argument is the number of u16 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.

fn with_capacity(capacity: usize) -> WideString

Creates a WideString 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.

fn capacity(&self) -> usize

Returns the capacity this WideString can hold without reallocating.

fn clear(&mut self)

Truncate the WideString to zero length.

fn reserve(&mut self, additional: usize)

Reserves the capacity for at least additiona more capacity to be inserted in the given WideString.

More space may be reserved to avoid frequent allocations.

fn reserve_exact(&mut self, additional: usize)

Reserves the minimum capacity for exactly additiona more capacity to be inserted in the given WideString. 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.

fn as_wide_str(&self) -> &WideStr

Converts to a WideStr reference.

fn into_vec(self) -> Vec<u16>

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

fn push<T: AsRef<WideStr>>(&mut self, s: T)

Extends the wide string with the given &WideStr.

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::WideString;
let s = "MyString";
let mut wstr = WideString::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");

fn push_slice<T: AsRef<[u16]>>(&mut self, s: T)

Extends the wide string with the given &[u16] 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::WideString;
let s = "MyString";
let mut wstr = WideString::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");

fn push_str<T: AsRef<OsStr>>(&mut self, s: T)

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::WideString;
let s = "MyString";
let mut wstr = WideString::from_str(s);
// Push the original to the end, repeating the string twice.
wstr.push_str(s);

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

Methods from Deref<Target = WideStr>

fn to_os_string(&self) -> OsString

Decodes a wide string to an owned OsString.

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

Examples

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

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

fn to_wide_string(&self) -> WideString

Copies the wide string to a new owned WideString.

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::WideString;
let s = "MyString";
// Create a wide string from the string
let wstr = WideString::from_str(s);
// Create a regular string from the wide string
let s2 = wstr.to_string().unwrap();

assert_eq!(s2, s);

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::WideString;
let s = "MyString";
// Create a wide string from the string
let wstr = WideString::from_str(s);
// Create a regular string from the wide string
let lossy = wstr.to_string_lossy();

assert_eq!(lossy, s);

fn as_slice(&self) -> &[u16]

Converts to a slice of the wide string.

fn as_ptr(&self) -> *const u16

Returns a raw pointer to the wide string.

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

fn len(&self) -> usize

Returns the length of the wide string as number of UTF-16 partial code units (not code points and not number of bytes).

fn is_empty(&self) -> bool

Returns whether this wide string contains no data.

Trait Implementations

impl Debug for WideString

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

Formats the value using the given formatter.

impl Default for WideString

fn default() -> WideString

Returns the "default value" for a type.

impl Clone for WideString

fn clone(&self) -> WideString

Returns a copy of the value.

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

Performs copy-assignment from source.

impl PartialEq for WideString

fn eq(&self, __arg_0: &WideString) -> bool

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

fn ne(&self, __arg_0: &WideString) -> bool

This method tests for !=.

impl Eq for WideString

impl PartialOrd for WideString

fn partial_cmp(&self, __arg_0: &WideString) -> Option<Ordering>

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

fn lt(&self, __arg_0: &WideString) -> bool

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

fn le(&self, __arg_0: &WideString) -> bool

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

fn gt(&self, __arg_0: &WideString) -> bool

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

fn ge(&self, __arg_0: &WideString) -> bool

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

impl Ord for WideString

fn cmp(&self, __arg_0: &WideString) -> Ordering

This method returns an Ordering between self and other.

impl Hash for WideString

fn hash<__H: Hasher>(&self, __arg_0: &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 Into<Vec<u16>> for WideString

fn into(self) -> Vec<u16>

Performs the conversion.

impl From<String> for WideString

fn from(s: String) -> WideString

Performs the conversion.

impl From<OsString> for WideString

fn from(s: OsString) -> WideString

Performs the conversion.

impl<'a, T: ?Sized + AsRef<WideStr>> From<&'a T> for WideString

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

Performs the conversion.

impl Index<RangeFull> for WideString

type Output = WideStr

The returned type after indexing

fn index(&self, _index: RangeFull) -> &WideStr

The method for the indexing (container[index]) operation

impl Deref for WideString

type Target = WideStr

The resulting type after dereferencing

fn deref(&self) -> &WideStr

The method called to dereference a value

impl PartialEq<WideStr> for WideString

fn eq(&self, other: &WideStr) -> 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 PartialOrd<WideStr> for WideString

fn partial_cmp(&self, other: &WideStr) -> 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> PartialEq<&'a WideStr> for WideString

fn eq(&self, other: &&'a WideStr) -> 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> PartialOrd<&'a WideStr> for WideString

fn partial_cmp(&self, other: &&'a WideStr) -> 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> PartialEq<Cow<'a, WideStr>> for WideString

fn eq(&self, other: &Cow<'a, WideStr>) -> 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> PartialOrd<Cow<'a, WideStr>> for WideString

fn partial_cmp(&self, other: &Cow<'a, WideStr>) -> 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 Borrow<WideStr> for WideString

fn borrow(&self) -> &WideStr

Immutably borrows from an owned value.

impl AsRef<WideStr> for WideString

fn as_ref(&self) -> &WideStr

Performs the conversion.

impl AsRef<[u16]> for WideString

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

Performs the conversion.

impl From<WideCString> for WideString

fn from(s: WideCString) -> WideString

Performs the conversion.