Type Alias WideCStr

Help

pub type WideCStr = U32CStr;

Expand description

Alias for U16CStr or U32CStr depending on platform. Intended to match typical C wchar_t size on platform.

Aliased Type§

struct WideCStr { /* private fields */ }

Implementations

Source §

impl U32CStr

Source

pub const NUL_TERMINATOR: u32 = 0u32

The nul terminator character value.

Source

pub fn new<S: AsRef<U32CStr> + ?Sized>(s: &S) -> &Self

Coerces a value into a wide C string slice.

Source

pub unsafe fn from_ptr_str<'a>(p: *const u32) -> &'a Self

Constructs a wide C string slice 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.

§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. In particular, the returned string reference must not be mutated for the duration of lifetime 'a, except inside an UnsafeCell.

§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.

Source

pub unsafe fn from_ptr_str_mut<'a>(p: *mut u32) -> &'a mut Self

Constructs a mutable wide C string slice from a mutable 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.

§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_mut.

§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.

Source

pub unsafe fn from_ptr<'a>( p: *const u32, len: usize, ) -> Result<&'a Self, NulError<u32>>

Constructs a wide C string slice from a pointer and a length.

The len argument is the number of elements, not the number of bytes, and does not include the nul terminator of the string. Thus, a len of 0 is valid and means that p is a pointer directly to the nul terminator of the string.

§Errors

This will scan the pointer string for an interior nul value and error if one is found before the nul terminator at len offset. To avoid scanning for interior nuls, from_ptr_unchecked may be used instead.

An error is returned if the value at len offset is not a nul terminator.

§Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len + 1 elements.

In addition, the data must meet the safety conditions of std::slice::from_raw_parts. In particular, the returned string reference must not be mutated for the duration of lifetime 'a, except inside an UnsafeCell.

§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.

Source

pub unsafe fn from_ptr_mut<'a>( p: *mut u32, len: usize, ) -> Result<&'a mut Self, NulError<u32>>

Constructs a mutable wide C string slice from a mutable pointer and a length.

The len argument is the number of elements, not the number of bytes, and does not include the nul terminator of the string. Thus, a len of 0 is valid and means that p is a pointer directly to the nul terminator of the string.

§Errors

This will scan the pointer string for an interior nul value and error if one is found before the nul terminator at len offset. To avoid scanning for interior nuls, from_ptr_unchecked_mut may be used instead.

An error is returned if the value at len offset is not a nul terminator.

§Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len + 1 elements.

In addition, the data must meet the safety conditions of std::slice::from_raw_parts_mut.

§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.

Source

pub unsafe fn from_ptr_truncate<'a>( p: *const u32, len: usize, ) -> Result<&'a Self, MissingNulTerminator>

Constructs a wide C string slice 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.

§Errors

If no nul terminator is found after len + 1 elements, an error is returned.

§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. In particular, the returned string reference must not be mutated for the duration of lifetime 'a, except inside an UnsafeCell.

§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 thev string, or by explicit annotation.

Source

pub unsafe fn from_ptr_truncate_mut<'a>( p: *mut u32, len: usize, ) -> Result<&'a mut Self, MissingNulTerminator>

Constructs a mutable wide C string slice from a mutable 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.

§Errors

If no nul terminator is found after len + 1 elements, an error is returned.

§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_mut.

§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.

Source

pub unsafe fn from_ptr_unchecked<'a>(p: *const u32, len: usize) -> &'a Self

Constructs a wide C string slice 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. Thus, a len of 0 is valid and means that p is a pointer directly to the nul terminator of the string.

§Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len + 1 elements, nor that it has a terminating nul value.

In addition, the data must meet the safety conditions of std::slice::from_raw_parts. In particular, the returned string reference must not be mutated for the duration of lifetime 'a, except inside an UnsafeCell.

The interior values of the pointer are not scanned for nul. Any interior nul values or a missing nul terminator at pointer offset len + 1 will result in an invalid string slice.

