Struct widestring::ucstr::U16CStr
source · pub struct U16CStr { /* private fields */ }
Expand description
C-style 16-bit wide string slice for U16CString
.
U16CStr
is to U16CString
as CStr
is to
CString
.
U16CStr
are string slices that do not have a defined encoding. While it is sometimes
assumed that they contain possibly invalid or ill-formed UTF-16 data, they may be used for
any wide encoded string.
§Nul termination
U16CStr
is aware of nul (0
) values. Unless unchecked conversions are used, all
U16CStr
strings end with a nul-terminator in the underlying buffer and contain no
internal nul values. These strings are intended to be used with C FFI functions that
require nul-terminated strings.
Because of the nul termination requirement, multiple classes methods for provided for
construction a U16CStr
under various scenarios. By default, methods such as
from_ptr
and from_slice
return an error if the
input does not terminate with a nul value, or if it contains any interior nul values before
the terminator.
_truncate
methods on the other hand, such as
from_ptr_truncate
and
from_slice_truncate
, construct a slice that terminates with
the first nul value encountered in the string, only returning an error if the slice contains
no nul values at all. Use this to mimic the behavior of C functions such as strlen
when
you don’t know if the input is clean of interior nuls.
Finally, unsafe _unchecked
variants of these methods, such as
from_ptr_unchecked
and
from_slice_unchecked
allow bypassing any checks for nul
values, when the input has already been ensured to have a nul terminator and no interior
nul values.
§Examples
The easiest way to use U16CStr
outside of FFI is with the u16cstr!
macro to convert string literals into nul-terminated UTF-16 string slices at compile time:
use widestring::u16cstr;
let hello = u16cstr!("Hello, world!");
You can also convert any u16
slice directly, as long as it has a nul terminator:
use widestring::{u16cstr, U16CStr};
let sparkle_heart = [0xd83d, 0xdc96, 0x0];
let sparkle_heart = U16CStr::from_slice(&sparkle_heart).unwrap();
assert_eq!(u16cstr!("💖"), sparkle_heart);
// This unpaired UTf-16 surrogate is invalid UTF-16, but is perfectly valid in U16CStr
let malformed_utf16 = [0xd83d, 0x0];
let s = U16CStr::from_slice(&malformed_utf16).unwrap();
assert_eq!(s.len(), 1);
When working with a FFI, it is useful to create a U16CStr
from a pointer:
use widestring::{u16cstr, U16CStr};
let sparkle_heart = [0xd83d, 0xdc96, 0x0];
let s = unsafe {
// Note the string and pointer length does not include the nul terminator
U16CStr::from_ptr(sparkle_heart.as_ptr(), sparkle_heart.len() - 1).unwrap()
};
assert_eq!(u16cstr!("💖"), 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 { U16CStr::from_ptr_str(sparkle_heart.as_ptr()) };
assert_eq!(u16cstr!("💖"), s);
Implementations§
source§impl U16CStr
impl U16CStr
sourcepub const NUL_TERMINATOR: u16 = 0u16
pub const NUL_TERMINATOR: u16 = 0u16
The nul terminator character value.
sourcepub fn new<S: AsRef<U16CStr> + ?Sized>(s: &S) -> &Self
pub fn new<S: AsRef<U16CStr> + ?Sized>(s: &S) -> &Self
Coerces a value into a wide C string slice.
sourcepub unsafe fn from_ptr_str<'a>(p: *const u16) -> &'a Self
pub unsafe fn from_ptr_str<'a>(p: *const u16) -> &'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.
sourcepub unsafe fn from_ptr_str_mut<'a>(p: *mut u16) -> &'a mut Self
pub unsafe fn from_ptr_str_mut<'a>(p: *mut u16) -> &'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.
sourcepub unsafe fn from_ptr<'a>(
p: *const u16,
len: usize,
) -> Result<&'a Self, NulError<u16>>
pub unsafe fn from_ptr<'a>( p: *const u16, len: usize, ) -> Result<&'a Self, NulError<u16>>
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.
sourcepub unsafe fn from_ptr_mut<'a>(
p: *mut u16,
len: usize,
) -> Result<&'a mut Self, NulError<u16>>
pub unsafe fn from_ptr_mut<'a>( p: *mut u16, len: usize, ) -> Result<&'a mut Self, NulError<u16>>
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.
sourcepub unsafe fn from_ptr_truncate<'a>(
p: *const u16,
len: usize,
) -> Result<&'a Self, MissingNulTerminator>
pub unsafe fn from_ptr_truncate<'a>( p: *const u16, 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.
sourcepub unsafe fn from_ptr_truncate_mut<'a>(
p: *mut u16,
len: usize,
) -> Result<&'a mut Self, MissingNulTerminator>
pub unsafe fn from_ptr_truncate_mut<'a>( p: *mut u16, 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.
sourcepub unsafe fn from_ptr_unchecked<'a>(p: *const u16, len: usize) -> &'a Self
pub unsafe fn from_ptr_unchecked<'a>(p: *const u16, 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.
sourcepub unsafe fn from_ptr_unchecked_mut<'a>(
p: *mut u16,
len: usize,
) -> &'a mut Self
pub unsafe fn from_ptr_unchecked_mut<'a>( p: *mut u16, 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.
sourcepub fn from_slice(slice: &[u16]) -> Result<&Self, NulError<u16>>
pub fn from_slice(slice: &[u16]) -> Result<&Self, NulError<u16>>
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.
sourcepub fn from_slice_mut(slice: &mut [u16]) -> Result<&mut Self, NulError<u16>>
pub fn from_slice_mut(slice: &mut [u16]) -> Result<&mut Self, NulError<u16>>
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.
sourcepub fn from_slice_truncate(slice: &[u16]) -> Result<&Self, MissingNulTerminator>
pub fn from_slice_truncate(slice: &[u16]) -> 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.
sourcepub fn from_slice_truncate_mut(
slice: &mut [u16],
) -> Result<&mut Self, MissingNulTerminator>
pub fn from_slice_truncate_mut( slice: &mut [u16], ) -> 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.
sourcepub const unsafe fn from_slice_unchecked(slice: &[u16]) -> &Self
pub const unsafe fn from_slice_unchecked(slice: &[u16]) -> &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.
sourcepub unsafe fn from_slice_unchecked_mut(slice: &mut [u16]) -> &mut Self
pub unsafe fn from_slice_unchecked_mut(slice: &mut [u16]) -> &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.
sourcepub fn to_ucstring(&self) -> U16CString
pub fn to_ucstring(&self) -> U16CString
Copies the string reference to a new owned wide C string.
sourcepub fn to_ustring(&self) -> U16String
pub fn to_ustring(&self) -> U16String
Copies the string reference to a new owned wide string.
The resulting wide string 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);
sourcepub fn as_slice(&self) -> &[u16]
pub fn as_slice(&self) -> &[u16]
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 [u16]
pub unsafe fn as_mut_slice(&mut self) -> &mut [u16]
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 const fn as_slice_with_nul(&self) -> &[u16]
pub const fn as_slice_with_nul(&self) -> &[u16]
Converts to a slice of the underlying elements, including the nul terminator.
sourcepub const fn as_ptr(&self) -> *const u16
pub const fn as_ptr(&self) -> *const u16
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 u16
pub fn as_mut_ptr(&mut self) -> *mut u16
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 u16>
pub fn as_ptr_range(&self) -> Range<*const u16>
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 u16>
pub fn as_mut_ptr_range(&mut self) -> Range<*mut u16>
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 const fn len(&self) -> usize
pub const fn len(&self) -> usize
Returns the length of the string as number of elements (not number of bytes) not including nul terminator.
sourcepub const fn is_empty(&self) -> bool
pub const fn is_empty(&self) -> bool
Returns whether this string contains no data (i.e. is only the nul terminator).
sourcepub fn into_ucstring(self: Box<Self>) -> U16CString
pub fn into_ucstring(self: Box<Self>) -> U16CString
Converts a boxed wide C string slice into an wide C string 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());
sourcepub fn as_ustr(&self) -> &U16Str
pub fn as_ustr(&self) -> &U16Str
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) -> &U16Str
pub fn as_ustr_with_nul(&self) -> &U16Str
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 U16Str
pub unsafe fn as_mut_ustr(&mut self) -> &mut U16Str
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<'_, U16CStr>
pub fn display(&self) -> Display<'_, U16CStr>
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-16, 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::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"
);
sourcepub fn get<I>(&self, i: I) -> Option<&U16Str>
pub fn get<I>(&self, i: I) -> Option<&U16Str>
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 U16Str>
pub unsafe fn get_mut<I>(&mut self, i: I) -> Option<&mut U16Str>
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) -> &U16Str
pub unsafe fn get_unchecked<I>(&self, i: I) -> &U16Str
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 U16Str
pub unsafe fn get_unchecked_mut<I>(&mut self, i: I) -> &mut U16Str
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) -> (&U16Str, &U16Str)
pub fn split_at(&self, mid: usize) -> (&U16Str, &U16Str)
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 U16Str, &mut U16Str)
pub unsafe fn split_at_mut(&mut self, mid: usize) -> (&mut U16Str, &mut U16Str)
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) -> U16CString
pub fn repeat(&self, n: usize) -> U16CString
Creates a new owned string by repeating this string n
times.
§Panics
This function will panic if the capacity would overflow.
source§impl U16CStr
impl U16CStr
sourcepub fn to_os_string(&self) -> OsString
pub fn to_os_string(&self) -> OsString
Copys a string 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));
sourcepub fn to_string(&self) -> Result<String, Utf16Error>
pub fn to_string(&self) -> Result<String, Utf16Error>
Copies the string to a String
if it contains valid UTF-16 data.
This method assumes this string is encoded as UTF-16 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-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);
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-16 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::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);
sourcepub fn chars(&self) -> CharsUtf16<'_> ⓘ
pub fn chars(&self) -> CharsUtf16<'_> ⓘ
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-16. Since it
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.
sourcepub fn chars_lossy(&self) -> CharsLossyUtf16<'_> ⓘ
pub fn chars_lossy(&self) -> CharsLossyUtf16<'_> ⓘ
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-16. Since it
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.
sourcepub fn char_indices(&self) -> CharIndicesUtf16<'_> ⓘ
pub fn char_indices(&self) -> CharIndicesUtf16<'_> ⓘ
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-16. Since it
may consist of invalid UTF-16, the iterator returned by this method is an iterator over
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.
sourcepub fn char_indices_lossy(&self) -> CharIndicesLossyUtf16<'_> ⓘ
pub fn char_indices_lossy(&self) -> CharIndicesLossyUtf16<'_> ⓘ
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.
Trait Implementations§
source§impl AddAssign<&U16CStr> for U16String
impl AddAssign<&U16CStr> for U16String
source§fn add_assign(&mut self, rhs: &U16CStr)
fn add_assign(&mut self, rhs: &U16CStr)
+=
operation. Read moresource§impl AsMut<U16CStr> for U16CString
impl AsMut<U16CStr> for U16CString
source§impl AsRef<U16CStr> for U16CString
impl AsRef<U16CStr> for U16CString
source§impl Borrow<U16CStr> for U16CString
impl Borrow<U16CStr> for U16CString
source§impl BorrowMut<U16CStr> for U16CString
impl BorrowMut<U16CStr> for U16CString
source§fn borrow_mut(&mut self) -> &mut U16CStr
fn borrow_mut(&mut self) -> &mut U16CStr
source§impl<'a> Extend<&'a U16CStr> for U16String
impl<'a> Extend<&'a U16CStr> for U16String
source§fn extend<T: IntoIterator<Item = &'a U16CStr>>(&mut self, iter: T)
fn extend<T: IntoIterator<Item = &'a U16CStr>>(&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<'a> FromIterator<&'a U16CStr> for U16String
impl<'a> FromIterator<&'a U16CStr> for U16String
source§impl PartialEq<&U16CStr> for U16CStr
impl PartialEq<&U16CStr> for U16CStr
source§impl<'a> PartialEq<&'a U16CStr> for U16CString
impl<'a> PartialEq<&'a U16CStr> for U16CString
source§impl PartialEq<&U16CStr> for U16Str
impl PartialEq<&U16CStr> for U16Str
source§impl<'a> PartialEq<&'a U16CStr> for U16String
impl<'a> PartialEq<&'a U16CStr> for U16String
source§impl PartialEq<&U16Str> for U16CStr
impl PartialEq<&U16Str> for U16CStr
source§impl PartialEq<U16CStr> for &U16CStr
impl PartialEq<U16CStr> for &U16CStr
source§impl PartialEq<U16CStr> for &U16Str
impl PartialEq<U16CStr> for &U16Str
source§impl PartialEq<U16CStr> for U16CString
impl PartialEq<U16CStr> for U16CString
source§impl PartialEq<U16CStr> for U16Str
impl PartialEq<U16CStr> for U16Str
source§impl PartialEq<U16CStr> for U16String
impl PartialEq<U16CStr> for U16String
source§impl PartialEq<U16CStr> for Utf16Str
impl PartialEq<U16CStr> for Utf16Str
source§impl PartialEq<U16CStr> for Utf16String
impl PartialEq<U16CStr> for Utf16String
source§impl PartialEq<U16CString> for &U16CStr
impl PartialEq<U16CString> for &U16CStr
source§fn eq(&self, other: &U16CString) -> bool
fn eq(&self, other: &U16CString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<U16CString> for U16CStr
impl PartialEq<U16CString> for U16CStr
source§fn eq(&self, other: &U16CString) -> bool
fn eq(&self, other: &U16CString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<U16Str> for &U16CStr
impl PartialEq<U16Str> for &U16CStr
source§impl PartialEq<U16Str> for U16CStr
impl PartialEq<U16Str> for U16CStr
source§impl PartialEq<U16String> for &U16CStr
impl PartialEq<U16String> for &U16CStr
source§impl PartialEq<U16String> for U16CStr
impl PartialEq<U16String> for U16CStr
source§impl PartialEq<Utf16Str> for U16CStr
impl PartialEq<Utf16Str> for U16CStr
source§impl PartialEq<Utf16String> for U16CStr
impl PartialEq<Utf16String> for U16CStr
source§fn eq(&self, other: &Utf16String) -> bool
fn eq(&self, other: &Utf16String) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq for U16CStr
impl PartialEq for U16CStr
source§impl<'a> PartialOrd<&'a U16CStr> for U16CString
impl<'a> PartialOrd<&'a U16CStr> for U16CString
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 U16CStr> for U16String
impl<'a> PartialOrd<&'a U16CStr> for U16String
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<U16CStr> for U16CString
impl PartialOrd<U16CStr> for U16CString
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<U16CStr> for U16Str
impl PartialOrd<U16CStr> for U16Str
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<U16CStr> for U16String
impl PartialOrd<U16CStr> for U16String
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<U16Str> for U16CStr
impl PartialOrd<U16Str> for U16CStr
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 U16CStr
impl PartialOrd for U16CStr
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