Struct winsafe::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 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, no allocation is made.

source

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

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

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 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();

Trait Implementations§

source§

impl Clone for WString

source§

fn clone(&self) -> WString

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for WString

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for WString

source§

fn default() -> WString

Returns the “default value” for a type. Read more
source§

impl Display for WString

source§

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

Formats the value using the given formatter. Read more
source§

impl From<BSTR> for WString

Available on crate feature oleaut only.
source§

fn from(v: BSTR) -> WString

Converts to this type from the input type.
source§

impl From<SE_PRIV> for WString

source§

fn from(v: SE_PRIV) -> Self

Converts to this type from the input type.
source§

impl Ord for WString

source§

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other. Read more
1.21.0 · source§

fn max(self, other: Self) -> Self
where Self: Sized,

Compares and returns the maximum of two values. Read more
1.21.0 · source§

fn min(self, other: Self) -> Self
where Self: Sized,

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized + PartialOrd,

Restrict a value to a certain interval. Read more
source§

impl PartialEq for WString

source§

fn eq(&self, other: &Self) -> bool

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl PartialOrd for WString

source§

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

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

fn lt(&self, other: &Rhs) -> bool

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

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

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

fn ge(&self, other: &Rhs) -> bool

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

impl Eq for WString

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

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

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.