Struct widestring::WideCString [] [src]

pub struct WideCString {
    // some fields omitted
}

An owned, mutable C-style "wide" string for windows FFI that is nul-aware and nul-terminated.

WideCString is aware of nul values. Unless unchecked conversions are used, all WideCString 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.

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

Examples

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

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

Methods

impl WideCString
[src]

fn new() -> WideCString

Constructs a new empty WideCString.

fn from_vec<T: Into<Vec<u16>>>(v: T) -> Result<WideCStringNulError>

Constructs a WideCString from a container of UTF-16 data.

This method will consume the provided data and use the underlying elements to construct a new string. The data will be scanned for invalid nul values.

Failures

This function will return an error if the data contains a nul value. The returned error will contain the Vec<u16> as well as the position of the nul value.

Examples

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

The following example demonstrates errors from nul values in a vector.

use widestring::WideCString;
let v = vec![84u16, 0u16, 104u16, 101u16]; // 'T' NUL 'h' 'e'
// Create a wide string from the vector
let res = WideCString::from_vec(v);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 1);

fn from_vec_with_nul<T: Into<Vec<u16>>>(v: T) -> Result<WideCStringMissingNulError>

Constructs a WideCString from a nul-terminated container of UTF-16 data.

This method will consume the provided data and use the underlying elements to construct a new string. The string will be truncated at the first nul value in the string.

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec<u16>.

Examples

use widestring::WideCString;
let v = vec![84u16, 104u16, 101u16, 0u16]; // 'T' 'h' 'e' NUL
// Create a wide string from the vector
let wcstr = WideCString::from_vec_with_nul(v).unwrap();

The following example demonstrates errors from missing nul values in a vector.

use widestring::WideCString;
let v = vec![84u16, 104u16, 101u16]; // 'T' 'h' 'e'
// Create a wide string from the vector
let res = WideCString::from_vec_with_nul(v);
assert!(res.is_err());

unsafe fn from_vec_unchecked<T: Into<Vec<u16>>>(v: T) -> WideCString

Creates a WideCString from a vector without checking for interior nul values.

A terminating nul value will be appended if the vector does not already have a terminating nul.

Safety

This method is equivalent to from_vec except that no runtime assertion is made that v contains no nul values. Providing a vector with non-terminating nul values will result in an invalid WideCString.

unsafe fn from_vec_with_nul_unchecked<T: Into<Vec<u16>>>(v: T) -> WideCString

Creates a WideCString from a vector that should have a nul terminator, without checking for any nul values.

Safety

This method is equivalent to from_vec_with_nul except that no runtime assertion is made that v contains no nul values. Providing a vector without interior nul values or without a terminating nul value will result in an invalid WideCString.

fn from_str<T: AsRef<OsStr>>(s: T) -> Result<WideCStringNulError>

Constructs a WideCString from anything that can be converted to an OsStr.

The string will be scanned for invalid nul values.

Failures

This function will return an error if the data contains a nul value. The returned error will contain a Vec<u16> as well as the position of the nul value.

Examples

use widestring::WideCString;
let s = "MyString";
// Create a wide string from the string
let wcstr = WideCString::from_str(s).unwrap();

The following example demonstrates errors from nul values in a vector.

use widestring::WideCString;
let s = "My\u{0}String";
// Create a wide string from the string
let res = WideCString::from_str(s);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 2);

fn from_str_with_nul<T: AsRef<OsStr>>(s: T) -> Result<WideCStringMissingNulError>

Constructs a WideCString from anything that can be converted to an OsStr with a nul terminator.

The string will be truncated at the first nul value in the string.

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec<u16>.

Examples

use widestring::WideCString;
let s = "My\u{0}String";
// Create a wide string from the string
let wcstr = WideCString::from_str_with_nul(s).unwrap();
assert_eq!(wcstr.to_string_lossy(), "My");

The following example demonstrates errors from missing nul values in a vector.

