Struct uefi::data_types::CStr16
source · pub struct CStr16(/* private fields */);
Expand description
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§
source§impl CStr16
impl CStr16
sourcepub unsafe fn from_ptr<'ptr>(ptr: *const Char16) -> &'ptr Self
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.
sourcepub fn from_u16_with_nul(codes: &[u16]) -> Result<&Self, FromSliceWithNulError>
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.
sourcepub const unsafe fn from_u16_with_nul_unchecked(codes: &[u16]) -> &Self
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.
sourcepub fn from_char16_with_nul(
chars: &[Char16],
) -> Result<&Self, FromSliceWithNulError>
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.
sourcepub const unsafe fn from_char16_with_nul_unchecked(chars: &[Char16]) -> &Self
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.
sourcepub fn from_str_with_buf<'a>(
input: &str,
buf: &'a mut [u16],
) -> Result<&'a Self, FromStrWithBufError>
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();
sourcepub fn from_unaligned_slice<'buf>(
src: &UnalignedSlice<'_, u16>,
buf: &'buf mut [MaybeUninit<u16>],
) -> Result<&'buf Self, UnalignedCStr16Error>
pub fn from_unaligned_slice<'buf>( src: &UnalignedSlice<'_, u16>, buf: &'buf mut [MaybeUninit<u16>], ) -> Result<&'buf Self, UnalignedCStr16Error>
Create a &CStr16
from an UnalignedSlice
using an aligned
buffer for storage. The lifetime of the output is tied to buf
,
not src
.
sourcepub fn as_slice(&self) -> &[Char16]
pub fn as_slice(&self) -> &[Char16]
Get the underlying Char16
s as slice without the trailing null.
sourcepub const fn as_slice_with_nul(&self) -> &[Char16]
pub const fn as_slice_with_nul(&self) -> &[Char16]
Get the underlying Char16
s as slice including the trailing null.
sourcepub fn to_u16_slice(&self) -> &[u16]
pub fn to_u16_slice(&self) -> &[u16]
Converts this C string to a u16 slice without the trailing null.
sourcepub const fn to_u16_slice_with_nul(&self) -> &[u16]
pub const fn to_u16_slice_with_nul(&self) -> &[u16]
Converts this C string to a u16 slice containing the trailing null.
sourcepub const fn num_chars(&self) -> usize
pub const fn num_chars(&self) -> usize
Returns the number of characters without the trailing null. character
sourcepub const fn is_empty(&self) -> bool
pub const fn is_empty(&self) -> bool
Returns if the string is empty. This ignores the null character.
sourcepub const fn num_bytes(&self) -> usize
pub const fn num_bytes(&self) -> usize
Get the number of bytes in the string (including the trailing null).
sourcepub fn is_ascii(&self) -> bool
pub fn is_ascii(&self) -> bool
Checks if all characters in this string are within the ASCII range.
sourcepub fn as_str_in_buf(&self, buf: &mut dyn Write) -> Result
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());
Trait Implementations§
source§impl PartialOrd for CStr16
impl PartialOrd for CStr16
source§impl ToOwned for CStr16
Available on crate feature alloc
only.
impl ToOwned for CStr16
alloc
only.