Struct NtUnicodeString

pub struct NtUnicodeString { /* private fields */ }

Available on crate feature alloc only.

An allocated, owned, and growable variant of UNICODE_STRING (equivalent of String).

See the module-level documentation for more details.

Implementations

impl NtUnicodeString

pub fn new() -> Self

Creates an empty NtUnicodeString.

This operation won’t allocate any buffer. Therefore, length and capacity will both be zero.

pub fn as_unicode_str_mut(&mut self) -> &mut NtUnicodeStrMut<'static>

Returns a mutable NtUnicodeStrMut reference for this string.

pub fn try_from_u16(buffer: &[u16]) -> Result<Self>

Creates an NtUnicodeString from an existing u16 string buffer without a terminating NUL character.

The string is expected to consist of valid UTF-16 characters.

The given buffer becomes the internal buffer of the NtUnicodeString and therefore won’t be NUL-terminated. See the module-level documentation for the implications of that.

This function has O(1) complexity.

If you have a NUL-terminated buffer, either use try_from_u16_until_nul or convert from a U16CStr using the corresponding TryFrom implementation.

pub fn try_from_u16_until_nul(buffer: &[u16]) -> Result<Self>

Creates an NtUnicodeString from an existing u16 string buffer that contains at least one NUL character.

The string is expected to consist of valid UTF-16 characters.

The string will be terminated at the NUL character. An NtStringError::NulNotFound error is returned if no NUL character could be found. As a consequence, this function has O(n) complexity.

The resulting internal buffer of NtUnicodeString will be NUL-terminated. See the module-level documentation for the implications of that.

Use try_from_u16 if you have a buffer that is not NUL-terminated. You can also convert from a NUL-terminated U16CStr in O(1) via the corresponding TryFrom implementation.

pub fn try_push(&mut self, c: char) -> Result<()>

Appends the given char to the end of this string.

Returns an NtStringError::BufferSizeExceedsU16 error if the resulting string would exceed 65532 bytes. This is due to the fact that a UNICODE_STRING internally uses a 16-bit field to store the length. Additionally, this function allocates one more character for NUL termination of the internal buffer. See the module-level documentation for the implications of that.

Note that every UTF-16 character consumes 2 or 4 bytes.

pub fn try_push_str(&mut self, s: &str) -> Result<()>

Appends the given string slice to the end of this string.

Returns an NtStringError::BufferSizeExceedsU16 error if the resulting string would exceed 65532 bytes. This is due to the fact that a UNICODE_STRING internally uses a 16-bit field to store the length. Additionally, this function allocates one more character for NUL termination of the internal buffer. See the module-level documentation for the implications of that.

Note that every UTF-16 character consumes 2 or 4 bytes.

pub fn try_push_u16(&mut self, buffer: &[u16]) -> Result<()>

Appends the given u16 string buffer (without a terminating NUL character) to the end of this string.

The string is expected to consist of valid UTF-16 characters.

Returns an NtStringError::BufferSizeExceedsU16 error if the resulting string would exceed 65532 bytes. This is due to the fact that a UNICODE_STRING internally uses a 16-bit field to store the length. Additionally, this function allocates one more character for NUL termination of the internal buffer. See the module-level documentation for the implications of that.

Note that every UTF-16 character consumes 2 or 4 bytes.

This function has O(1) complexity.

See try_push_u16_until_nul or try_push_u16cstr if you have a NUL-terminated buffer.

pub fn try_push_u16_until_nul(&mut self, buffer: &[u16]) -> Result<()>

Appends the given u16 string buffer, which contains at least one NUL character, to the end of this string.

The string is expected to consist of valid UTF-16 characters.

The string will be terminated at the NUL character. An NtStringError::NulNotFound error is returned if no NUL character could be found. As a consequence, this function has O(n) complexity.

Returns an NtStringError::BufferSizeExceedsU16 error if the resulting string would exceed 65532 bytes. This is due to the fact that a UNICODE_STRING internally uses a 16-bit field to store the length. Additionally, this function allocates one more character for NUL termination of the internal buffer. See the module-level documentation for the implications of that.

Note that every UTF-16 character consumes 2 or 4 bytes.

Use try_push_u16 if you have a buffer that is not NUL-terminated. You can also push a NUL-terminated U16CStr in O(1) via try_push_u16cstr.

pub fn try_push_u16cstr(&mut self, u16cstr: &U16CStr) -> Result<()>

Appends the given U16CStr to the end of this string.

Returns an NtStringError::BufferSizeExceedsU16 error if the resulting string would exceed 65532 bytes. This is due to the fact that a UNICODE_STRING internally uses a 16-bit field to store the length. Additionally, this function allocates one more character for NUL termination of the internal buffer. See the module-level documentation for the implications of that.

Note that every UTF-16 character consumes 2 or 4 bytes.

This function has O(1) complexity.

pub fn try_push_u16str(&mut self, u16str: &U16Str) -> Result<()>

Appends the given U16Str to the end of this string.

