Struct EfiStr16

pub struct EfiStr16 { /* private fields */ }

String slice based on UCS-2 strings as defined by UEFI.

The EfiStr16 is similar to [CStr] or [OsStr] in the rust standard library, but it implements a string type similar to UCS-2, as defined by the UEFI specification. The type does neither match UTF-16 nor UCS-2, but is something of a mixture of both. While the UEFI specification clearly states UCS-2 is used, this is not what happens to be used in practice.

The EfiStr16 type considers any array of u16 as a valid string, as long as it is terminated by a 0 entry, and it does not contain any other 0 entry. The individual entries must be encoded as native-endian 16-bit unsigned integers.

Implementations

impl EfiStr16

pub unsafe fn from_ptr<'a>(ptr: *const u16) -> &'a EfiStr16

Create Str16 from pointer to u16.

This takes a pointer to a Char16 string as defined by the UEFI specification. It is a C-string based on 16-bit integers and terminated by a 16-bit 0 entry.

This function turns this C-string into a slice of [EfiStr16]. The returned slice does not own the backing memory, but points to the original C-string.

Safety

This function is unsafe for several reasons:

• The caller must guarantee the backing memory of the C-string outlives the livetime 'a.
• The memory pointer to by ptr must be a valid, zero-terminated C-string based on 16-bit integers.

The caller must guarantee that the pointer points to a nul-terminated native-endian UTF-16 string. The string should either originate in UEFI, or be restricted to the subset of UTF-16 that the UEFI spec allows.

pub unsafe fn from_slice_with_nul_unchecked<'a>(slice: &[u16]) -> &EfiStr16

Create Str16 from a slice of u16.

This turns a slice of u16 into a Str16. The original slice is borrowed by the newly returned Str16. The input is not verified for validity. It is the caller’s responsibility to adhere to the safety guarantees.

Safety

This function is unsafe because the caller has to guarantee that the passed slice contains a 0 terminator as its last entry. Furthermore, it must not contain any other 0 entry.

pub fn from_slice_with_nul<'a>( slice: &[u16], ) -> Result<&EfiStr16, FromSliceWithNulError>

Create Str16 from a slice of u16.

This turns a slice of u16 into a Str16. The original slice is borrowed by the newly returned Str16. The input is verified to be a 0-terminated slice, with no other 0 characters embedded in the string.

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

Convert string slice to a raw pointer.

This converts the string slice to a raw pointer. The pointer references the memory inside of self. Therefore, the pointer becomes stale as soon as self goes out of scope.

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

Convert string slice to a u16 slice including the terminating 0 character.

This returns a slice of u16, which borrows the backing memory of the input string. The slice includes the terminating 0 character.

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

Convert string slice to a u16 slice excluding the terminating 0 character.

This returns a slice of u16, which borrows the backing memory of the input string. The slice does not includes the terminating 0 character.

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

Converts an EfiStr16 into a [String].

This converts the input string into a standard rust string. This always requires a memory allocation since the backing data needs to be converted from 16-bit based UCS-2 to 8-bit based UTF-8.

The EfiStr16 type is a lot less strict on its encoding. Therefore, not all instances can be converted to valid UTF-8. If the input string is invalid, this function will raise an error. Use to_string_lossy() if you want the conversion to replace invalid characters.

pub fn to_string_lossy(&self) -> String

Converts an EfiStr16 into a [String], replacing invalid characters with the Unicode replacement character.

This function works like to_string() but whenever invalid characters are found in the input string, they are replaced with the Unicode Replacement Character.

Trait Implementations

impl Clone for Box<EfiStr16>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for EfiStr16

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

Formats the value using the given formatter.

impl Default for &EfiStr16

fn default() -> Self

Returns the “default value” for a type.

impl Default for Box<EfiStr16>

fn default() -> Self

Returns the “default value” for a type.

impl From<&EfiStr16> for Box<EfiStr16>

fn from(s: &EfiStr16) -> Box<EfiStr16>

Converts to this type from the input type.

impl Ord for EfiStr16

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

This method returns an Ordering between self and other.

impl PartialEq for EfiStr16

fn eq(&self, other: &EfiStr16) -> 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 PartialOrd for EfiStr16

fn partial_cmp(&self, other: &EfiStr16) -> 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 Eq for EfiStr16

impl StructuralPartialEq for EfiStr16