Struct widestring::ucstring::UCString [−][src]
pub struct UCString<C: UChar> { /* fields omitted */ }
Expand description
An owned, mutable C-style “wide” string for FFI that is nul-aware and nul-terminated.
UCString
is aware of nul values. Unless unchecked conversions are used, all UCString
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.
UCString
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 U16CString
, U32CString
, or WideCString
to using
this type directly.
Examples
The following example constructs a U16CString
and shows how to convert a U16CString
to a
regular Rust String
.
use widestring::U16CString;
let s = "Test";
// Create a wide string from the rust string
let wstr = U16CString::from_str(s).unwrap();
// Convert back to a rust string
let rust_str = wstr.to_string_lossy();
assert_eq!(rust_str, "Test");
The same example using U32CString
:
use widestring::U32CString;
let s = "Test";
// Create a wide string from the rust string
let wstr = U32CString::from_str(s).unwrap();
// Convert back to a rust string
let rust_str = wstr.to_string_lossy();
assert_eq!(rust_str, "Test");
Implementations
Constructs a UCString
from a container of wide character data.
This method will consume the provided data and use the underlying elements to construct a new string. The data will be scanned for invalid interior nul values.
Errors
This function will return an error if the data contains a nul value that is not the
terminating nul.
The returned error will contain the original Vec
as well as the position of the nul
value.
Examples
use widestring::U16CString;
let v = vec![84u16, 104u16, 101u16]; // 'T' 'h' 'e'
// Create a wide string from the vector
let wcstr = U16CString::from_vec(v).unwrap();
use widestring::U32CString;
let v = vec![84u32, 104u32, 101u32]; // 'T' 'h' 'e'
// Create a wide string from the vector
let wcstr = U32CString::from_vec(v).unwrap();
Empty vectors are valid and will return an empty string with a nul terminator:
use widestring::U16CString;
let wcstr = U16CString::from_vec(vec![]).unwrap();
assert_eq!(wcstr, U16CString::default());
use widestring::U32CString;
let wcstr = U32CString::from_vec(vec![]).unwrap();
assert_eq!(wcstr, U32CString::default());
The following example demonstrates errors from nul values in a vector.
use widestring::U16CString;
let v = vec![84u16, 0u16, 104u16, 101u16]; // 'T' NUL 'h' 'e'
// Create a wide string from the vector
let res = U16CString::from_vec(v);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 1);
use widestring::U32CString;
let v = vec![84u32, 0u32, 104u32, 101u32]; // 'T' NUL 'h' 'e'
// Create a wide string from the vector
let res = U32CString::from_vec(v);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 1);
Constructs a UCString
from a container of wide character data, truncating at the first
nul terminator.
The string will be truncated at the first nul value in the data.
Examples
use widestring::U16CString;
let v = vec![84u16, 104u16, 101u16, 0u16]; // 'T' 'h' 'e' NUL
// Create a wide string from the vector
let wcstr = U16CString::from_vec_truncate(v);
use widestring::U32CString;
let v = vec![84u32, 104u32, 101u32, 0u32]; // 'T' 'h' 'e' NUL
// Create a wide string from the vector
let wcstr = U32CString::from_vec_truncate(v);
Constructs a UCString
from a vector without checking for interior nul values.
A terminating nul value will be appended if the vector does not already have a terminating nul.
Safety
This method is equivalent to from_vec
except that no runtime assertion
is made that v
contains no interior nul values. Providing a vector with any nul values
that are not the last value in the vector will result in an invalid UCString
.
Constructs a UCString
from anything that can be converted to a UStr
.
The string will be scanned for invalid interior nul values.
Errors
This function will return an error if the data contains a nul value that is not the
terminating nul.
The returned error will contain a Vec
as well as the position of the nul value.
Constructs a UCString
from anything that can be converted to a UStr
, without
scanning for invalid nul values.
Safety
This method is equivalent to from_ustr
except that no runtime assertion
is made that v
contains no interior nul values. Providing a string with any nul values
that are not the last value in the vector will result in an invalid UCString
.
Constructs a new UCString
copied from a nul-terminated string pointer.
This will scan for nul values beginning with p
. The first nul value will be used as the
nul terminator for the string, similar to how libc string functions such as strlen
work.
If you wish to avoid copying the string pointer, use UCStr::from_ptr_str
instead.
Safety
This function is unsafe as there is no guarantee that the given pointer is valid or has a nul terminator, and the function could scan past the underlying buffer.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
Panics
This function panics if p
is null.
Caveat
The lifetime for the returned string is inferred from its usage. To prevent accidental misuse, it’s suggested to tie the lifetime to whichever source lifetime is safe in the context, such as by providing a helper function taking the lifetime of a host value for the string, or by explicit annotation.
Constructs a UCString
copied from a pointer and a length, checking for invalid interior
nul values.
The len
argument is the number of elements, not the number of bytes, and does
not include the nul terminator of the string. If len
is 0
, p
is allowed to be a
null pointer.
The resulting string will always be nul-terminated even if the pointer data is not.
Errors
This will scan the pointer string for an interior nul value and error if one is found. To
avoid scanning for interior nuls, from_ptr_unchecked
may be
used instead.
The returned error will contain a Vec
as well as the position of the nul value.
Safety
This function is unsafe as there is no guarantee that the given pointer is valid for len
elements.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
Panics
Panics if len
is greater than 0 but p
is a null pointer.
Constructs a UCString
copied from a pointer and a length, truncating at the first nul
terminator.
The len
argument is the number of elements, not the number of bytes. This will scan
for nul values beginning with p
until offset len
. The first nul value will be used as
the nul terminator for the string, ignoring any remaining values left before len
. If no
nul value is found, the whole string of length len
is used, and a new nul-terminator
will be added to the resulting string. If len
is 0
, p
is allowed to be a null pointer.
Safety
This function is unsafe as there is no guarantee that the given pointer is valid for len
elements.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
Panics
Panics if len
is greater than 0 but p
is a null pointer.
Constructs a UCString
copied from a pointer and a length without checking for any nul
values.
The len
argument is the number of elements, not the number of bytes, and does
not include the nul terminator of the string. If len
is 0
, p
is allowed to be a
null pointer.
The resulting string will always be nul-terminated even if the pointer data is not.
Safety
This function is unsafe as there is no guarantee that the given pointer is valid for len
elements.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
The interior values of the pointer are not scanned for nul. Any interior nul values or
will result in an invalid UCString
.
Panics
Panics if len
is greater than 0 but p
is a null pointer.
Converts to a mutable UCStr
reference.
Converts this string into a UString
without a nul terminator.
The resulting string will not contain a nul-terminator, and will contain no other nul values.
Converts this string into a UString
with a nul terminator.
The resulting vector will contain a nul-terminator and no interior nul values.
Converts the string into a Vec
without a nul terminator, consuming the string in
the process.
The resulting vector will not contain a nul-terminator, and will contain no other nul values.
Converts the string into a Vec
, consuming the string in the process.
The resulting vector will contain a nul-terminator and no interior nul values.
Retakes ownership of a UCString
that was transferred to C.
This should only be used in combination with into_raw
. To construct a
new UCString
from a pointer, use from_ptr_str
.
Safety
This should only ever be called with a pointer that was earlier obtained by calling
into_raw
. Additionally, the length of the string will be recalculated
from the pointer by scanning for the nul-terminator.
Panics
Panics if p
is a null pointer.
Converts this UCString
into a boxed UCStr
.
Examples
use widestring::{U16CString, U16CStr};
let mut v = vec![102u16, 111u16, 111u16]; // "foo"
let c_string = U16CString::from_vec(v.clone()).unwrap();
let boxed = c_string.into_boxed_ucstr();
v.push(0);
assert_eq!(&*boxed, U16CStr::from_slice(&v).unwrap());
use widestring::{U32CString, U32CStr};
let mut v = vec![102u32, 111u32, 111u32]; // "foo"
let c_string = U32CString::from_vec(v.clone()).unwrap();
let boxed = c_string.into_boxed_ucstr();
v.push(0);
assert_eq!(&*boxed, U32CStr::from_slice(&v).unwrap());
Encodes a U16CString
copied from a str
.
The string will be scanned for nul values, which are invalid anywhere except the final character.
The resulting string will always be nul-terminated even if the original string is not.
Errors
This function will return an error if the data contains a nul value anywhere except the
final position.
The returned error will contain a Vec<u16>
as well as the position of the nul value.
Examples
use widestring::U16CString;
let s = "MyString";
// Create a wide string from the string
let wcstr = U16CString::from_str(s).unwrap();
The following example demonstrates errors from nul values in a string.
use widestring::U16CString;
let s = "My\u{0}String";
// Create a wide string from the string
let res = U16CString::from_str(s);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 2);
Encodes a U16CString
copied from a str
, without checking for interior nul values.
The resulting string will always be nul-terminated even if the original string is not.
Safety
This method is equivalent to from_str
except that no runtime assertion
is made that s
contains no interior nul values. Providing a string with nul values that
are not the last character will result in an invalid U16CString
.
Examples
use widestring::U16CString;
let s = "MyString";
// Create a wide string from the string
let wcstr = unsafe { U16CString::from_str_unchecked(s) };
Encodes a U16CString
copied from a str
, truncating at the first nul terminator.
The string will be truncated at the first nul value in the string. The resulting string will always be nul-terminated even if the original string is not.
Examples
use widestring::U16CString;
let s = "My\u{0}String";
// Create a wide string from the string
let wcstr = U16CString::from_str_truncate(s);
assert_eq!(wcstr.to_string_lossy(), "My");
Encodes a U16CString
copied from anything that can be converted to an
OsStr
.
The string will be scanned for nul values, which are invalid anywhere except the final character. The resulting string will always be nul-terminated even if the original string is not.
Note that the encoding of OsStr
is platform-dependent, so on
some platforms this may make an encoding conversions, while on other platforms (such as
windows) no changes to the string will be made.
Errors
This function will return an error if the data contains a nul value anywhere except the
last character.
The returned error will contain a Vec<u16>
as well as the position of the nul value.
Examples
use widestring::U16CString;
let s = "MyString";
// Create a wide string from the string
let wcstr = U16CString::from_os_str(s).unwrap();
The following example demonstrates errors from nul values in the string.
use widestring::U16CString;
let s = "My\u{0}String";
// Create a wide string from the string
let res = U16CString::from_os_str(s);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 2);
Encodes a U16CString
from anything that can be converted to an
OsStr
, without checking for nul values.
The resulting string will always be nul-terminated even if the original string is not.
Note that the encoding of OsStr
is platform-dependent, so on
some platforms this may make an encoding conversions, while on other platforms (such as
windows) no changes to the string will be made.
Safety
This method is equivalent to from_os_str
except that no runtime
assertion is made that s
contains no interior nul values. Providing a string with nul
values anywhere but the last character will result in an invalid U16CString
.
Examples
use widestring::U16CString;
let s = "MyString";
// Create a wide string from the string
let wcstr = unsafe { U16CString::from_os_str_unchecked(s) };
Encodes a U16CString
copied from anything that can be converted to an
OsStr
, truncating at the first nul terminator.
The string will be truncated at the first nul value in the string. The resulting string will always be nul-terminated even if the original string is not.
Note that the encoding of OsStr
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;
let s = "My\u{0}String";
// Create a wide string from the string
let wcstr = U16CString::from_os_str_truncate(s);
assert_eq!(wcstr.to_string_lossy(), "My");
Constructs a U32CString
from a container of character data, checking for invalid nul
values.
This method will consume the provided data and use the underlying elements to construct a new string. The data will be scanned for invalid nul values anywhere except the last character. The resulting string will always be nul-terminated even if the original string is not.
Errors
This function will return an error if the data contains a nul value anywhere except the
last character.
The returned error will contain the Vec<u32>
as well as the position of the nul value.
Examples
use widestring::U32CString;
let v: Vec<char> = "Test".chars().collect();
// Create a wide string from the vector
let wcstr = U32CString::from_chars(v).unwrap();
The following example demonstrates errors from nul values in a vector.
use widestring::U32CString;
let v: Vec<char> = "T\u{0}est".chars().collect();
// Create a wide string from the vector
let res = U32CString::from_chars(v);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 1);
Constructs a U32CString
from a container of character data, truncating at the first nul
value.
This method will consume the provided data and use the underlying elements to construct a new string. The string will be truncated at the first nul value in the string. The resulting string will always be nul-terminated even if the original string is not.
Examples
use widestring::U32CString;
let v: Vec<char> = "Test\u{0}".chars().collect();
// Create a wide string from the vector
let wcstr = U32CString::from_chars_truncate(v);
Constructs a U32CString
from character data without checking for nul values.
A terminating nul value will be appended if the vector does not already have a terminating nul.
Safety
This method is equivalent to from_chars
except that no runtime
assertion is made that v
contains no interior nul values. Providing a vector with nul
values anywhere but the last character will result in an invalid U32CString
.
Encodes a U32CString
copied from a str
, checking for invalid interior nul values.
The string will be scanned for nul values, which are invalid anywhere except the last character. The resulting string will always be nul-terminated even if the original string is not.
Errors
This function will return an error if the data contains a nul value anywhere except the
last character.
The returned error will contain a Vec<u32>
as well as the position of the nul value.
Examples
use widestring::U32CString;
let s = "MyString";
// Create a wide string from the string
let wcstr = U32CString::from_str(s).unwrap();
The following example demonstrates errors from nul values in a string.
use widestring::U32CString;
let s = "My\u{0}String";
// Create a wide string from the string
let res = U32CString::from_str(s);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 2);
Encodes a U32CString
copied from a str
, without checking for nul values.
The resulting string will always be nul-terminated even if the original string is not.
Safety
This method is equivalent to from_str
except that no runtime assertion
is made that s
contains invalid nul values. Providing a string with nul values anywhere
except the last character will result in an invalid U32CString
.
Examples
use widestring::U32CString;
let s = "MyString";
// Create a wide string from the string
let wcstr = unsafe { U32CString::from_str_unchecked(s) };
Encodes a U32CString
copied from a str
, truncating at the first nul terminator.
The string will be truncated at the first nul value in the string. The resulting string will always be nul-terminated even if the original string is not.
Examples
use widestring::U32CString;
let s = "My\u{0}String";
// Create a wide string from the string
let wcstr = U32CString::from_str_truncate(s);
assert_eq!(wcstr.to_string_lossy(), "My");
Constructs a new UCString
copied from a nul-terminated char
string pointer.
This will scan for nul values beginning with p
. The first nul value will be used as the
nul terminator for the string, similar to how libc string functions such as strlen
work.
If you wish to avoid copying the string pointer, use UCStr::from_char_ptr_str
instead.
Safety
This function is unsafe as there is no guarantee that the given pointer is valid or has a nul terminator, and the function could scan past the underlying buffer.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
Panics
This function panics if p
is null.
Caveat
The lifetime for the returned string is inferred from its usage. To prevent accidental misuse, it’s suggested to tie the lifetime to whichever source lifetime is safe in the context, such as by providing a helper function taking the lifetime of a host value for the string, or by explicit annotation.
Constructs a UCString
copied from a char
pointer and a length, checking for invalid
interior nul values.
The len
argument is the number of elements, not the number of bytes, and does
not include the nul terminator of the string. If len
is 0
, p
is allowed to be a
null pointer.
The resulting string will always be nul-terminated even if the pointer data is not.
Errors
This will scan the pointer string for an interior nul value and error if one is found. To
avoid scanning for interior nuls, from_ptr_unchecked
may be
used instead.
The returned error will contain a Vec
as well as the position of the nul value.
Safety
This function is unsafe as there is no guarantee that the given pointer is valid for len
elements.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
Panics
Panics if len
is greater than 0 but p
is a null pointer.
Constructs a UCString
copied from a char
pointer and a length, truncating at the
first nul terminator.
The len
argument is the number of elements, not the number of bytes. This will scan
for nul values beginning with p
until offset len
. The first nul value will be used as
the nul terminator for the string, ignoring any remaining values left before len
. If no
nul value is found, the whole string of length len
is used, and a new nul-terminator
will be added to the resulting string. If len
is 0
, p
is allowed to be a null pointer.
Safety
This function is unsafe as there is no guarantee that the given pointer is valid for len
elements.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
Panics
Panics if len
is greater than 0 but p
is a null pointer.
Constructs a UCString
copied from a char
pointer and a length without checking for
any nul values.
The len
argument is the number of elements, not the number of bytes, and does
not include the nul terminator of the string. If len
is 0
, p
is allowed to be a
null pointer.
The resulting string will always be nul-terminated even if the pointer data is not.
Safety
This function is unsafe as there is no guarantee that the given pointer is valid for len
elements.
In addition, the data must meet the safety conditions of std::slice::from_raw_parts.
The interior values of the pointer are not scanned for nul. Any interior nul values or
will result in an invalid UCString
.
Panics
Panics if len
is greater than 0 but p
is a null pointer.
Encodes a U32CString
copied from anything that can be converted to an
OsStr
, checking for invalid nul values.
The string will be scanned for nul values, which are invlaid anywhere except the last character. The resulting string will always be nul-terminated even if the string is not.
Note that the encoding of OsStr
is platform-dependent, so on
some platforms this may make an encoding conversions, while on other platforms no changes to
the string will be made.
Errors
This function will return an error if the data contains a nul value anywhere except the
last character.
The returned error will contain a Vec<u16>
as well as the position of the nul value.
Examples
use widestring::U32CString;
let s = "MyString";
// Create a wide string from the string
let wcstr = U32CString::from_os_str(s).unwrap();
The following example demonstrates errors from nul values in a string.
use widestring::U32CString;
let s = "My\u{0}String";
// Create a wide string from the string
let res = U32CString::from_os_str(s);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 2);
Encodes a U32CString
copied from anything that can be converted to an
OsStr
, without checking for nul values.
The resulting string will always be nul-terminated even if the string is not.
Note that the encoding of OsStr
is platform-dependent, so on
some platforms this may make an encoding conversions, while on other platforms no changes to
the string will be made.
Safety
This method is equivalent to from_os_str
except that no runtime
assertion is made that s
contains invalid nul values. Providing a string with nul values
anywhere except the last character will result in an invalid U32CString
.
Examples
use widestring::U32CString;
let s = "MyString";
// Create a wide string from the string
let wcstr = unsafe { U32CString::from_os_str_unchecked(s) };
Encodes a U32CString
copied from anything that can be converted to an
OsStr
, truncating at the first nul terminator.
The string will be truncated at the first nul value in the string. The resulting string will always be nul-terminated even if the string is not.
Note that the encoding of OsStr
is platform-dependent, so on
some platforms this may make an encoding conversions, while on other platforms no changes to
the string will be made.
Examples
use widestring::U32CString;
let s = "My\u{0}String";
// Create a wide string from the string
let wcstr = U32CString::from_os_str_truncate(s);
assert_eq!(wcstr.to_string_lossy(), "My");
Methods from Deref<Target = UCStr<C>>
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).
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.
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
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
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
Auto Trait Implementations
impl<C> RefUnwindSafe for UCString<C> where
C: RefUnwindSafe,
impl<C> UnwindSafe for UCString<C> where
C: UnwindSafe,
Blanket Implementations
Mutably borrows from an owned value. Read more