§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.

Source

pub unsafe fn from_ptr_unchecked_mut<'a>( p: *mut u32, len: usize, ) -> &'a mut Self

Constructs a mutable wide C string slice from a mutable 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. Thus, a len of 0 is valid and means that p is a pointer directly to the nul terminator of the string.

§Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len + 1 elements, nor that is has a terminating nul value.

In addition, the data must meet the safety conditions of std::slice::from_raw_parts_mut.

The interior values of the pointer are not scanned for nul. Any interior nul values or a missing nul terminator at pointer offset len + 1 will result in an invalid string slice.

§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.

Source

pub fn from_slice(slice: &[u32]) -> Result<&Self, NulError<u32>>

Constructs a wide C string slice from a slice of values with a terminating nul, checking for invalid interior nul values.

The slice must have at least one item, the nul terminator, even for an empty string.

§Errors

If there are nul values in the slice except for the last value, an error is returned.

An error is also returned if the last value of the slice is not a nul terminator.

Source

pub fn from_slice_mut(slice: &mut [u32]) -> Result<&mut Self, NulError<u32>>

Constructs a mutable wide C string slice from a mutable slice of values with a terminating nul, checking for invalid interior nul values.

The slice must have at least one item, the nul terminator, even for an empty string.

§Errors

If there are nul values in the slice except for the last value, an error is returned.

An error is also returned if the last value of the slice is not a nul terminator.

Source

pub fn from_slice_truncate(slice: &[u32]) -> Result<&Self, MissingNulTerminator>

Constructs a wide C string slice from a slice of values, truncating at the first nul terminator.

The slice will be scanned for nul values. When a nul value is found, it is treated as the terminator for the string, and the string slice will be truncated to that nul.

§Errors

If there are no nul values in the slice, an error is returned.

Source

pub fn from_slice_truncate_mut( slice: &mut [u32], ) -> Result<&mut Self, MissingNulTerminator>

Constructs a mutable wide C string slice from a mutable slice of values, truncating at the first nul terminator.

The slice will be scanned for nul values. When a nul value is found, it is treated as the terminator for the string, and the string slice will be truncated to that nul.

§Errors

If there are no nul values in the slice, an error is returned.

Source

pub const unsafe fn from_slice_unchecked(slice: &[u32]) -> &Self

Constructs a wide C string slice from a slice of values without checking for a terminating or interior nul values.

§Safety

This function is unsafe because it can lead to invalid string slice values when the slice is missing a terminating nul value or there are non-terminating interior nul values in the slice. In particular, an empty slice will result in an invalid string slice.

Source

pub unsafe fn from_slice_unchecked_mut(slice: &mut [u32]) -> &mut Self

Constructs a mutable wide C string slice from a mutable slice of values without checking for a terminating or interior nul values.

§Safety

This function is unsafe because it can lead to invalid string slice values when the slice is missing a terminating nul value or there are non-terminating interior nul values in the slice. In particular, an empty slice will result in an invalid string slice.

Source

pub fn to_ucstring(&self) -> U32CString

Copies the string reference to a new owned wide C string.

Source

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);

Source

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

Converts to a slice of the underlying elements.

The slice will not include the nul terminator.

Source

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).

Source

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

Converts to a slice of the underlying elements, including the nul terminator.

Source

pub const 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.

Source

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.

Source

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++.

Source

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++.

Source

pub const fn len(&self) -> usize

Returns the length of the string as number of elements (not number of bytes) not including nul terminator.

Source

pub const fn is_empty(&self) -> bool

Returns whether this string contains no data (i.e. is only the nul terminator).

Source

pub fn into_ucstring(self: Box<Self>) -> U32CString

Converts a boxed wide C string slice into an owned wide C string without copying or allocating.

§Examples

use widestring::U32CString;

