Struct widestring::ucstr::UCStr [−][src]
pub struct UCStr<C> { /* fields omitted */ }
Expand description
C-style wide string reference for UCString
.
UCStr
is aware of nul values. Unless unchecked conversions are used, all UCStr
strings end with a nul-terminator in the underlying buffer and contain no internal nul values.
The strings may still contain invalid or ill-formed UTF-16 or UTF-32 data. These strings are
intended to be used with FFI functions such as Windows API that may require nul-terminated
strings.
UCStr
can be converted to and from many other string types, including
UString
, OsString
, and String
, making proper
Unicode FFI safe and easy.
Please prefer using the type aliases U16CStr
, U32CStr
, or WideCStr
to using
UCStr
directly.
Implementations
Constructs a UCStr
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.
Constructs a mutable UCStr
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.
Constructs a UCStr
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.
Constructs a mutable UCStr
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.
pub unsafe fn from_ptr_truncate<'a>(
p: *const C,
len: usize
) -> Result<&'a Self, MissingNulTerminator>
pub unsafe fn from_ptr_truncate<'a>(
p: *const C,
len: usize
) -> Result<&'a Self, MissingNulTerminator>
Constructs a UCStr
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 the string, or by explicit annotation.
pub unsafe fn from_ptr_truncate_mut<'a>(
p: *mut C,
len: usize
) -> Result<&'a mut Self, MissingNulTerminator>
pub unsafe fn from_ptr_truncate_mut<'a>(
p: *mut C,
len: usize
) -> Result<&'a mut Self, MissingNulTerminator>
Constructs a mutable UCStr
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.
Constructs a UCStr
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 UCStr
.
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.
Constructs a mutable UCStr
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 UCStr
.
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.
Constructs a UCStr
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.
Constructs a mutable UCStr
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.
Constructs a UCStr
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 UCStr
slice will be truncated to that nul.
Errors
If there are no nul values in the slice, an error is returned.
Constructs a mutable UCStr
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 UCStr
slice will be truncated to that nul.
Errors
If there are no nul values in the slice, an error is returned.
Constructs a UCStr
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 UCStr
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 UCStr
.
Constructs a mutable UCStr
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 UCStr
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 UCStr
.
Copies the string reference to a new owned UCString
.
Copies the string reference to a new owned UString
.
The resulting UString
will not have a nul terminator
Examples
use widestring::U16CString;
let wcstr = U16CString::from_str("MyString").unwrap();
// Convert U16CString to a U16String
let wstr = wcstr.to_ustring();
// U16CString will have a terminating nul
let wcvec = wcstr.into_vec_with_nul();
assert_eq!(wcvec[wcvec.len()-1], 0);
// The resulting U16String will not have the terminating nul
let wvec = wstr.into_vec();
assert_ne!(wvec[wvec.len()-1], 0);
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);
Converts to a slice of the underlying code units.
The slice will not include the nul terminator.
Converts to a mutable slice of the underlying code units.
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).
Converts to a slice of the underlying code units, including the nul terminator.
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.
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.
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).
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++.
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++.
Returns the length of the string as number of elements (not number of bytes) not including nul terminator.
Returns whether this string contains no data (i.e. is only the nul terminator).
Converts a Box<UCStr>
into a UCString
without copying or
allocating.
Examples
use widestring::U16CString;
let v = vec![102u16, 111u16, 111u16]; // "foo"
let c_string = U16CString::from_vec(v.clone()).unwrap();
let boxed = c_string.into_boxed_ucstr();
assert_eq!(boxed.into_ucstring(), U16CString::from_vec(v).unwrap());
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());
Returns an object that implements Display
for printing strings that
may contain non-Unicode data.
A UCStr
might contain ill-formed UTF encoding. This 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::U16CStr;
// 𝄞mus<invalid>ic<invalid>
let s = U16CStr::from_slice(&[
0xD834, 0xDD1E, 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::U16CStr;
// 𝄞mus<invalid>ic<invalid>
let s = U16CStr::from_slice(&[
0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834, 0x0000,
]).unwrap();
assert_eq!(format!("{:#}", s.display()),
"𝄞music"
);
Decodes a string reference to an owned OsString
.
This makes a string copy of the U16CStr
. Since U16CStr
makes no guarantees that it
is valid UTF-16, 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 (such as
windows) no changes to the string will be made.
Examples
use widestring::U16CString;
use std::ffi::OsString;
let s = "MyString";
// Create a wide string from the string
let wstr = U16CString::from_str(s).unwrap();
// Create an OsString from the wide string
let osstr = wstr.to_os_string();
assert_eq!(osstr, OsString::from(s));
Decodes the string reference to a String
if it contains valid UTF-16 data.
Errors
Returns an error if the string contains any invalid UTF-16 data.
Examples
use widestring::U16CString;
let s = "MyString";
// Create a wide string from the string
let wstr = U16CString::from_str(s).unwrap();
// Create a regular string from the wide string
let s2 = wstr.to_string().unwrap();
assert_eq!(s2, s);
Decodes the string reference to a String
even if it is invalid UTF-16 data.
Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER
.
Examples
use widestring::U16CString;
let s = "MyString";
// Create a wide string from the string
let wstr = U16CString::from_str(s).unwrap();
// Create a regular string from the wide string
let s2 = wstr.to_string_lossy();
assert_eq!(s2, s);
pub fn chars(&self) -> Utf16Chars<'_>ⓘNotable traits for Utf16Chars<'a>impl<'a> Iterator for Utf16Chars<'a> type Item = Result<char, DecodeUtf16Error>;
pub fn chars(&self) -> Utf16Chars<'_>ⓘNotable traits for Utf16Chars<'a>impl<'a> Iterator for Utf16Chars<'a> type Item = Result<char, DecodeUtf16Error>;
impl<'a> Iterator for Utf16Chars<'a> type Item = Result<char, DecodeUtf16Error>;
Returns an iterator over the char
s of a string slice.
As this string slice may consist of invalid UTF-16, the iterator returned by this method
is an iterator over Result<char, DecodeUtf16Error>
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.
pub fn chars_lossy(&self) -> CharsLossy<'_>ⓘNotable traits for CharsLossy<'a>impl<'a> Iterator for CharsLossy<'a> type Item = char;
pub fn chars_lossy(&self) -> CharsLossy<'_>ⓘNotable traits for CharsLossy<'a>impl<'a> Iterator for CharsLossy<'a> type Item = char;
impl<'a> Iterator for CharsLossy<'a> type Item = char;
Returns a lossy iterator over the char
s of a string slice.
As this string slice may consist of invalid UTF-16, the iterator returned by this method
will replace unpaired surrogates 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.
pub fn char_indices(&self) -> Utf16CharIndices<'_>ⓘNotable traits for Utf16CharIndices<'a>impl<'a> Iterator for Utf16CharIndices<'a> type Item = (Result<char, DecodeUtf16Error>, usize);
pub fn char_indices(&self) -> Utf16CharIndices<'_>ⓘNotable traits for Utf16CharIndices<'a>impl<'a> Iterator for Utf16CharIndices<'a> type Item = (Result<char, DecodeUtf16Error>, usize);
impl<'a> Iterator for Utf16CharIndices<'a> type Item = (Result<char, DecodeUtf16Error>, usize);
Returns an iterator over the chars of a string slice, and their positions.
As this string slice may consist of invalid UTF-16, the iterator returned by this method
is an iterator over Result<char, DecodeUtf16Error>
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.
pub fn char_indices_lossy(&self) -> Utf16CharIndicesLossy<'_>ⓘNotable traits for Utf16CharIndicesLossy<'a>impl<'a> Iterator for Utf16CharIndicesLossy<'a> type Item = (char, usize);
pub fn char_indices_lossy(&self) -> Utf16CharIndicesLossy<'_>ⓘNotable traits for Utf16CharIndicesLossy<'a>impl<'a> Iterator for Utf16CharIndicesLossy<'a> type Item = (char, usize);
impl<'a> Iterator for Utf16CharIndicesLossy<'a> type Item = (char, usize);
Returns a lossy iterator over the chars of a string slice, and their positions.
As this string slice may consist of invalid UTF-16, the iterator returned by this method
will replace unpaired surrogates 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.
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.
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.
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.
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.
pub unsafe fn from_char_ptr_truncate<'a>(
p: *const char,
len: usize
) -> Result<&'a Self, MissingNulTerminator>
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.
pub unsafe fn from_char_ptr_truncate_mut<'a>(
p: *mut char,
len: usize
) -> Result<&'a mut Self, MissingNulTerminator>
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.
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 UCStr
.
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.
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 UCStr
.
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.
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.
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.
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 UCStr
slice will be truncated to that nul.
Errors
If there are no nul values in the slice, an error is returned.
pub fn from_char_slice_truncate_mut(
slice: &mut [char]
) -> Result<&mut Self, MissingNulTerminator>
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 UCStr
slice will be truncated to that nul.
Errors
If there are no nul values in the slice, an error is returned.
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 UCStr
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 UCStr
.
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 UCStr
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 UCStr
.
Decodes a string reference to an owned OsString
.
This makes a string copy of this reference. Since UCStr<u32>
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));
Decodes the string reference to a String
if it contains valid UTF-32 data.
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);
Decodes the string reference to a String
even if it is invalid UTF-32 data.
Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER
.
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);
pub fn chars(&self) -> Utf32Chars<'_>ⓘNotable traits for Utf32Chars<'a>impl<'a> Iterator for Utf32Chars<'a> type Item = Result<char, DecodeUtf32Error>;
pub fn chars(&self) -> Utf32Chars<'_>ⓘNotable traits for Utf32Chars<'a>impl<'a> Iterator for Utf32Chars<'a> type Item = Result<char, DecodeUtf32Error>;
impl<'a> Iterator for Utf32Chars<'a> type Item = Result<char, DecodeUtf32Error>;
Returns an iterator over the char
s of a string slice.
As this string slice 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.
pub fn chars_lossy(&self) -> CharsLossy<'_>ⓘNotable traits for CharsLossy<'a>impl<'a> Iterator for CharsLossy<'a> type Item = char;
pub fn chars_lossy(&self) -> CharsLossy<'_>ⓘNotable traits for CharsLossy<'a>impl<'a> Iterator for CharsLossy<'a> type Item = char;
impl<'a> Iterator for CharsLossy<'a> type Item = char;
Returns a lossy iterator over the char
s of a string slice.
As this string slice may consist of invalid UTF-32, the iterator returned by this method
will replace surrogate values or invalid code points 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.
Trait Implementations
Performs the +=
operation. Read more
Mutably borrows from an owned value. Read more
Extends a collection with the contents of an iterator. Read more
extend_one
)Extends a collection with exactly one element.
extend_one
)Reserves capacity in a collection for the given number of additional elements. Read more
Creates a value from an iterator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more