Struct winsafe::WString

pub struct WString { /* fields omitted */ }

Stores a Vec<u16> buffer for a null-terminated Unicode UTF-16 wide string natively used by Windows.

Performs UTF-8 conversions and can be used as a buffer to low-level Win32 functions.

This is struct is mostly used internally by the library, as a bridge between Windows and Rust strings.

Implementations

impl WString

pub fn from_opt_str(s: Option<&str>) -> WString

Creates and stores a new UTF-16 string from an optional &str.

The string will be stored with a terminating null.

If s is None, the internal buffer is not allocated.

pub fn from_str(s: &str) -> WString

Creates and stores a new UTF-16 string from an ordinary &str.

The string will be stored with a terminating null.

pub fn from_str_vec<S: AsRef<str>>(v: &[S]) -> WString

Creates and stores a new UTF-16 string from a Vec of ordinary strings. This new string will be stored as sequential null-separated strings, terminated with two nulls. That means that further retrieval operations will “see” only the first string.

This method is intended to pass multi-strings to native APIs, not to retrieve them.

pub fn from_wchars_count(src: *const u16, num_chars: usize) -> WString

Creates a new UTF-16 string by copying from a buffer, specifying the number of existing chars, not counting a terminating null.

The string will be stored with a terminating null.

pub fn from_wchars_nullt(src: *const u16) -> WString

Creates a new UTF-16 string by copying from a null-terminated buffer.

The string will be stored with a terminating null.

pub fn from_wchars_slice(src: &[u16]) -> WString

Creates a new UTF-16 string by copying from a slice.

The string will be stored with a terminating null.

pub fn new_alloc_buffer(num_chars: usize) -> WString

Creates a new UTF-16 buffer allocated with an specific length. All UTF-16 chars will be set to zero.

pub unsafe fn as_mut_ptr(&mut self) -> *mut u16

Returns a LPWSTR mut pointer to the internal UTF-16 string buffer, to be passed to native Win32 functions. This is useful to receive strings.

Panics

Panics if the buffer wasn’t previously allocated. Be sure to alloc enough room, otherwise a buffer overrun may occur.

pub unsafe fn as_ptr(&self) -> *const u16

Returns a LPCWSTR const pointer to the internal UTF-16 string buffer, to be passed to native Win32 functions.

Note: Returns a null pointer if the buffer wasn’t previously allocated. Make sure the WString object outlives the function call, otherwise it will point to an invalid memory location.

pub fn as_mut_slice(&mut self) -> &mut [u16]

Returns a slice to the internal u16 buffer. This is useful to receive strings.

Panics

Panics if the buffer wasn’t previously allocated. Be sure to alloc enough room, otherwise a buffer overrun may occur.

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

Returns a slice to the internal UTF-16 string buffer.

Panics

Panics if the buffer wasn’t previously allocated. Make sure the WString object outlives the function call, otherwise it will point to an invalid memory location.

pub fn buffer_size(&self) -> usize

Returns the size of the allocated internal buffer.

If the buffer was not allocated yet, returns zero.

pub fn copy_to_slice(&self, dest: &mut [u16])

Copies the content into an external buffer. A terminating null will be appended.

If dest is smaller, the string will be truncated.

Panics

Panics if dest has zero length. If length is 1, the buffer will receive a single null char.

pub fn fill_with_zero(&mut self)

Fills the entire buffer with zero values. The buffer size is not changed.

pub fn is_empty(&self) -> bool

Tells whether the internal buffer is storing a null string pointer, or if it’s holding a string with a length of zero.

pub fn is_null(&self) -> bool

Tells whether the internal buffer is storing a null string pointer.

pub fn len(&self) -> usize

Wrapper to lstrlen.

Returns the number of u16 characters stored in the internal buffer, not counting the terminating null.

pub fn realloc_buffer(&mut self, new_size: usize)

Resizes the internal buffer, to be used as a buffer for native Win32 functions. All UTF-16 chars will be set to zero.

If the new size is zero, the internal buffer is deallocated.

Note: The internal memory can move after a realloc, so if you’re using a pointer or reference to the internal buffer, they may then point to an invalid memory location. After a realloc, the following methods must be called again:

• as_mut_ptr;
• as_ptr;
• as_mut_slice;
• as_slice.

pub fn to_string(&self) -> String

Converts into String. An internal null pointer will simply be converted into an empty string.

Panics

Panics if any invalid character is found.

If you’re parsing raw data which may contain errors, prefer using to_string_checked instead.

pub fn to_string_checked(&self) -> Result<String, FromUtf16Error>

Converts into String by calling String::from_utf16. An internal null pointer will simply be converted into an empty string.

This method is useful if you’re parsing raw data which may contain invalid characters. If you’re dealing with a string known to be valid, to_string is more practical.

pub fn guess_encoding(data: &[u8]) -> (Encoding, usize)

Guesses the Encoding of the given data, also returning the size of its BOM, if any.

pub fn parse_str(data: &[u8]) -> WinResult<WString>

Guesses the encoding with WString::guess_encoding and parses the data as string.

Trait Implementations

impl Clone for WString

fn clone(&self) -> WString

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for WString

fn default() -> Self

Returns the “default value” for a type.

impl Display for WString

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.