let v = vec![102u32, 111u32, 111u32]; // "foo"
let c_string = U32CString::from_vec(v.clone()).unwrap();
let boxed = c_string.into_boxed_ucstr();
assert_eq!(boxed.into_ucstring(), U32CString::from_vec(v).unwrap());

Source

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.

Source

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.

Source

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).

Source

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"
);

Source

pub fn get(&self, i: I) -> Option<&U32Str>
where I: SliceIndex<[u32], Output = [u32]>,

Returns a subslice of the string.

This is the non-panicking alternative to indexing the string. Returns None whenever equivalent indexing operation would panic.

Source

pub unsafe fn get_mut(&mut self, i: I) -> Option<&mut U32Str>
where I: SliceIndex<[u32], Output = [u32]>,

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).

Source

pub unsafe fn get_unchecked(&self, i: I) -> &U32Str
where I: SliceIndex<[u32], Output = [u32]>,

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.

Source

pub unsafe fn get_unchecked_mut(&mut self, i: I) -> &mut U32Str
where I: SliceIndex<[u32], Output = [u32]>,

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).

Source

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.

Source

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).

Source

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.

Source §

impl U32CStr

Source

pub unsafe fn from_char_ptr_str<'a>(p: *const char) -> &'a Self

Constructs a string reference from a char 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.

§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. In particular, the returned string reference must not be mutated for the duration of lifetime 'a, except inside an UnsafeCell.

§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.

Source

pub unsafe fn from_char_ptr_str_mut<'a>(p: *mut char) -> &'a mut Self

Constructs a mutable string reference from a mutable char 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.

§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_mut.

§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.

Source

pub unsafe fn from_char_ptr<'a>( p: *const char, len: usize, ) -> Result<&'a Self, NulError<u32>>

Constructs a string reference from a char pointer and a length.

The len argument is the number of elements, not the number of bytes, and does not include the nul terminator of the string. Thus, a len of 0 is valid and means that p is a pointer directly to the nul terminator of the string.

§Errors

This will scan the pointer string for an interior nul value and error if one is found before the nul terminator at len offset. To avoid scanning for interior nuls, from_ptr_unchecked may be used instead.

An error is returned if the value at len offset is not a nul terminator.

§Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len + 1 elements.

In addition, the data must meet the safety conditions of std::slice::from_raw_parts. In particular, the returned string reference must not be mutated for the duration of lifetime 'a, except inside an UnsafeCell.

§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.

Source

pub unsafe fn from_char_ptr_mut<'a>( p: *mut char, len: usize, ) -> Result<&'a mut Self, NulError<u32>>

Constructs a mutable string reference from a mutable char pointer and a length.

The len argument is the number of elements, not the number of bytes, and does not include the nul terminator of the string. Thus, a len of 0 is valid and means that p is a pointer directly to the nul terminator of the string.

§Errors

This will scan the pointer string for an interior nul value and error if one is found before the nul terminator at len offset. To avoid scanning for interior nuls, from_ptr_unchecked_mut may be used instead.

An error is returned if the value at len offset is not a nul terminator.

§Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len + 1 elements.

In addition, the data must meet the safety conditions of std::slice::from_raw_parts_mut.

§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.

Source

pub unsafe fn from_char_ptr_truncate<'a>( p: *const char, len: usize, ) -> Result<&'a Self, MissingNulTerminator>

Constructs a string reference 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.

§Errors

If no nul terminator is found after len + 1 elements, an error is returned.

§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. In particular, the returned string reference must not be mutated for the duration of lifetime 'a, except inside an UnsafeCell.

§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.

Source

pub unsafe fn from_char_ptr_truncate_mut<'a>( p: *mut char, len: usize, ) -> Result<&'a mut Self, MissingNulTerminator>

Constructs a mutable string reference from a mutable 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.

§Errors

If no nul terminator is found after len + 1 elements, an error is returned.

§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_mut.

§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.

Source

pub unsafe fn from_char_ptr_unchecked<'a>( p: *const char, len: usize, ) -> &'a Self

