Struct widestring::WideCStr [] [src]

pub struct WideCStr {
    // some fields omitted
}

C-style wide string reference for WideCString.

WideCStr is aware of nul values. Unless unchecked conversions are used, all WideCStr strings end with a nul-terminator in the underlying buffer, and contain no internal nul values. The strings may still contain invalid or ill-formed UTF-16 data. These strings are intended to be used with windows FFI functions that may require nul-terminated strings.

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

Methods

impl WideCStr
[src]

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

Coerces a value into a WideCStr.

unsafe fn from_ptr_str<'a>(p: *const u16) -> &'a WideCStr

Constructs a WideStr from a u16 nul-terminated string pointer.

This will scan for nul values beginning with p. The first nul value will be used as the nul terminator for the string, similar to how libc string functions such as strlen work.

Safety

This function is unsafe as there is no guarantee that the given pointer is valid or has a nul terminator, and the function could scan past the underlying buffer.

p must be non-null.

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.

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

Constructs a WideStr from a u16 pointer and a length.

The len argument is the number of u16 elements, not the number of bytes, and does not include the nul terminator of the string. Thus, a len of 0 is valid and means that p is a pointer directly to the nul terminator of the string.

Safety

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

p must be non-null, even for zero len.

The interior values of the pointer are not scanned for nul.

Panics

This function panics if p is null or if a nul value is not found at offset len of p. Only pointers with a nul terminator are valid.

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_with_nul<'a>(slice: &'a [u16]) -> Result<&'a WideCStrMissingNulError>

Constructs a WideCStr from a slice of u16 values that has a nul terminator.

The slice will be scanned for nul values. If a nul value is found, it is treated as the terminator for the string, and the WideCStr slice will be truncated to that nul. If no nul value is found, an error is returned.

fn to_wide_c_string(&self) -> WideCString

Copies the wide string to an new owned WideString.

fn to_os_string(&self) -> OsString

Decodes a wide string to an owned OsString.

This makes a string copy of the WideCStr. Since WideCStr makes no guaruntees that it is valid UTF-16, there is no guaruntee that the resulting OsString will be valid data. The OsString will not have a nul terminator.

Examples

use widestring::WideCString;
use std::ffi::OsString;
let s = "MyString";
// Create a wide string from the string
let wstr = WideCString::from_str(s).unwrap();
// 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.

The WideString will not have a nul terminator.

fn to_string(&self) -> Result<StringFromUtf16Error>

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

assert_eq!(s2, s);

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

Converts to a slice of the wide string.

The slice will not include the nul terminator.

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

converts to a slice of the wide string, including the nul terminator.

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) not including nul terminator.

fn is_empty(&self) -> bool

Returns whether this wide string contains no data (i.e. is only the nul terminator).

Trait Implementations

impl Hash for WideCStr
[src]

fn hash<__H: Hasher>(&self, __arg_0: &mut __H)

Feeds this value into the state given, updating the hasher as necessary.

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher
1.3.0

Feeds a slice of this type into the state provided.

impl Ord for WideCStr
[src]

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

This method returns an Ordering between self and other. Read more

impl PartialOrd for WideCStr
[src]

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

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

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

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

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

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

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

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

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

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

impl Eq for WideCStr
[src]

impl PartialEq for WideCStr
[src]

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

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

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

This method tests for !=.

impl Debug for WideCStr
[src]

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

Formats the value using the given formatter.

impl ToOwned for WideCStr
[src]

type Owned = WideCString

fn to_owned(&self) -> WideCString

Creates owned data from borrowed data, usually by cloning. Read more

impl AsRef<WideCStr> for WideCStr
[src]

fn as_ref(&self) -> &WideCStr

Performs the conversion.

impl AsRef<[u16]> for WideCStr
[src]

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

Performs the conversion.