Struct WString

Source

pub struct WString { /* private fields */ }

Available on crate feature kernel only.

Expand description

Stores a [u16] buffer for a null-terminated Unicode UTF-16 wide string natively used by Windows.

Uses Short String Optimization technique for faster performance.

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

Implementations§

Source §

impl WString

Source

pub const SSO_LEN: usize = 20usize

Stack size for internal Short String Optimization.

Source

pub fn from_opt_str(s: Option<impl AsRef<str>>) -> Self

Stores an UTF-16 null-terminated string from an optional &str.

If s is None or the string is empty, no allocation is made.

Source

pub fn from_str(s: impl AsRef<str>) -> Self

Stores an UTF-16 null-terminated string from a &str.

If the string is empty, no allocation is made.

Source

pub fn from_str_force_heap(s: impl AsRef<str>) -> Self

Stores an UTF-16 null-terminated string from a &str, bypassing Short String Optimization – that is, forcing the internal allocation on the heap. This should be rarely needed.

If the string is empty, no allocation is made.

Source

pub fn from_str_vec(v: &[impl AsRef<str>]) -> Self

Stores a series of UTF-16 null-terminated strings. The buffer will end with two terminating nulls – that means further retrieval operations will “see” only the first string.

This method can be used as an escape hatch to interoperate with other libraries.

Source

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

Stores an UTF-16 null-terminated string by copying from a buffer, specifying the number of chars to be copied.

The src buffer doesn’t need to be null-terminated.

Source

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

Stores an UTF-16 null-terminated string by copying from a null-terminated buffer. The string length is retrieved with lstrlen.

§Safety

Be sure the string is null-terminated, otherwise lstrlen will get lost, possibly reading an invalid memory location.

Source

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

Stores an UTF-16 null-terminated string by copying from a slice.

The src slice doesn’t need to be null-terminated.

Source

pub const fn new() -> Self

Creates a new, empty WString.

Source

pub fn new_alloc_buf(sz: usize) -> Self

Allocates an UTF-16 buffer with an specific length. All elements will be set to zero.

Source

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

Returns a mutable LPWSTR 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 was not allocated.

§Safety

Be sure to alloc enough room, otherwise a buffer overrun may occur.

Source

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

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

Source

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

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

If the buffer was not allocated, returns a null pointer.

Source

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

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

Source

pub const fn buf_len(&self) -> usize

Returns the size of the allocated internal buffer, in u16 wide chars. Note that the terminating null, if existing, is also counted.

If the buffer was not allocated yet, returns zero.

Source

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.

If dest has 1 element, it will receive only the terminating null.

Source

pub fn fill_with_zero(&mut self)

Fills the entire buffer with zeros.

Source

pub const fn is_allocated(&self) -> bool

Returns true if the internal buffer has been allocated.

Source

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

Converts into String by calling String::from_utf16. An uncallocated 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.

Source

pub fn str_len(&self) -> usize

Wrapper to lstrlen.

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

Source

pub fn make_lowercase(&mut self)

Converts the string to lower case, in-place. Wrapper to CharLower.

Source

pub fn make_uppercase(&mut self)

Converts the string to upper case, in-place. Wrapper to CharUpper.

Source

pub fn parse(data: &[u8]) -> SysResult<Self>

Guesses the encoding with Encoding::guess and parses the data as a string.

If you’re sure the data has UTF-8 encoding, you can also use the built-in String::from_utf8.

To serialize the string back into UTF-8 bytes, use the built-in String::into_bytes.

§Examples

Usually the fastest way to read the text from a file is by mapping its contents in memory with FileMapped, then parsing:

use winsafe::{self as w, prelude::*};

let file_in = w::FileMapped::open(
    "C:\\Temp\\foo.txt",
    w::FileAccess::ExistingReadOnly,
)?;
let wstr = w::WString::parse(file_in.as_slice())?;
let str_contents = wstr.to_string();