Struct uefi::data_types::CStr16

pub struct CStr16(/* private fields */);

An UCS-2 null-terminated string slice.

This type is largely inspired by core::ffi::CStr with the exception that all characters are guaranteed to be 16 bit long.

For convenience, a CStr16 is comparable with core::str and alloc::string::String from the standard library through the trait EqStrUntilNul.

Implementations

impl CStr16

pub unsafe fn from_ptr<'ptr>(ptr: *const Char16) -> &'ptr Self

Wraps a raw UEFI string with a safe C string wrapper

Safety

The function will start accessing memory from ptr until the first null character. It’s the callers responsibility to ensure ptr points to a valid string, in accessible memory.

pub fn from_u16_with_nul(codes: &[u16]) -> Result<&Self, FromSliceWithNulError>

Creates a &CStr16 from a u16 slice, if the slice contains exactly one terminating null-byte and all chars are valid UCS-2 chars.

pub const unsafe fn from_u16_with_nul_unchecked(codes: &[u16]) -> &Self

Unsafely creates a &CStr16 from a u16 slice.

Safety

It’s the callers responsibility to ensure chars is a valid UCS-2 null-terminated string, with no interior null characters.

pub fn from_char16_with_nul( chars: &[Char16] ) -> Result<&Self, FromSliceWithNulError>

Creates a &CStr16 from a Char16 slice, if the slice is null-terminated and has no interior null characters.

pub const unsafe fn from_char16_with_nul_unchecked(chars: &[Char16]) -> &Self

Unsafely creates a &CStr16 from a Char16 slice.

Safety

It’s the callers responsibility to ensure chars is null-terminated and has no interior null characters.

pub fn from_str_with_buf<'a>( input: &str, buf: &'a mut [u16] ) -> Result<&'a Self, FromStrWithBufError>

Convert a &str to a &CStr16, backed by a buffer.

The input string must contain only characters representable with UCS-2, and must not contain any null characters (even at the end of the input).

The backing buffer must be big enough to hold the converted string as well as a trailing null character.

Examples

Convert the UTF-8 string “ABC” to a &CStr16:

use uefi::CStr16;

let mut buf = [0; 4];
CStr16::from_str_with_buf("ABC", &mut buf).unwrap();

pub fn from_unaligned_slice<'buf>( src: &UnalignedSlice<'_, u16>, buf: &'buf mut [MaybeUninit<u16>] ) -> Result<&'buf CStr16, UnalignedCStr16Error>

Create a &CStr16 from an UnalignedSlice using an aligned buffer for storage. The lifetime of the output is tied to buf, not src.

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

Returns the inner pointer to this C16 string.

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

Get the underlying Char16s as slice without the trailing null.

pub const fn as_slice_with_nul(&self) -> &[Char16]

Get the underlying Char16s as slice including the trailing null.

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

Converts this C string to a u16 slice without the trailing null.

pub const fn to_u16_slice_with_nul(&self) -> &[u16]

Converts this C string to a u16 slice containing the trailing null.

pub const fn iter(&self) -> CStr16Iter<'_>

Returns an iterator over this C string

pub const fn num_chars(&self) -> usize

Returns the number of characters without the trailing null. character

pub fn is_empty(&self) -> bool

Returns if the string is empty. This ignores the null character.

pub const fn num_bytes(&self) -> usize

Get the number of bytes in the string (including the trailing null).

pub fn is_ascii(&self) -> bool

Checks if all characters in this string are within the ASCII range.

pub fn as_str_in_buf(&self, buf: &mut dyn Write) -> Result

Writes each Char16 as a char (4 bytes long in Rust language) into the buffer. It is up to the implementer of core::fmt::Write to convert the char to a string with proper encoding/charset. For example, in the case of alloc::string::String all Rust chars (UTF-32) get converted to UTF-8.

Example

let firmware_vendor_c16_str: CStr16 = ...;
// crate "arrayvec" uses stack-allocated arrays for Strings => no heap allocations
let mut buf = arrayvec::ArrayString::<128>::new();
firmware_vendor_c16_str.as_str_in_buf(&mut buf);
log::info!("as rust str: {}", buf.as_str());

pub fn as_bytes(&self) -> &[u8]

Returns the underlying bytes as slice including the terminating null character.

Trait Implementations

impl AsRef<[u8]> for CStr16

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<CStr16> for CStr16

fn as_ref(&self) -> &CStr16

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<CStr16> for CString16

Available on crate feature alloc only.

fn as_ref(&self) -> &CStr16

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<CStr16> for Path

Available on crate feature alloc only.

fn as_ref(&self) -> &CStr16

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<CStr16> for PathBuf

Available on crate feature alloc only.

fn as_ref(&self) -> &CStr16

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Path> for CStr16

Available on crate feature alloc only.

fn as_ref(&self) -> &Path

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<[u8]> for CStr16

fn borrow(&self) -> &[u8]

Immutably borrows from an owned value.

impl Borrow<CStr16> for CString16

Available on crate feature alloc only.

fn borrow(&self) -> &CStr16

Immutably borrows from an owned value.

impl Borrow<CStr16> for Path

Available on crate feature alloc only.

fn borrow(&self) -> &CStr16

Immutably borrows from an owned value.

impl Borrow<CStr16> for PathBuf

Available on crate feature alloc only.

fn borrow(&self) -> &CStr16

Immutably borrows from an owned value.

impl Borrow<Path> for CStr16

Available on crate feature alloc only.

fn borrow(&self) -> &Path

Immutably borrows from an owned value.

impl Debug for CStr16

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

Formats the value using the given formatter.

impl Display for CStr16

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

Formats the value using the given formatter.

impl<StrType: AsRef<str> + ?Sized> EqStrUntilNul<StrType> for CStr16

fn eq_str_until_nul(&self, other: &StrType) -> bool

Checks if the provided Rust string StrType is equal to Self until the first null character is found. An exception is the terminating null character of Self which is ignored.

impl<'a> From<&'a CStr16> for &'a Path

Available on crate feature alloc only.

fn from(value: &'a CStr16) -> Self

Converts to this type from the input type.

impl From<&CStr16> for CString16

Available on crate feature alloc only.

fn from(value: &CStr16) -> Self

Converts to this type from the input type.

impl From<&CStr16> for PathBuf

Available on crate feature alloc only.

fn from(value: &CStr16) -> Self

Converts to this type from the input type.

impl From<&CStr16> for String

Available on crate feature alloc only.

fn from(value: &CStr16) -> Self

Converts to this type from the input type.

impl Hash for CStr16

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

impl Ord for CStr16

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

This method returns an Ordering between self and other.

impl PartialEq<&CStr16> for CString16

Available on crate feature alloc only.

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

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

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.

impl PartialEq<CString16> for &CStr16

Available on crate feature alloc only.

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

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

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.

impl PartialEq for CStr16

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

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

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.

impl PartialOrd for CStr16

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl ToOwned for CStr16

Available on crate feature alloc only.

type Owned = CString16

The resulting type after obtaining ownership.

fn to_owned(&self) -> CString16

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.

impl Eq for CStr16

impl StructuralPartialEq for CStr16