use widestring::WideCString;
let s = "MyString";
// Create a wide string from the string
let res = WideCString::from_str_with_nul(s);
assert!(res.is_err());

fn from_wide_str<T: AsRef<WideStr>>(s: T) -> Result<WideCStringNulError>

Constructs a WideCString from anything that can be converted to a WideStr.

The string will be scanned for invalid nul values.

Failures

This function will return an error if the data contains a nul value. The returned error will contain a Vec<u16> as well as the position of the nul value.

fn from_wide_str_with_nul<T: AsRef<WideStr>>(s: T) -> Result<WideCStringMissingNulError>

Constructs a WideCString from anything that can be converted to a WideStr with a nul terminator.

The string will be truncated at the first nul value in the string.

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec<u16>.

unsafe fn from_ptr_str(p: *const u16) -> WideCString

Constructs a new WideCString copied 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(p: *const u16, len: usize) -> Result<WideCStringNulError>

Constructs a new WideCString copied from a u16 pointer and a length.

The len argument is the number of u16 elements, not the number of bytes.

The string will be scanned for invalid nul values.

Failures

This function will return an error if the data contains a nul value. The returned error will contain a Vec<u16> as well as the position of the nul value.

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.

unsafe fn from_ptr_with_nul(p: *const u16, len: usize) -> Result<WideCStringMissingNulError>

Constructs a new WideString copied from a u16 pointer and a length.

The len argument is the number of u16 elements, not the number of bytes.

The string will be truncated at the first nul value in the string.

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec<u16>.

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 as_wide_c_str(&self) -> &WideCStr

Converts to a WideCStr reference.

fn into_vec(self) -> Vec<u16>

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

The resulting vector will not contain a nul-terminator, and will contain no other nul values.

fn into_vec_with_nul(self) -> Vec<u16>

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

The resulting vector will contain a nul-terminator and no interior nul values.

fn into_raw(self) -> *mut u16

Transfers ownership of the wide string to a C caller.

Safety

The pointer must be returned to Rust and reconstituted using from_raw to be properly deallocated. Specifically, one should not use the standard C free function to deallocate this string.

Failure to call from_raw will lead to a memory leak.

unsafe fn from_raw(p: *mut u16) -> WideCString

Retakes ownership of a CString that was transferred to C.

Safety

This should only ever be called with a pointer that was earlier obtained by calling into_raw on a WideCString. Additionally, the length of the string will be recalculated from the pointer.

Methods from Deref<Target=WideCStr>

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 WideCString
[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 WideCString
[src]

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

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

impl PartialOrd for WideCString
[src]

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

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

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

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

fn le(&self, __arg_0: &WideCString) -> 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: &WideCString) -> bool

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

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

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

impl Eq for WideCString
[src]

impl PartialEq for WideCString
[src]

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

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

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

This method tests for !=.

impl Clone for WideCString
[src]

fn clone(&self) -> WideCString

Returns a copy of the value. Read more

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

Performs copy-assignment from source. Read more

impl Debug for WideCString
[src]

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

Formats the value using the given formatter.

impl Into<Vec<u16>> for WideCString
[src]

fn into(self) -> Vec<u16>

Performs the conversion.

impl<'a, T: ?Sized + AsRef<WideCStr>> From<&'a T> for WideCString
[src]

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

Performs the conversion.

impl Index<RangeFull> for WideCString
[src]

type Output = WideCStr

The returned type after indexing

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

The method for the indexing (Foo[Bar]) operation

impl Deref for WideCString
[src]

type Target = WideCStr

The resulting type after dereferencing

fn deref(&self) -> &WideCStr

The method called to dereference a value

impl Default for WideCString
[src]

fn default() -> WideCString

Returns the "default value" for a type. Read more

impl Borrow<WideCStr> for WideCString
[src]

fn borrow(&self) -> &WideCStr

Immutably borrows from an owned value. Read more

impl AsRef<WideCStr> for WideCString
[src]

fn as_ref(&self) -> &WideCStr

Performs the conversion.

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

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

Performs the conversion.