Returns an NtStringError::BufferSizeExceedsU16 error if the resulting string would exceed 65532 bytes. This is due to the fact that a UNICODE_STRING internally uses a 16-bit field to store the length. Additionally, this function allocates one more character for NUL termination of the internal buffer. See the module-level documentation for the implications of that.

Note that every UTF-16 character consumes 2 or 4 bytes.

This function has O(1) complexity.

pub fn try_reserve(&mut self, additional: u16) -> Result<()>

Reserves capacity for additional bytes more than the current length.

Returns an NtStringError::BufferSizeExceedsU16 error if the resulting capacity would exceed 65535 bytes.

Note that every UTF-16 character consumes 2 or 4 bytes.

pub fn with_capacity(capacity: u16) -> Self

Creates an empty NtUnicodeString with at least the specified capacity.

This will preallocate a buffer with the given capacity. If the given capacity is 0, no allocation will occur, and this method is identical to the new method.

Methods from Deref<Target = NtUnicodeStrMut<'static>>

pub fn as_mut_ptr(&mut self) -> *mut Self

Returns a *mut NtUnicodeStrMut pointer (mainly for non-Rust interfaces that expect a mutable UNICODE_STRING*).

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

Returns a mutable slice to the raw u16 codepoints of the string.

pub fn as_mut_u16str(&mut self) -> &'a U16Str

Returns a mutable U16Str reference for this string.

The U16Str will only contain the characters and not the NUL terminator.