Constructs a string reference 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. Thus, a len of 0 is valid and means that p is a pointer directly to the nul terminator of the string.

§Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len + 1 elements, nor that is has a terminating nul value.

In addition, the data must meet the safety conditions of std::slice::from_raw_parts. In particular, the returned string reference must not be mutated for the duration of lifetime 'a, except inside an UnsafeCell.

The interior values of the pointer are not scanned for nul. Any interior nul values or a missing nul terminator at pointer offset len + 1 will result in an invalid string slice.

§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.

Source

pub unsafe fn from_char_ptr_unchecked_mut<'a>( p: *mut char, len: usize, ) -> &'a mut Self

Constructs a mutable string reference from a mutable 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. Thus, a len of 0 is valid and means that p is a pointer directly to the nul terminator of the string.

§Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len + 1 elements, nor that is has a terminating nul value.

In addition, the data must meet the safety conditions of std::slice::from_raw_parts_mut.

The interior values of the pointer are not scanned for nul. Any interior nul values or a missing nul terminator at pointer offset len + 1 will result in an invalid string slice.

§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.

Source

pub fn from_char_slice(slice: &[char]) -> Result<&Self, NulError<u32>>

Constructs a string reference from a char slice with a terminating nul, checking for invalid interior nul values.

The slice must have at least one item, the nul terminator, even for an empty string.

§Errors

If there are nul values in the slice except for the last value, an error is returned.

An error is also returned if the last value of the slice is not a nul terminator.

Source

pub fn from_char_slice_mut( slice: &mut [char], ) -> Result<&mut Self, NulError<u32>>

Constructs a mutable string reference from a mutable char slice with a terminating nul, checking for invalid interior nul values.

The slice must have at least one item, the nul terminator, even for an empty string.

§Errors

If there are nul values in the slice except for the last value, an error is returned.

An error is also returned if the last value of the slice is not a nul terminator.

Source

pub fn from_char_slice_truncate( slice: &[char], ) -> Result<&Self, MissingNulTerminator>

Constructs a string reference from a slice of char values, truncating at the first nul terminator.

The slice will be scanned for nul values. When a nul value is found, it is treated as the terminator for the string, and the string slice will be truncated to that nul.

§Errors

If there are no nul values in the slice, an error is returned.

Source

pub fn from_char_slice_truncate_mut( slice: &mut [char], ) -> Result<&mut Self, MissingNulTerminator>

Constructs a mutable string reference from a mutable slice of char values, truncating at the first nul terminator.

The slice will be scanned for nul values. When a nul value is found, it is treated as the terminator for the string, and the string slice will be truncated to that nul.

§Errors

If there are no nul values in the slice, an error is returned.

Source

pub unsafe fn from_char_slice_unchecked(slice: &[char]) -> &Self

Constructs a string reference from a char slice without checking for a terminating or interior nul values.

§Safety

This function is unsafe because it can lead to invalid C string slice values when the slice is missing a terminating nul value or there are non-terminating interior nul values in the slice. In particular, an empty slice will result in an invalid string slice.

Source

pub unsafe fn from_char_slice_unchecked_mut(slice: &mut [char]) -> &mut Self

Constructs a mutable string reference from a mutable char slice without checking for a terminating or interior nul values.

§Safety

This function is unsafe because it can lead to invalid C string slice values when the slice is missing a terminating nul value or there are non-terminating interior nul values in the slice. In particular, an empty slice will result in an invalid string slice.

Source

pub fn to_os_string(&self) -> OsString

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));

Source

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);

Source

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);

Source

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

Returns an iterator over the chars 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 chars directly. If you would like a lossy iterator over charss 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.

Source

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

Returns a lossy iterator over the chars 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.

Source

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 chars directly. If you would like a lossy indices iterator over charss directly, instead use char_indices_lossy.

The iterator yields tuples. The position is first, the char is second.

Source

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.