pub struct UStr<C: UChar> { /* private fields */ }Expand description
String slice reference for U16String.
UStr is to UString as str is to String.
UStr is not aware of nul values. Strings may or may not be nul-terminated, and may
contain invalid and ill-formed UTF-16 or UTF-32 data. These strings are intended to be used
with FFI functions that directly use string length, where the strings are known to have proper
nul-termination already, or where strings are merely being passed through without modification.
UCStr should be used instead of nul-aware strings are required.
UStr can be converted to many other string types, including OsString and String, making
proper Unicode FFI safe and easy.
Please prefer using the type aliases U16Str or U32Str or WideStr to using this type
directly.
Implementations§
Source§impl<C: UChar> UStr<C>
impl<C: UChar> UStr<C>
Sourcepub unsafe fn from_ptr<'a>(p: *const C, len: usize) -> &'a Self
pub unsafe fn from_ptr<'a>(p: *const C, len: usize) -> &'a Self
Constructs a UStr from a pointer and a length.
The len argument is the number of elements, not the number of bytes.
§Safety
This function is unsafe as there is no guarantee that the given pointer is valid for len
elements.
§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: &[C]) -> &Self
pub fn from_slice(slice: &[C]) -> &Self
Constructs a UStr from a slice of code points.
No checks are performed on the slice.
Sourcepub fn to_ustring(&self) -> UString<C>
pub fn to_ustring(&self) -> UString<C>
Copies the wide string to a new owned UString.
Sourcepub fn as_ptr(&self) -> *const C
pub fn as_ptr(&self) -> *const C
Returns a raw pointer to the wide string.
The pointer is valid only as long as the lifetime of this reference.
Sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the length of the wide string as number of elements (not number of bytes).
Sourcepub fn into_ustring(self: Box<Self>) -> UString<C>
pub fn into_ustring(self: Box<Self>) -> UString<C>
Converts a Box<UStr> into a UString without copying or allocating.
Source§impl UStr<u16>
impl UStr<u16>
Sourcepub fn to_os_string(&self) -> OsString
pub fn to_os_string(&self) -> OsString
Decodes a wide string to an owned OsString.
This makes a string copy of the U16Str. Since U16Str makes no guarantees that it is
valid UTF-16, there is no guarantee that the resulting OsString will be valid data.
§Examples
use widestring::U16String;
use std::ffi::OsString;
let s = "MyString";
// Create a wide string from the string
let wstr = U16String::from_str(s);
// 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, FromUtf16Error>
pub fn to_string(&self) -> Result<String, FromUtf16Error>
Copies the wide string to a String if it contains valid UTF-16 data.
§Failures
Returns an error if the string contains any invalid UTF-16 data.
§Examples
use widestring::U16String;
let s = "MyString";
// Create a wide string from the string
let wstr = U16String::from_str(s);
// 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
Copies the wide string to a String.
Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
§Examples
use widestring::U16String;
let s = "MyString";
// Create a wide string from the string
let wstr = U16String::from_str(s);
// Create a regular string from the wide string
let lossy = wstr.to_string_lossy();
assert_eq!(lossy, s);Source§impl UStr<u32>
impl UStr<u32>
Sourcepub unsafe fn from_char_ptr<'a>(p: *const char, len: usize) -> &'a Self
pub unsafe fn from_char_ptr<'a>(p: *const char, len: usize) -> &'a Self
Constructs a U32Str from a char pointer and a length.
The len argument is the number of char elements, not the number of bytes.
§Safety
This function is unsafe as there is no guarantee that the given pointer is valid for len
elements.
§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_char_slice(slice: &[char]) -> &Self
pub fn from_char_slice(slice: &[char]) -> &Self
Constructs a U32Str from a slice of u32 code points.
No checks are performed on the slice.
Sourcepub fn to_os_string(&self) -> OsString
pub fn to_os_string(&self) -> OsString
Decodes a wide string to an owned OsString.
This makes a string copy of the U32Str. Since U32Str makes no guarantees that it is
valid UTF-32, there is no guarantee that the resulting OsString will be valid data.
§Examples
use widestring::U32String;
use std::ffi::OsString;
let s = "MyString";
// Create a wide string from the string
let wstr = U32String::from_str(s);
// 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, FromUtf32Error>
pub fn to_string(&self) -> Result<String, FromUtf32Error>
Copies the wide string to a String if it contains valid UTF-32 data.
§Failures
Returns an error if the string contains any invalid UTF-32 data.
§Examples
use widestring::U32String;
let s = "MyString";
// Create a wide string from the string
let wstr = U32String::from_str(s);
// 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
Copies the wide string to a String.
Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
§Examples
use widestring::U32String;
let s = "MyString";
// Create a wide string from the string
let wstr = U32String::from_str(s);
// Create a regular string from the wide string
let lossy = wstr.to_string_lossy();
assert_eq!(lossy, s);