pub fn as_unicode_str(&'a self) -> &NtUnicodeStr<'a>

Returns an immutable NtUnicodeStr reference for this string.

pub fn clear(&mut self)

Truncates this string, removing all contents.

While this means the string will have a length of zero, it does not touch its capacity.

pub fn pop(&mut self) -> Option<Result<char>>

Removes the last character from the string and returns it.

An NtStringError::UnpairedUtf16Surrogate error is returned if the last character is an unpaired surrogate. In that case, the unpaired surrogate codepoint is removed from the string anyway.

None is returned if this string is empty.

Methods from Deref<Target = NtUnicodeStr<'a>>

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

Returns a *const NtUnicodeStr pointer (mainly for non-Rust interfaces that expect an immutable UNICODE_STRING*).

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

Returns a slice to the raw u16 codepoints of the string.

pub fn as_u16str(&self) -> &'a U16Str

Returns a U16Str reference for this string.

The U16Str will only contain the characters and not the NUL terminator.

pub fn capacity(&self) -> u16

Returns the capacity (also known as “maximum length”) of this string, in bytes.

pub fn chars(&self) -> Chars<'_>

Returns an iterator over the chars of this string.

As the string may contain invalid UTF-16 characters (unpaired surrogates), the returned iterator is an iterator over Result<char>. Unpaired surrogates are returned as an NtStringError::UnpairedUtf16Surrogate error. If you would like a lossy iterator over chars directly, use chars_lossy instead.

pub fn chars_lossy(&self) -> CharsLossy<'_>

Returns an iterator over the chars of this string.

Any invalid UTF-16 characters (unpaired surrogates) are automatically replaced by U+FFFD REPLACEMENT CHARACTER (�). If you would like to treat them differently, use chars instead.

pub fn is_empty(&self) -> bool

Returns true if this string has a length of zero, and false otherwise.

pub fn len(&self) -> u16

Returns the length of this string, in bytes.

Note that a single character may occupy more than one byte. In other words, the returned value might not be what a human considers the length of the string.

Trait Implementations

impl Add<&U16CStr> for NtUnicodeString

type Output = NtUnicodeString

The resulting type after applying the + operator.

fn add(self, rhs: &U16CStr) -> Self::Output

Performs the + operation.

impl Add<&U16Str> for NtUnicodeString

type Output = NtUnicodeString

The resulting type after applying the + operator.

fn add(self, rhs: &U16Str) -> Self::Output

Performs the + operation.

impl Add<&str> for NtUnicodeString

type Output = NtUnicodeString

The resulting type after applying the + operator.

fn add(self, rhs: &str) -> Self::Output

Performs the + operation.

impl AddAssign<&U16CStr> for NtUnicodeString

fn add_assign(&mut self, rhs: &U16CStr)

Performs the += operation.

impl AddAssign<&U16Str> for NtUnicodeString

fn add_assign(&mut self, rhs: &U16Str)

Performs the += operation.

impl AddAssign<&str> for NtUnicodeString

fn add_assign(&mut self, rhs: &str)

Performs the += operation.

impl Clone for NtUnicodeString

fn clone(&self) -> Self

Creates a copy of this NtUnicodeString.

This implementation keeps the original capacity.

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

Performs copy-assignment from source.

impl Debug for NtUnicodeString

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

Formats the value using the given formatter.

impl Default for NtUnicodeString

fn default() -> Self

Returns the “default value” for a type.

impl Deref for NtUnicodeString

type Target = NtUnicodeStrMut<'static>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for NtUnicodeString

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Display for NtUnicodeString

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

Formats the value using the given formatter.

impl Drop for NtUnicodeString

fn drop(&mut self)

Executes the destructor for this type.

impl<'a> From<&NtUnicodeStr<'a>> for NtUnicodeString

fn from(unicode_str: &NtUnicodeStr<'_>) -> Self

Creates an NtUnicodeString from an existing NtUnicodeStr.

This implementation keeps the original capacity.

impl From<char> for NtUnicodeString

fn from(c: char) -> Self

Creates an NtUnicodeString from a single char.

impl Ord for NtUnicodeString

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<'a, 'b> PartialEq<&str> for NtUnicodeString

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<NtUnicodeStr<'a>> for NtUnicodeString

fn eq(&self, other: &NtUnicodeStr<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<NtUnicodeStrMut<'a>> for NtUnicodeString

fn eq(&self, other: &NtUnicodeStrMut<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<NtUnicodeString> for &str

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<NtUnicodeString> for NtUnicodeStr<'a>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<NtUnicodeString> for NtUnicodeStrMut<'a>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<NtUnicodeString> for str

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq<str> for NtUnicodeString

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialEq for NtUnicodeString

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'b> PartialOrd<&str> for NtUnicodeString

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialOrd<NtUnicodeStr<'a>> for NtUnicodeString

fn partial_cmp(&self, other: &NtUnicodeStr<'a>) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialOrd<NtUnicodeStrMut<'a>> for NtUnicodeString

fn partial_cmp(&self, other: &NtUnicodeStrMut<'a>) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialOrd<NtUnicodeString> for &str

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialOrd<NtUnicodeString> for NtUnicodeStr<'a>

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialOrd<NtUnicodeString> for NtUnicodeStrMut<'a>

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialOrd<NtUnicodeString> for str

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialOrd<str> for NtUnicodeString

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'b> PartialOrd for NtUnicodeString

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a> TryExtend<&'a U16CStr> for NtUnicodeString

type Error = NtStringError

The type returned in the event of an error.

fn try_extend<I: IntoIterator<Item = &'a U16CStr>>( &mut self, iter: I, ) -> Result<()>

Tries to extends a collection with the contents of an iterator.

fn try_extend_one(&mut self, item: T) -> Result<(), Self::Error>

Tries to extend a collection with exactly one element.

impl<'a> TryExtend<&'a U16Str> for NtUnicodeString

type Error = NtStringError

The type returned in the event of an error.

fn try_extend<I: IntoIterator<Item = &'a U16Str>>( &mut self, iter: I, ) -> Result<()>

Tries to extends a collection with the contents of an iterator.

fn try_extend_one(&mut self, item: T) -> Result<(), Self::Error>

Tries to extend a collection with exactly one element.

impl<'a> TryExtend<&'a str> for NtUnicodeString

type Error = NtStringError

The type returned in the event of an error.

fn try_extend<I: IntoIterator<Item = &'a str>>(&mut self, iter: I) -> Result<()>

Tries to extends a collection with the contents of an iterator.

fn try_extend_one(&mut self, item: T) -> Result<(), Self::Error>

Tries to extend a collection with exactly one element.

impl TryExtend<char> for NtUnicodeString

type Error = NtStringError

The type returned in the event of an error.

fn try_extend<I: IntoIterator<Item = char>>(&mut self, iter: I) -> Result<()>

Tries to extends a collection with the contents of an iterator.

fn try_extend_one(&mut self, item: char) -> Result<()>

Tries to extend a collection with exactly one element.

impl TryFrom<&String> for NtUnicodeString

fn try_from(s: &String) -> Result<Self>

Converts a String reference into an owned NtUnicodeString.

This allocates a buffer of matching size on the heap and NUL-terminates it internally. See the module-level documentation for the implications of that.

type Error = NtStringError

The type returned in the event of a conversion error.

impl TryFrom<&U16CStr> for NtUnicodeString

fn try_from(value: &U16CStr) -> Result<Self>

Converts a U16CStr reference into an owned NtUnicodeString.

The internal buffer will be NUL-terminated. See the module-level documentation for the implications of that.

type Error = NtStringError

The type returned in the event of a conversion error.

impl TryFrom<&U16Str> for NtUnicodeString

fn try_from(value: &U16Str) -> Result<Self>

Converts a U16Str reference into an owned NtUnicodeString.

The internal buffer will NOT be NUL-terminated. See the module-level documentation for the implications of that.

type Error = NtStringError

The type returned in the event of a conversion error.

impl TryFrom<&str> for NtUnicodeString

fn try_from(s: &str) -> Result<Self>

Converts a string slice into an owned NtUnicodeString.

This allocates a buffer of matching size on the heap and NUL-terminates it internally. See the module-level documentation for the implications of that.

type Error = NtStringError

The type returned in the event of a conversion error.

impl TryFrom<String> for NtUnicodeString

fn try_from(s: String) -> Result<Self>

Converts a String into an owned NtUnicodeString.

This allocates a buffer of matching size on the heap and NUL-terminates it internally. See the module-level documentation for the implications of that.

type Error = NtStringError

The type returned in the event of a conversion error.

impl Eq for NtUnicodeString