Struct widestring::UCStr [−][src]
pub struct UCStr<C: UChar> { /* fields omitted */ }
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
or U32CStr
or WideCStr
to using
this type directly.
Methods
impl<C: UChar> UCStr<C>
[src]
impl<C: UChar> UCStr<C>
pub fn new<S: AsRef<UCStr<C>> + ?Sized>(s: &S) -> &Self
[src]
pub fn new<S: AsRef<UCStr<C>> + ?Sized>(s: &S) -> &Self
Coerces a value into a UCStr
.
pub unsafe fn from_ptr_str<'a>(p: *const C) -> &'a Self
[src]
pub unsafe fn from_ptr_str<'a>(p: *const C) -> &'a Self
Constructs a UStr
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.
p
must be non-null.
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_with_nul<'a>(p: *const C, len: usize) -> &'a Self
[src]
pub unsafe fn from_ptr_with_nul<'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, 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
elements.
p
must be non-null, even for zero len
.
The interior values of the pointer are not scanned for nul. Any interior nul values will
result in an invalid UCStr
.
Panics
This function panics if p
is null or if a nul value is not found at offset len
of p
.
Only pointers with a nul terminator are valid.
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 fn from_slice_with_nul(slice: &[C]) -> Result<&Self, MissingNulError<C>>
[src]
pub fn from_slice_with_nul(slice: &[C]) -> Result<&Self, MissingNulError<C>>
Constructs a UCStr
from a slice of values that has a 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.
Failure
If there are no no nul values in the slice, an error is returned.
pub unsafe fn from_slice_with_nul_unchecked(slice: &[C]) -> &Self
[src]
pub unsafe fn from_slice_with_nul_unchecked(slice: &[C]) -> &Self
Constructs a UCStr
from a slice of values that has a nul terminator. No
checking for nul values is performed.
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.
pub fn to_ucstring(&self) -> UCString<C>
[src]
pub fn to_ucstring(&self) -> UCString<C>
Copies the wide string to an new owned UString
.
pub fn to_ustring(&self) -> UString<C>
[src]
pub fn to_ustring(&self) -> UString<C>
Copies the wide string to a new owned UString
.
The 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);
pub fn as_slice(&self) -> &[C]
[src]
pub fn as_slice(&self) -> &[C]
Converts to a slice of the wide string.
The slice will not include the nul terminator.
pub fn as_slice_with_nul(&self) -> &[C]
[src]
pub fn as_slice_with_nul(&self) -> &[C]
Converts to a slice of the wide string, including the nul terminator.
pub fn as_ptr(&self) -> *const C
[src]
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.
pub fn len(&self) -> usize
[src]
pub fn len(&self) -> usize
Returns the length of the wide string as number of elements (not number of bytes) not including nul terminator.
pub fn is_empty(&self) -> bool
[src]
pub fn is_empty(&self) -> bool
Returns whether this wide string contains no data (i.e. is only the nul terminator).
pub fn into_ucstring(self: Box<Self>) -> UCString<C>
[src]
pub fn into_ucstring(self: Box<Self>) -> UCString<C>
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::new(v.clone()).unwrap(); let boxed = c_string.into_boxed_ucstr(); assert_eq!(boxed.into_ucstring(), U16CString::new(v).unwrap());
use widestring::U32CString; let v = vec![102u32, 111u32, 111u32]; // "foo" let c_string = U32CString::new(v.clone()).unwrap(); let boxed = c_string.into_boxed_ucstr(); assert_eq!(boxed.into_ucstring(), U32CString::new(v).unwrap());
impl UCStr<u16>
[src]
impl UCStr<u16>
pub fn to_os_string(&self) -> OsString
[src]
pub fn to_os_string(&self) -> OsString
Decodes a wide 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.
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));
pub fn to_string(&self) -> Result<String, FromUtf16Error>
[src]
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::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);
pub fn to_string_lossy(&self) -> String
[src]
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::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);
impl UCStr<u32>
[src]
impl UCStr<u32>
pub unsafe fn from_char_ptr_str<'a>(p: *const char) -> &'a Self
[src]
pub unsafe fn from_char_ptr_str<'a>(p: *const char) -> &'a Self
Constructs a U32Str
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.
p
must be non-null.
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_with_nul<'a>(p: *const char, len: usize) -> &'a Self
[src]
pub unsafe fn from_char_ptr_with_nul<'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, 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
elements.
p
must be non-null, even for zero len
.
The interior values of the pointer are not scanned for nul. Any interior nul values will
result in an invalid U32CStr
.
Panics
This function panics if p
is null or if a nul value is not found at offset len
of p
.
Only pointers with a nul terminator are valid.
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 fn from_char_slice_with_nul(
slice: &[char]
) -> Result<&Self, MissingNulError<u32>>
[src]
pub fn from_char_slice_with_nul(
slice: &[char]
) -> Result<&Self, MissingNulError<u32>>
Constructs a U32CStr
from a slice of char
values that has a 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 U32CStr
slice will be truncated to that nul.
Failure
If there are no no nul values in slice
, an error is returned.
pub unsafe fn from_char_slice_with_nul_unchecked(slice: &[char]) -> &Self
[src]
pub unsafe fn from_char_slice_with_nul_unchecked(slice: &[char]) -> &Self
Constructs a U32CStr
from a slice of char
values that has a nul terminator. No
checking for nul values is performed.
Safety
This function is unsafe because it can lead to invalid U32CStr
values when slice
is missing a terminating nul value or there are non-terminating interior nul values
in the slice.
pub fn to_os_string(&self) -> OsString
[src]
pub fn to_os_string(&self) -> OsString
Decodes a wide string to an owned OsString
.
This makes a string copy of the U32CStr
. Since U32CStr
makes no guarantees that it is
valid UTF-32, there is no guarantee that the resulting OsString
will be valid data. The
OsString
will not have a nul terminator.
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));
pub fn to_string(&self) -> Result<String, FromUtf32Error>
[src]
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::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);
pub fn to_string_lossy(&self) -> String
[src]
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::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);
Trait Implementations
impl<C: Debug + UChar> Debug for UCStr<C>
[src]
impl<C: Debug + UChar> Debug for UCStr<C>
fn fmt(&self, f: &mut Formatter) -> Result
[src]
fn fmt(&self, f: &mut Formatter) -> Result
Formats the value using the given formatter. Read more
impl<C: PartialEq + UChar> PartialEq for UCStr<C>
[src]
impl<C: PartialEq + UChar> PartialEq for UCStr<C>
fn eq(&self, other: &UCStr<C>) -> bool
[src]
fn eq(&self, other: &UCStr<C>) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &UCStr<C>) -> bool
[src]
fn ne(&self, other: &UCStr<C>) -> bool
This method tests for !=
.
impl<C: Eq + UChar> Eq for UCStr<C>
[src]
impl<C: Eq + UChar> Eq for UCStr<C>
impl<C: PartialOrd + UChar> PartialOrd for UCStr<C>
[src]
impl<C: PartialOrd + UChar> PartialOrd for UCStr<C>
fn partial_cmp(&self, other: &UCStr<C>) -> Option<Ordering>
[src]
fn partial_cmp(&self, other: &UCStr<C>) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
fn lt(&self, other: &UCStr<C>) -> bool
[src]
fn lt(&self, other: &UCStr<C>) -> bool
This method tests less than (for self
and other
) and is used by the <
operator. Read more
fn le(&self, other: &UCStr<C>) -> bool
[src]
fn le(&self, other: &UCStr<C>) -> bool
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
fn gt(&self, other: &UCStr<C>) -> bool
[src]
fn gt(&self, other: &UCStr<C>) -> bool
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
fn ge(&self, other: &UCStr<C>) -> bool
[src]
fn ge(&self, other: &UCStr<C>) -> bool
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
impl<C: Ord + UChar> Ord for UCStr<C>
[src]
impl<C: Ord + UChar> Ord for UCStr<C>
fn cmp(&self, other: &UCStr<C>) -> Ordering
[src]
fn cmp(&self, other: &UCStr<C>) -> Ordering
This method returns an Ordering
between self
and other
. Read more
fn max(self, other: Self) -> Self
1.21.0[src]
fn max(self, other: Self) -> Self
Compares and returns the maximum of two values. Read more
fn min(self, other: Self) -> Self
1.21.0[src]
fn min(self, other: Self) -> Self
Compares and returns the minimum of two values. Read more
impl<C: Hash + UChar> Hash for UCStr<C>
[src]
impl<C: Hash + UChar> Hash for UCStr<C>
fn hash<__HC: Hasher>(&self, state: &mut __HC)
[src]
fn hash<__HC: Hasher>(&self, state: &mut __HC)
Feeds this value into the given [Hasher
]. Read more
fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,
1.3.0[src]
fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,
Feeds a slice of this type into the given [Hasher
]. Read more
impl<'a> Default for &'a UCStr<u16>
[src]
impl<'a> Default for &'a UCStr<u16>
impl<'a> Default for &'a UCStr<u32>
[src]
impl<'a> Default for &'a UCStr<u32>
impl<C: UChar> Borrow<UCStr<C>> for UCString<C>
[src]
impl<C: UChar> Borrow<UCStr<C>> for UCString<C>
impl<C: UChar> ToOwned for UCStr<C>
[src]
impl<C: UChar> ToOwned for UCStr<C>
type Owned = UCString<C>
fn to_owned(&self) -> UCString<C>
[src]
fn to_owned(&self) -> UCString<C>
Creates owned data from borrowed data, usually by cloning. Read more
fn clone_into(&self, target: &mut Self::Owned)
[src]
fn clone_into(&self, target: &mut Self::Owned)
🔬 This is a nightly-only experimental API. (toowned_clone_into
)
recently added
Uses borrowed data to replace owned data, usually by cloning. Read more
impl<'a> From<&'a UCStr<u16>> for Cow<'a, UCStr<u16>>
[src]
impl<'a> From<&'a UCStr<u16>> for Cow<'a, UCStr<u16>>
impl<'a> From<&'a UCStr<u32>> for Cow<'a, UCStr<u32>>
[src]
impl<'a> From<&'a UCStr<u32>> for Cow<'a, UCStr<u32>>
impl<C: UChar> AsRef<UCStr<C>> for UCStr<C>
[src]
impl<C: UChar> AsRef<UCStr<C>> for UCStr<C>
impl<C: UChar> AsRef<UCStr<C>> for UCString<C>
[src]
impl<C: UChar> AsRef<UCStr<C>> for UCString<C>
impl<C: UChar> AsRef<[C]> for UCStr<C>
[src]
impl<C: UChar> AsRef<[C]> for UCStr<C>
impl<'a, C: UChar> From<&'a UCStr<C>> for Box<UCStr<C>>
[src]
impl<'a, C: UChar> From<&'a UCStr<C>> for Box<UCStr<C>>