Struct widestring::ucstring::U32CString
source · pub struct U32CString { /* private fields */ }
alloc
only.Expand description
An owned, mutable C-style 32-bit wide string for FFI that is nul-aware and nul-terminated.
The string slice of a U32CString
is U32CStr
.
U32CString
strings do not have a defined encoding. While it is sometimes
assumed that they contain possibly invalid or ill-formed UTF-32 data, they may be used for
any wide encoded string.
§Nul termination
U32CString
is aware of nul (0
) values. Unless unchecked conversions are used, all
U32CString
strings end with a nul-terminator in the underlying buffer and contain no
internal nul values. These strings are intended to be used with FFI functions that require
nul-terminated strings.
Because of the nul termination requirement, multiple classes methods for provided for
construction a U32CString
under various scenarios. By default, methods such as
from_ptr
and from_vec
return an error if it contains
any interior nul values before the terminator. For these methods, the input does not need to
contain the terminating nul; it is added if it is does not exist.
_truncate
methods on the other hand, such as
from_ptr_truncate
and
from_vec_truncate
, construct a string that terminates with
the first nul value encountered in the string, and do not return an error. They
automatically ensure the string is terminated in a nul value even if it was not originally.
Finally, unsafe _unchecked
variants of these methods, such as
from_ptr_unchecked
and
from_vec_unchecked
allow bypassing any checks for nul
values, when the input has already been ensured to no interior nul values. Again, any
missing nul terminator is automatically added if necessary.
§Examples
The easiest way to use U32CString
outside of FFI is with the
u32cstr!
macro to convert string literals into nul-terminated UTF-32
strings at compile time:
use widestring::{u32cstr, U32CString};
let hello = U32CString::from(u32cstr!("Hello, world!"));
You can also convert any u32
slice or vector directly:
use widestring::{u32cstr, U32CString};
let sparkle_heart = vec![0x1f496];
let sparkle_heart = U32CString::from_vec(sparkle_heart).unwrap();
// The string will add the missing nul terminator
assert_eq!(u32cstr!("💖"), sparkle_heart);
// This UTf-16 surrogate is invalid UTF-32, but is perfectly valid in U32CString
let malformed_utf32 = vec![0xd83d, 0x0];
let s = U32CString::from_vec(malformed_utf32).unwrap();
assert_eq!(s.len(), 1); // Note the terminating nul is not counted in the length
When working with a FFI, it is useful to create a U32CString
from a pointer:
use widestring::{u32cstr, U32CString};
let sparkle_heart = [0x1f496, 0x0];
let s = unsafe {
// Note the string and pointer length does not include the nul terminator
U32CString::from_ptr(sparkle_heart.as_ptr(), sparkle_heart.len() - 1).unwrap()
};
assert_eq!(u32cstr!("💖"), s);
// Alternatively, if the length of the pointer is unknown but definitely terminates in nul,
// a C-style string version can be used
let s = unsafe { U32CString::from_ptr_str(sparkle_heart.as_ptr()) };
assert_eq!(u32cstr!("💖"), s);
Implementations§
source§impl U32CString
impl U32CString
sourcepub const NUL_TERMINATOR: u32 = 0u32
pub const NUL_TERMINATOR: u32 = 0u32
The nul terminator character value.
sourcepub fn from_vec(v: impl Into<Vec<u32>>) -> Result<Self, ContainsNul<u32>>
pub fn from_vec(v: impl Into<Vec<u32>>) -> Result<Self, ContainsNul<u32>>
Constructs a wide C string from a container of wide character data.
This method will consume the provided data and use the underlying elements to construct a new string. The data will be scanned for invalid interior nul values.
§Errors
This function will return an error if the data contains a nul value that is not the
terminating nul.
The returned error will contain the original Vec
as well as the position of the
nul value.
§Examples
use widestring::U32CString;
let v = vec![84u32, 104u32, 101u32]; // 'T' 'h' 'e'
// Create a wide string from the vector
let wcstr = U32CString::from_vec(v).unwrap();
Empty vectors are valid and will return an empty string with a nul terminator:
use widestring::U32CString;
let wcstr = U32CString::from_vec(vec![]).unwrap();
assert_eq!(wcstr, U32CString::default());
The following example demonstrates errors from nul values in a vector.
use widestring::U32CString;
let v = vec![84u32, 0u32, 104u32, 101u32]; // 'T' NUL 'h' 'e'
// Create a wide string from the vector
let res = U32CString::from_vec(v);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 1);
sourcepub fn from_vec_truncate(v: impl Into<Vec<u32>>) -> Self
pub fn from_vec_truncate(v: impl Into<Vec<u32>>) -> Self
Constructs a wide C string from a container of wide character data, truncating at the first nul terminator.
The string will be truncated at the first nul value in the data.
§Examples
use widestring::U32CString;
let v = vec![84u32, 104u32, 101u32, 0u32]; // 'T' 'h' 'e' NUL
// Create a wide string from the vector
let wcstr = U32CString::from_vec_truncate(v);
sourcepub unsafe fn from_vec_unchecked(v: impl Into<Vec<u32>>) -> Self
pub unsafe fn from_vec_unchecked(v: impl Into<Vec<u32>>) -> Self
Constructs a wide C string from a vector without checking for interior nul values.
A terminating nul value will be appended if the vector does not already have a terminating nul.
§Safety
This method is equivalent to from_vec
except that no runtime
assertion is made that v
contains no interior nul values. Providing a vector with
any nul values that are not the last value in the vector will result in an invalid
C string.
sourcepub fn from_ustr(s: impl AsRef<U32Str>) -> Result<Self, ContainsNul<u32>>
pub fn from_ustr(s: impl AsRef<U32Str>) -> Result<Self, ContainsNul<u32>>
Constructs a wide C string from anything that can be converted to a wide string slice.
The string will be scanned for invalid interior nul values.
§Errors
This function will return an error if the data contains a nul value that is not the
terminating nul.
The returned error will contain a Vec
as well as the position of the nul value.
sourcepub fn from_ustr_truncate(s: impl AsRef<U32Str>) -> Self
pub fn from_ustr_truncate(s: impl AsRef<U32Str>) -> Self
Constructs a wide C string from anything that can be converted to a wide string slice, truncating at the first nul terminator.
The string will be truncated at the first nul value in the string.
sourcepub unsafe fn from_ustr_unchecked(s: impl AsRef<U32Str>) -> Self
pub unsafe fn from_ustr_unchecked(s: impl AsRef<U32Str>) -> Self
Constructs a wide C string from anything that can be converted to a wide string slice, without scanning for invalid nul values.
§Safety
This method is equivalent to from_ustr
except that no runtime
assertion is made that v
contains no interior nul values. Providing a string with
any nul values that are not the last value in the vector will result in an invalid
C string.
sourcepub unsafe fn from_ptr_str(p: *const u32) -> Self
pub unsafe fn from_ptr_str(p: *const u32) -> Self
Constructs a new wide C string copied from a nul-terminated string pointer.
This will scan for nul values beginning with p
. The first nul value will be used
as the nul terminator for the string, similar to how libc string functions such as
strlen
work.
If you wish to avoid copying the string pointer, use U16CStr::from_ptr_str
or
U32CStr::from_ptr_str
instead.
§Safety
This function is unsafe as there is no guarantee that the given pointer is valid or has a nul terminator, and the function could scan past the underlying buffer.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
§Panics
This function panics if p
is null.
§Caveat
The lifetime for the returned string is inferred from its usage. To prevent accidental misuse, it’s suggested to tie the lifetime to whichever source lifetime is safe in the context, such as by providing a helper function taking the lifetime of a host value for the string, or by explicit annotation.
sourcepub unsafe fn from_ptr(
p: *const u32,
len: usize
) -> Result<Self, ContainsNul<u32>>
pub unsafe fn from_ptr( p: *const u32, len: usize ) -> Result<Self, ContainsNul<u32>>
Constructs a wide C string copied from a pointer and a length, checking for invalid interior nul values.
The len
argument is the number of elements, not the number of bytes, and does
not include the nul terminator of the string. If len
is 0
, p
is allowed to
be a null pointer.
The resulting string will always be nul-terminated even if the pointer data is not.
§Errors
This will scan the pointer string for an interior nul value and error if one is
found. To avoid scanning for interior nuls,
from_ptr_unchecked
may be used instead.
The returned error will contain a Vec
as well as the position of the nul value.
§Safety
This function is unsafe as there is no guarantee that the given pointer is valid for
len
elements.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
§Panics
Panics if len
is greater than 0 but p
is a null pointer.
sourcepub unsafe fn from_ptr_truncate(p: *const u32, len: usize) -> Self
pub unsafe fn from_ptr_truncate(p: *const u32, len: usize) -> Self
Constructs a wide C string copied from a pointer and a length, truncating at the first nul terminator.
The len
argument is the number of elements, not the number of bytes. This will
scan for nul values beginning with p
until offset len
. The first nul value will
be used as the nul terminator for the string, ignoring any remaining values left
before len
. If no nul value is found, the whole string of length len
is used,
and a new nul-terminator will be added to the resulting string. If len
is 0
, p
is allowed to be a null pointer.
§Safety
This function is unsafe as there is no guarantee that the given pointer is valid for
len
elements.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
§Panics
Panics if len
is greater than 0 but p
is a null pointer.
sourcepub unsafe fn from_ptr_unchecked(p: *const u32, len: usize) -> Self
pub unsafe fn from_ptr_unchecked(p: *const u32, len: usize) -> Self
Constructs a wide C string copied from a pointer and a length without checking for any nul values.
The len
argument is the number of elements, not the number of bytes, and does
not include the nul terminator of the string. If len
is 0
, p
is allowed to
be a null pointer.
The resulting string will always be nul-terminated even if the pointer data is not.
§Safety
This function is unsafe as there is no guarantee that the given pointer is valid for
len
elements.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
The interior values of the pointer are not scanned for nul. Any interior nul values or will result in an invalid C string.
§Panics
Panics if len
is greater than 0 but p
is a null pointer.
sourcepub fn as_mut_ucstr(&mut self) -> &mut U32CStr
pub fn as_mut_ucstr(&mut self) -> &mut U32CStr
Converts to a mutable wide C string slice.
sourcepub fn into_ustring(self) -> U32String
pub fn into_ustring(self) -> U32String
Converts this string into a wide string without a nul terminator.
The resulting string will not contain a nul-terminator, and will contain no other nul values.
sourcepub fn into_ustring_with_nul(self) -> U32String
pub fn into_ustring_with_nul(self) -> U32String
Converts this string into a wide string with a nul terminator.
The resulting vector will contain a nul-terminator and no interior nul values.
sourcepub fn into_vec(self) -> Vec<u32>
pub fn into_vec(self) -> Vec<u32>
Converts the string into a Vec
without a nul terminator, consuming the string in
the process.
The resulting vector will not contain a nul-terminator, and will contain no other nul values.
sourcepub fn into_vec_with_nul(self) -> Vec<u32>
pub fn into_vec_with_nul(self) -> Vec<u32>
Converts the string into a Vec
, consuming the string in the process.
The resulting vector will contain a nul-terminator and no interior nul values.
sourcepub unsafe fn from_raw(p: *mut u32) -> Self
pub unsafe fn from_raw(p: *mut u32) -> Self
Retakes ownership of a wide C string that was transferred to C.
This should only be used in combination with into_raw
. To
construct a new wide C string from a pointer, use
from_ptr_str
.
§Safety
This should only ever be called with a pointer that was earlier obtained by calling
into_raw
. Additionally, the length of the string will be
recalculated from the pointer by scanning for the nul-terminator.
§Panics
Panics if p
is a null pointer.
sourcepub fn into_boxed_ucstr(self) -> Box<U32CStr>
pub fn into_boxed_ucstr(self) -> Box<U32CStr>
Converts this wide C string into a boxed wide C string slice.
§Examples
use widestring::{U32CString, U32CStr};
let mut v = vec![102u32, 111u32, 111u32]; // "foo"
let c_string = U32CString::from_vec(v.clone()).unwrap();
let boxed = c_string.into_boxed_ucstr();
v.push(0);
assert_eq!(&*boxed, U32CStr::from_slice(&v).unwrap());
source§impl U32CString
impl U32CString
sourcepub fn from_chars(v: impl Into<Vec<char>>) -> Result<Self, ContainsNul<u32>>
pub fn from_chars(v: impl Into<Vec<char>>) -> Result<Self, ContainsNul<u32>>
Constructs a U32CString
from a container of character data, checking for invalid nul
values.
This method will consume the provided data and use the underlying elements to construct a new string. The data will be scanned for invalid nul values anywhere except the last character. The resulting string will always be nul-terminated even if the original string is not.
§Errors
This function will return an error if the data contains a nul value anywhere except the
last character.
The returned error will contain the Vec<u32>
as well as the position of the nul value.
§Examples
use widestring::U32CString;
let v: Vec<char> = "Test".chars().collect();
// Create a wide string from the vector
let wcstr = U32CString::from_chars(v).unwrap();
The following example demonstrates errors from nul values in a vector.
use widestring::U32CString;
let v: Vec<char> = "T\u{0}est".chars().collect();
// Create a wide string from the vector
let res = U32CString::from_chars(v);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 1);
sourcepub fn from_chars_truncate(v: impl Into<Vec<char>>) -> Self
pub fn from_chars_truncate(v: impl Into<Vec<char>>) -> Self
Constructs a U32CString
from a container of character data, truncating at the first nul
value.
This method will consume the provided data and use the underlying elements to construct a new string. The string will be truncated at the first nul value in the string. The resulting string will always be nul-terminated even if the original string is not.
§Examples
use widestring::U32CString;
let v: Vec<char> = "Test\u{0}".chars().collect();
// Create a wide string from the vector
let wcstr = U32CString::from_chars_truncate(v);
sourcepub unsafe fn from_chars_unchecked(v: impl Into<Vec<char>>) -> Self
pub unsafe fn from_chars_unchecked(v: impl Into<Vec<char>>) -> Self
Constructs a U32CString
from character data without checking for nul values.
A terminating nul value will be appended if the vector does not already have a terminating nul.
§Safety
This method is equivalent to from_chars
except that no runtime
assertion is made that v
contains no interior nul values. Providing a vector with nul
values anywhere but the last character will result in an invalid U32CString
.
sourcepub fn from_str(s: impl AsRef<str>) -> Result<Self, ContainsNul<u32>>
pub fn from_str(s: impl AsRef<str>) -> Result<Self, ContainsNul<u32>>
Constructs a U32CString
copy from a str
, encoding it as UTF-32 and checking for
invalid interior nul values.
This makes a string copy of the str
. Since str
will always be valid UTF-8, the
resulting U32CString
will also be valid UTF-32.
The string will be scanned for nul values, which are invalid anywhere except the last character. The resulting string will always be nul-terminated even if the original string is not.
§Errors
This function will return an error if the data contains a nul value anywhere except the
last character.
The returned error will contain a Vec<u32>
as well as the position of the nul value.
§Examples
use widestring::U32CString;
let s = "MyString";
// Create a wide string from the string
let wcstr = U32CString::from_str(s).unwrap();
The following example demonstrates errors from nul values in a string.
use widestring::U32CString;
let s = "My\u{0}String";
// Create a wide string from the string
let res = U32CString::from_str(s);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 2);
sourcepub unsafe fn from_str_unchecked(s: impl AsRef<str>) -> Self
pub unsafe fn from_str_unchecked(s: impl AsRef<str>) -> Self
Constructs a U32CString
copy from a str
, encoding it as UTF-32, without checking for
nul values.
This makes a string copy of the str
. Since str
will always be valid UTF-8, the
resulting U32CString
will also be valid UTF-32.
The resulting string will always be nul-terminated even if the original string is not.
§Safety
This method is equivalent to from_str
except that no runtime assertion
is made that s
contains invalid nul values. Providing a string with nul values anywhere
except the last character will result in an invalid U32CString
.
§Examples
use widestring::U32CString;
let s = "MyString";
// Create a wide string from the string
let wcstr = unsafe { U32CString::from_str_unchecked(s) };
sourcepub fn from_str_truncate(s: impl AsRef<str>) -> Self
pub fn from_str_truncate(s: impl AsRef<str>) -> Self
Constructs a U32CString
copy from a str
, encoding it as UTF-32, truncating at the
first nul terminator.
This makes a string copy of the str
. Since str
will always be valid UTF-8, the
resulting U32CString
will also be valid UTF-32.
The string will be truncated at the first nul value in the string. The resulting string will always be nul-terminated even if the original string is not.
§Examples
use widestring::U32CString;
let s = "My\u{0}String";
// Create a wide string from the string
let wcstr = U32CString::from_str_truncate(s);
assert_eq!(wcstr.to_string_lossy(), "My");
sourcepub unsafe fn from_char_ptr_str(p: *const char) -> Self
pub unsafe fn from_char_ptr_str(p: *const char) -> Self
Constructs a new wide C string copied from a nul-terminated char
string pointer.
This will scan for nul values beginning with p
. The first nul value will be used as the
nul terminator for the string, similar to how libc string functions such as strlen
work.
If you wish to avoid copying the string pointer, use U32CStr::from_char_ptr_str
instead.
§Safety
This function is unsafe as there is no guarantee that the given pointer is valid or has a nul terminator, and the function could scan past the underlying buffer.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
§Panics
This function panics if p
is null.
§Caveat
The lifetime for the returned string is inferred from its usage. To prevent accidental misuse, it’s suggested to tie the lifetime to whichever source lifetime is safe in the context, such as by providing a helper function taking the lifetime of a host value for the string, or by explicit annotation.
sourcepub unsafe fn from_char_ptr(
p: *const char,
len: usize
) -> Result<Self, ContainsNul<u32>>
pub unsafe fn from_char_ptr( p: *const char, len: usize ) -> Result<Self, ContainsNul<u32>>
Constructs a wide C string copied from a char
pointer and a length, checking for invalid
interior nul values.
The len
argument is the number of elements, not the number of bytes, and does
not include the nul terminator of the string. If len
is 0
, p
is allowed to be a
null pointer.
The resulting string will always be nul-terminated even if the pointer data is not.
§Errors
This will scan the pointer string for an interior nul value and error if one is found. To
avoid scanning for interior nuls, from_ptr_unchecked
may be
used instead.
The returned error will contain a Vec
as well as the position of the nul value.
§Safety
This function is unsafe as there is no guarantee that the given pointer is valid for len
elements.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
§Panics
Panics if len
is greater than 0 but p
is a null pointer.
sourcepub unsafe fn from_char_ptr_truncate(p: *const char, len: usize) -> Self
pub unsafe fn from_char_ptr_truncate(p: *const char, len: usize) -> Self
Constructs a wide C string copied from a char
pointer and a length, truncating at the
first nul terminator.
The len
argument is the number of elements, not the number of bytes. This will scan
for nul values beginning with p
until offset len
. The first nul value will be used as
the nul terminator for the string, ignoring any remaining values left before len
. If no
nul value is found, the whole string of length len
is used, and a new nul-terminator
will be added to the resulting string. If len
is 0
, p
is allowed to be a null pointer.
§Safety
This function is unsafe as there is no guarantee that the given pointer is valid for len
elements.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
§Panics
Panics if len
is greater than 0 but p
is a null pointer.
sourcepub unsafe fn from_char_ptr_unchecked(p: *const char, len: usize) -> Self
pub unsafe fn from_char_ptr_unchecked(p: *const char, len: usize) -> Self
Constructs a wide C string copied from a char
pointer and a length without checking for
any nul values.
The len
argument is the number of elements, not the number of bytes, and does
not include the nul terminator of the string. If len
is 0
, p
is allowed to be a
null pointer.
The resulting string will always be nul-terminated even if the pointer data is not.
§Safety
This function is unsafe as there is no guarantee that the given pointer is valid for len
elements.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
The interior values of the pointer are not scanned for nul. Any interior nul values or will result in an invalid C string.
§Panics
Panics if len
is greater than 0 but p
is a null pointer.
sourcepub fn from_os_str(s: impl AsRef<OsStr>) -> Result<Self, ContainsNul<u32>>
Available on crate feature std
only.
pub fn from_os_str(s: impl AsRef<OsStr>) -> Result<Self, ContainsNul<u32>>
std
only.Constructs a U32CString
copy from an OsStr
, checking for invalid
nul values.
This makes a string copy of the OsStr
. Since OsStr
makes no guarantees that it is valid data, there is no guarantee that the resulting
U32CString
will be valid UTF-32.
The string will be scanned for nul values, which are invlaid anywhere except the last character. The resulting string will always be nul-terminated even if the string is not.
Note that the encoding of OsStr
is platform-dependent, so on
some platforms this may make an encoding conversions, while on other platforms no changes to
the string will be made.
§Errors
This function will return an error if the data contains a nul value anywhere except the
last character.
The returned error will contain a Vec<u32>
as well as the position of the nul value.
§Examples
use widestring::U32CString;
let s = "MyString";
// Create a wide string from the string
let wcstr = U32CString::from_os_str(s).unwrap();
The following example demonstrates errors from nul values in a string.
use widestring::U32CString;
let s = "My\u{0}String";
// Create a wide string from the string
let res = U32CString::from_os_str(s);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 2);
sourcepub unsafe fn from_os_str_unchecked(s: impl AsRef<OsStr>) -> Self
Available on crate feature std
only.
pub unsafe fn from_os_str_unchecked(s: impl AsRef<OsStr>) -> Self
std
only.Constructs a U32CString
copy from an OsStr
, without checking for
nul values.
This makes a string copy of the OsStr
. Since OsStr
makes no guarantees that it is valid data, there is no guarantee that the resulting
U32CString
will be valid UTF-32.
The resulting string will always be nul-terminated even if the string is not.
Note that the encoding of OsStr
is platform-dependent, so on
some platforms this may make an encoding conversions, while on other platforms no changes to
the string will be made.
§Safety
This method is equivalent to from_os_str
except that no runtime
assertion is made that s
contains invalid nul values. Providing a string with nul values
anywhere except the last character will result in an invalid U32CString
.
§Examples
use widestring::U32CString;
let s = "MyString";
// Create a wide string from the string
let wcstr = unsafe { U32CString::from_os_str_unchecked(s) };
sourcepub fn from_os_str_truncate(s: impl AsRef<OsStr>) -> Self
Available on crate feature std
only.
pub fn from_os_str_truncate(s: impl AsRef<OsStr>) -> Self
std
only.Constructs a U32CString
copy from an OsStr
, truncating at the first
nul terminator.
This makes a string copy of the OsStr
. Since OsStr
makes no guarantees that it is valid data, there is no guarantee that the resulting
U32CString
will be valid UTF-32.
The string will be truncated at the first nul value in the string. The resulting string will always be nul-terminated even if the string is not.
Note that the encoding of OsStr
is platform-dependent, so on
some platforms this may make an encoding conversions, while on other platforms no changes to
the string will be made.
§Examples
use widestring::U32CString;
let s = "My\u{0}String";
// Create a wide string from the string
let wcstr = U32CString::from_os_str_truncate(s);
assert_eq!(wcstr.to_string_lossy(), "My");
Methods from Deref<Target = U32CStr>§
pub const NUL_TERMINATOR: u32 = 0u32
sourcepub fn to_ucstring(&self) -> U32CString
pub fn to_ucstring(&self) -> U32CString
Copies the string reference to a new owned wide C string.
sourcepub fn to_ustring(&self) -> U32String
pub fn to_ustring(&self) -> U32String
Copies the string reference to a new owned wide string.
The resulting wide string will not have a nul terminator.
§Examples
use widestring::U32CString;
let wcstr = U32CString::from_str("MyString").unwrap();
// Convert U32CString to a U32String
let wstr = wcstr.to_ustring();
// U32CString will have a terminating nul
let wcvec = wcstr.into_vec_with_nul();
assert_eq!(wcvec[wcvec.len()-1], 0);
// The resulting U32String will not have the terminating nul
let wvec = wstr.into_vec();
assert_ne!(wvec[wvec.len()-1], 0);
sourcepub fn as_slice(&self) -> &[u32]
pub fn as_slice(&self) -> &[u32]
Converts to a slice of the underlying elements.
The slice will not include the nul terminator.
sourcepub unsafe fn as_mut_slice(&mut self) -> &mut [u32]
pub unsafe fn as_mut_slice(&mut self) -> &mut [u32]
Converts to a mutable slice of the underlying elements.
The slice will not include the nul terminator.
§Safety
This method is unsafe because you can violate the invariants of this type when mutating the slice (i.e. by adding interior nul values).
sourcepub fn as_slice_with_nul(&self) -> &[u32]
pub fn as_slice_with_nul(&self) -> &[u32]
Converts to a slice of the underlying elements, including the nul terminator.
sourcepub fn as_ptr(&self) -> *const u32
pub fn as_ptr(&self) -> *const u32
Returns a raw pointer to the string.
The caller must ensure that the string outlives the pointer this function returns, or else it will end up pointing to garbage.
The caller must also ensure that the memory the pointer (non-transitively) points to
is never written to (except inside an UnsafeCell
) using this pointer or any
pointer derived from it. If you need to mutate the contents of the string, use
as_mut_ptr
.
Modifying the container referenced by this string may cause its buffer to be reallocated, which would also make any pointers to it invalid.
sourcepub fn as_mut_ptr(&mut self) -> *mut u32
pub fn as_mut_ptr(&mut self) -> *mut u32
Returns a mutable raw pointer to the string.
The caller must ensure that the string outlives the pointer this function returns, or else it will end up pointing to garbage.
Modifying the container referenced by this string may cause its buffer to be reallocated, which would also make any pointers to it invalid.
sourcepub fn as_ptr_range(&self) -> Range<*const u32>
pub fn as_ptr_range(&self) -> Range<*const u32>
Returns the two raw pointers spanning the string slice.
The returned range is half-open, which means that the end pointer points one past the last element of the slice. This way, an empty slice is represented by two equal pointers, and the difference between the two pointers represents the size of the slice.
See as_ptr
for warnings on using these pointers. The end pointer
requires extra caution, as it does not point to a valid element in the slice.
This function is useful for interacting with foreign interfaces which use two pointers to refer to a range of elements in memory, as is common in C++.
sourcepub fn as_mut_ptr_range(&mut self) -> Range<*mut u32>
pub fn as_mut_ptr_range(&mut self) -> Range<*mut u32>
Returns the two unsafe mutable pointers spanning the string slice.
The returned range is half-open, which means that the end pointer points one past the last element of the slice. This way, an empty slice is represented by two equal pointers, and the difference between the two pointers represents the size of the slice.
See as_mut_ptr
for warnings on using these pointers. The end
pointer requires extra caution, as it does not point to a valid element in the
slice.
This function is useful for interacting with foreign interfaces which use two pointers to refer to a range of elements in memory, as is common in C++.
sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the length of the string as number of elements (not number of bytes) not including nul terminator.
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns whether this string contains no data (i.e. is only the nul terminator).
sourcepub fn as_ustr(&self) -> &U32Str
pub fn as_ustr(&self) -> &U32Str
Returns a wide string slice to this wide C string slice.
The wide string slice will not include the nul-terminator.
sourcepub fn as_ustr_with_nul(&self) -> &U32Str
pub fn as_ustr_with_nul(&self) -> &U32Str
Returns a wide string slice to this wide C string slice.
The wide string slice will include the nul-terminator.
sourcepub unsafe fn as_mut_ustr(&mut self) -> &mut U32Str
pub unsafe fn as_mut_ustr(&mut self) -> &mut U32Str
Returns a mutable wide string slice to this wide C string slice.
The wide string slice will not include the nul-terminator.
§Safety
This method is unsafe because you can violate the invariants of this type when mutating the string (i.e. by adding interior nul values).
sourcepub fn display(&self) -> Display<'_, U32CStr>
pub fn display(&self) -> Display<'_, U32CStr>
Returns an object that implements Display
for printing
strings that may contain non-Unicode data.
A wide C string might data of any encoding. This function assumes the string is encoded in
UTF-32, and returns a struct implements the
Display
trait in a way that decoding the string is lossy but
no heap allocations are performed, such as by
to_string_lossy
.
By default, invalid Unicode data is replaced with
U+FFFD REPLACEMENT CHARACTER
(�). If you wish
to simply skip any invalid Uncode data and forego the replacement, you may use the
alternate formatting with {:#}
.
§Examples
Basic usage:
use widestring::U32CStr;
// 𝄞mus<invalid>ic<invalid>
let s = U32CStr::from_slice(&[
0x1d11e, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834, 0x0000,
]).unwrap();
assert_eq!(format!("{}", s.display()),
"𝄞mus�ic�"
);
Using alternate formatting style to skip invalid values entirely:
use widestring::U32CStr;
// 𝄞mus<invalid>ic<invalid>
let s = U32CStr::from_slice(&[
0x1d11e, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834, 0x0000,
]).unwrap();
assert_eq!(format!("{:#}", s.display()),
"𝄞music"
);
sourcepub fn get<I>(&self, i: I) -> Option<&U32Str>
pub fn get<I>(&self, i: I) -> Option<&U32Str>
Returns a subslice of the string.
This is the non-panicking alternative to indexing the string. Returns None
whenever equivalent indexing operation would panic.
sourcepub unsafe fn get_mut<I>(&mut self, i: I) -> Option<&mut U32Str>
pub unsafe fn get_mut<I>(&mut self, i: I) -> Option<&mut U32Str>
Returns a mutable subslice of the string.
This is the non-panicking alternative to indexing the string. Returns None
whenever equivalent indexing operation would panic.
§Safety
This method is unsafe because you can violate the invariants of this type when mutating the memory the pointer points to (i.e. by adding interior nul values).
sourcepub unsafe fn get_unchecked<I>(&self, i: I) -> &U32Str
pub unsafe fn get_unchecked<I>(&self, i: I) -> &U32Str
Returns an unchecked subslice of the string.
This is the unchecked alternative to indexing the string.
§Safety
Callers of this function are responsible that these preconditions are satisfied:
- The starting index must not exceed the ending index;
- Indexes must be within bounds of the original slice.
Failing that, the returned string slice may reference invalid memory.
sourcepub unsafe fn get_unchecked_mut<I>(&mut self, i: I) -> &mut U32Str
pub unsafe fn get_unchecked_mut<I>(&mut self, i: I) -> &mut U32Str
Returns aa mutable, unchecked subslice of the string.
This is the unchecked alternative to indexing the string.
§Safety
Callers of this function are responsible that these preconditions are satisfied:
- The starting index must not exceed the ending index;
- Indexes must be within bounds of the original slice.
Failing that, the returned string slice may reference invalid memory.
This method is unsafe because you can violate the invariants of this type when mutating the memory the pointer points to (i.e. by adding interior nul values).
sourcepub fn split_at(&self, mid: usize) -> (&U32Str, &U32Str)
pub fn split_at(&self, mid: usize) -> (&U32Str, &U32Str)
Divide one string slice into two at an index.
The argument, mid
, should be an offset from the start of the string.
The two slices returned go from the start of the string slice to mid
, and from
mid
to the end of the string slice.
To get mutable string slices instead, see the split_at_mut
method.
sourcepub unsafe fn split_at_mut(&mut self, mid: usize) -> (&mut U32Str, &mut U32Str)
pub unsafe fn split_at_mut(&mut self, mid: usize) -> (&mut U32Str, &mut U32Str)
Divide one mutable string slice into two at an index.
The argument, mid
, should be an offset from the start of the string.
The two slices returned go from the start of the string slice to mid
, and from
mid
to the end of the string slice.
To get immutable string slices instead, see the split_at
method.
§Safety
This method is unsafe because you can violate the invariants of this type when mutating the memory the pointer points to (i.e. by adding interior nul values).
sourcepub fn repeat(&self, n: usize) -> U32CString
pub fn repeat(&self, n: usize) -> U32CString
Creates a new owned string by repeating this string n
times.
§Panics
This function will panic if the capacity would overflow.
sourcepub fn to_os_string(&self) -> OsString
Available on crate feature std
only.
pub fn to_os_string(&self) -> OsString
std
only.Decodes a string reference to an owned OsString
.
This makes a string copy of this reference. Since U32CStr
makes no guarantees that it
is valid UTF-32, there is no guarantee that the resulting OsString
will be valid data. The OsString
will not have a nul
terminator.
Note that the encoding of OsString
is platform-dependent, so on
some platforms this may make an encoding conversions, while on other platforms no changes to
the string will be made.
§Examples
use widestring::U32CString;
use std::ffi::OsString;
let s = "MyString";
// Create a wide string from the string
let wstr = U32CString::from_str(s).unwrap();
// Create an OsString from the wide string
let osstr = wstr.to_os_string();
assert_eq!(osstr, OsString::from(s));
sourcepub fn to_string(&self) -> Result<String, Utf32Error>
pub fn to_string(&self) -> Result<String, Utf32Error>
Decodes the string reference to a String
if it contains valid UTF-32 data.
This method assumes this string is encoded as UTF-32 and attempts to decode it as such. It will *not have a nul terminator.
§Errors
Returns an error if the string contains any invalid UTF-32 data.
§Examples
use widestring::U32CString;
let s = "MyString";
// Create a wide string from the string
let wstr = U32CString::from_str(s).unwrap();
// Create a regular string from the wide string
let s2 = wstr.to_string().unwrap();
assert_eq!(s2, s);
sourcepub fn to_string_lossy(&self) -> String
pub fn to_string_lossy(&self) -> String
Decodes the string reference to a String
even if it is invalid UTF-32 data.
This method assumes this string is encoded as UTF-16 and attempts to decode it as such. Any
invalid sequences are replaced with
U+FFFD REPLACEMENT CHARACTER
, which looks like this:
�. It will *not have a nul terminator.
§Examples
use widestring::U32CString;
let s = "MyString";
// Create a wide string from the string
let wstr = U32CString::from_str(s).unwrap();
// Create a regular string from the wide string
let s2 = wstr.to_string_lossy();
assert_eq!(s2, s);
sourcepub fn chars(&self) -> CharsUtf32<'_> ⓘ
pub fn chars(&self) -> CharsUtf32<'_> ⓘ
Returns an iterator over the char
s of a string slice.
As this string has no defined encoding, this method assumes the string is UTF-32. Since it
may consist of invalid UTF-32, the iterator returned by this method
is an iterator over Result<char, DecodeUtf32Error>
instead of char
s
directly. If you would like a lossy iterator over chars
s directly, instead
use chars_lossy
.
It’s important to remember that char
represents a Unicode Scalar Value, and
may not match your idea of what a ‘character’ is. Iteration over grapheme clusters may be
what you actually want. That functionality is not provided by by this crate.
sourcepub fn chars_lossy(&self) -> CharsLossyUtf32<'_> ⓘ
pub fn chars_lossy(&self) -> CharsLossyUtf32<'_> ⓘ
Returns a lossy iterator over the char
s of a string slice.
As this string has no defined encoding, this method assumes the string is UTF-32. Since it
may consist of invalid UTF-32, the iterator returned by this method will replace invalid
data with
U+FFFD REPLACEMENT CHARACTER
(�). This is a lossy
version of chars
.
It’s important to remember that char
represents a Unicode Scalar Value, and
may not match your idea of what a ‘character’ is. Iteration over grapheme clusters may be
what you actually want. That functionality is not provided by by this crate.
sourcepub fn char_indices(&self) -> CharIndicesUtf32<'_> ⓘ
pub fn char_indices(&self) -> CharIndicesUtf32<'_> ⓘ
Returns an iterator over the chars of a string slice, and their positions.
As this string has no defined encoding, this method assumes the string is UTF-32. Since it
may consist of invalid UTF-32, the iterator returned by this method is an iterator over
Result<char, DecodeUtf32Error>
as well as their positions, instead of
char
s directly. If you would like a lossy indices iterator over
chars
s directly, instead use
char_indices_lossy
.
The iterator yields tuples. The position is first, the char
is second.
sourcepub fn char_indices_lossy(&self) -> CharIndicesLossyUtf32<'_> ⓘ
pub fn char_indices_lossy(&self) -> CharIndicesLossyUtf32<'_> ⓘ
Returns a lossy iterator over the chars of a string slice, and their positions.
As this string slice may consist of invalid UTF-32, the iterator returned by this method
will replace invalid values with
U+FFFD REPLACEMENT CHARACTER
(�), as well as the
positions of all characters. This is a lossy version of
char_indices
.
The iterator yields tuples. The position is first, the char
is second.
Trait Implementations§
source§impl AsMut<U32CStr> for U32CString
impl AsMut<U32CStr> for U32CString
source§impl AsRef<[u32]> for U32CString
impl AsRef<[u32]> for U32CString
source§impl AsRef<U32CStr> for U32CString
impl AsRef<U32CStr> for U32CString
source§impl AsRef<U32Str> for U32CString
impl AsRef<U32Str> for U32CString
source§impl Borrow<U32CStr> for U32CString
impl Borrow<U32CStr> for U32CString
source§impl BorrowMut<U32CStr> for U32CString
impl BorrowMut<U32CStr> for U32CString
source§fn borrow_mut(&mut self) -> &mut U32CStr
fn borrow_mut(&mut self) -> &mut U32CStr
source§impl Clone for U32CString
impl Clone for U32CString
source§fn clone(&self) -> U32CString
fn clone(&self) -> U32CString
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for U32CString
impl Debug for U32CString
source§impl Default for U32CString
impl Default for U32CString
source§impl Deref for U32CString
impl Deref for U32CString
source§impl DerefMut for U32CString
impl DerefMut for U32CString
source§impl Drop for U32CString
impl Drop for U32CString
source§impl Extend<U32CString> for U32String
impl Extend<U32CString> for U32String
source§fn extend<T: IntoIterator<Item = U32CString>>(&mut self, iter: T)
fn extend<T: IntoIterator<Item = U32CString>>(&mut self, iter: T)
source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)source§impl From<U32CString> for OsString
impl From<U32CString> for OsString
source§fn from(s: U32CString) -> OsString
fn from(s: U32CString) -> OsString
source§impl From<U32CString> for U32String
impl From<U32CString> for U32String
source§fn from(s: U32CString) -> Self
fn from(s: U32CString) -> Self
source§impl From<U32CString> for Vec<u32>
impl From<U32CString> for Vec<u32>
source§fn from(value: U32CString) -> Self
fn from(value: U32CString) -> Self
source§impl FromIterator<U32CString> for U32String
impl FromIterator<U32CString> for U32String
source§fn from_iter<T: IntoIterator<Item = U32CString>>(iter: T) -> Self
fn from_iter<T: IntoIterator<Item = U32CString>>(iter: T) -> Self
source§impl Hash for U32CString
impl Hash for U32CString
source§impl<I> Index<I> for U32CString
impl<I> Index<I> for U32CString
source§impl Ord for U32CString
impl Ord for U32CString
source§fn cmp(&self, other: &U32CString) -> Ordering
fn cmp(&self, other: &U32CString) -> Ordering
1.21.0 · source§fn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
source§impl<'a> PartialEq<&'a U32CStr> for U32CString
impl<'a> PartialEq<&'a U32CStr> for U32CString
source§impl<'a> PartialEq<&'a U32Str> for U32CString
impl<'a> PartialEq<&'a U32Str> for U32CString
source§impl<'a> PartialEq<Cow<'a, U32CStr>> for U32CString
impl<'a> PartialEq<Cow<'a, U32CStr>> for U32CString
source§impl<'a> PartialEq<Cow<'a, U32Str>> for U32CString
impl<'a> PartialEq<Cow<'a, U32Str>> for U32CString
source§impl PartialEq<U32CStr> for U32CString
impl PartialEq<U32CStr> for U32CString
source§impl PartialEq<U32CString> for &U32CStr
impl PartialEq<U32CString> for &U32CStr
source§fn eq(&self, other: &U32CString) -> bool
fn eq(&self, other: &U32CString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<U32CString> for &U32Str
impl PartialEq<U32CString> for &U32Str
source§fn eq(&self, other: &U32CString) -> bool
fn eq(&self, other: &U32CString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<U32CString> for U32CStr
impl PartialEq<U32CString> for U32CStr
source§fn eq(&self, other: &U32CString) -> bool
fn eq(&self, other: &U32CString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<U32CString> for U32Str
impl PartialEq<U32CString> for U32Str
source§fn eq(&self, other: &U32CString) -> bool
fn eq(&self, other: &U32CString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<U32CString> for U32String
impl PartialEq<U32CString> for U32String
source§fn eq(&self, other: &U32CString) -> bool
fn eq(&self, other: &U32CString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<U32CString> for Utf32Str
impl PartialEq<U32CString> for Utf32Str
source§fn eq(&self, other: &U32CString) -> bool
fn eq(&self, other: &U32CString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<U32CString> for Utf32String
impl PartialEq<U32CString> for Utf32String
source§fn eq(&self, other: &U32CString) -> bool
fn eq(&self, other: &U32CString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<U32Str> for U32CString
impl PartialEq<U32Str> for U32CString
source§impl PartialEq<U32String> for U32CString
impl PartialEq<U32String> for U32CString
source§impl PartialEq<Utf32Str> for U32CString
impl PartialEq<Utf32Str> for U32CString
source§impl PartialEq<Utf32String> for U32CString
impl PartialEq<Utf32String> for U32CString
source§fn eq(&self, other: &Utf32String) -> bool
fn eq(&self, other: &Utf32String) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq for U32CString
impl PartialEq for U32CString
source§fn eq(&self, other: &U32CString) -> bool
fn eq(&self, other: &U32CString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl<'a> PartialOrd<&'a U32CStr> for U32CString
impl<'a> PartialOrd<&'a U32CStr> for U32CString
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<'a> PartialOrd<&'a U32Str> for U32CString
impl<'a> PartialOrd<&'a U32Str> for U32CString
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<'a> PartialOrd<Cow<'a, U32CStr>> for U32CString
impl<'a> PartialOrd<Cow<'a, U32CStr>> for U32CString
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<'a> PartialOrd<Cow<'a, U32Str>> for U32CString
impl<'a> PartialOrd<Cow<'a, U32Str>> for U32CString
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl PartialOrd<U32CStr> for U32CString
impl PartialOrd<U32CStr> for U32CString
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl PartialOrd<U32CString> for U32String
impl PartialOrd<U32CString> for U32String
source§fn partial_cmp(&self, other: &U32CString) -> Option<Ordering>
fn partial_cmp(&self, other: &U32CString) -> Option<Ordering>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl PartialOrd<U32Str> for U32CString
impl PartialOrd<U32Str> for U32CString
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl PartialOrd<U32String> for U32CString
impl PartialOrd<U32String> for U32CString
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl PartialOrd for U32CString
impl PartialOrd for U32CString
source§fn partial_cmp(&self, other: &U32CString) -> Option<Ordering>
fn partial_cmp(&self, other: &U32CString) -> Option<Ordering>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read more