Struct widestring::WideStr

pub struct WideStr { /* fields omitted */ }

Wide string reference for WideString.

WideStr is 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.

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

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

Methods

impl WideStr

fn new<'a, S: AsRef<WideStr> + ?Sized>(s: &'a S) -> &'a WideStr

Coerces a value into a WideStr.

unsafe fn from_ptr<'a>(p: *const u16, len: usize) -> &'a WideStr

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

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.

fn from_slice<'a>(slice: &'a [u16]) -> &'a WideStr

Constructs a WideStr from a slice of u16 partial code points.

No checks are performed on the slice.

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 WideStr

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

Formats the value using the given formatter.

impl PartialEq for WideStr

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

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

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

This method tests for !=.

impl Eq for WideStr

impl PartialOrd for WideStr

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

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

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

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

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

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

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

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

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

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

impl Ord for WideStr

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

This method returns an Ordering between self and other.

impl Hash for WideStr

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 ToOwned for WideStr

type Owned = WideString

fn to_owned(&self) -> WideString

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 AsRef<WideStr> for WideStr

fn as_ref(&self) -> &WideStr

Performs the conversion.

impl AsRef<[u16]> for WideStr

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

Performs the conversion.