Struct UCStr

pub struct UCStr<C: UChar> { /* private fields */ }

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.

Implementations

impl<C: UChar> UCStr<C>

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

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

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>>

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

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>

Copies the wide string to an new owned UString.

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]

Converts to a slice of the wide string.

The slice will not include the nul terminator.

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

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

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

Returns whether this wide string contains no data (i.e. is only the nul terminator).

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>

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>

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

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>

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

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>>

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

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

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>

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

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: UChar> AsRef<[C]> for UCStr<C>

fn as_ref(&self) -> &[C]

Converts this type into a shared reference of the (usually inferred) input type.

impl<C: UChar> AsRef<UCStr<C>> for UCStr<C>

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl<C: UChar> AsRef<UCStr<C>> for UCString<C>

fn as_ref(&self) -> &UCStr<C>

Converts this type into a shared reference of the (usually inferred) input type.

impl<C: UChar> Borrow<UCStr<C>> for UCString<C>

fn borrow(&self) -> &UCStr<C>

Immutably borrows from an owned value.

impl<C: Debug + UChar> Debug for UCStr<C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for &'a UCStr<u16>

fn default() -> Self

Returns the “default value” for a type.

impl<'a> Default for &'a UCStr<u32>

fn default() -> Self

Returns the “default value” for a type.

impl<C: UChar> Default for Box<UCStr<C>>

fn default() -> Box<UCStr<C>>

Returns the “default value” for a type.

impl<'a, C: UChar> From<&'a UCStr<C>> for Box<UCStr<C>>

fn from(s: &'a UCStr<C>) -> Box<UCStr<C>>

Converts to this type from the input type.

impl<'a> From<&'a UCStr<u16>> for Cow<'a, UCStr<u16>>

fn from(s: &'a UCStr<u16>) -> Cow<'a, UCStr<u16>>

Converts to this type from the input type.

impl<'a> From<&'a UCStr<u32>> for Cow<'a, UCStr<u32>>

fn from(s: &'a UCStr<u32>) -> Cow<'a, UCStr<u32>>

Converts to this type from the input type.

impl<C: UChar> From<UCString<C>> for Box<UCStr<C>>

fn from(s: UCString<C>) -> Box<UCStr<C>>

Converts to this type from the input type.

impl<C: Hash + UChar> Hash for UCStr<C>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

impl<C: Ord + UChar> Ord for UCStr<C>

fn cmp(&self, other: &UCStr<C>) -> Ordering

This method returns an Ordering between self and other.

impl<C: PartialEq + UChar> PartialEq for UCStr<C>

fn eq(&self, other: &UCStr<C>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<C: PartialOrd + UChar> PartialOrd for UCStr<C>

fn partial_cmp(&self, other: &UCStr<C>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<C: UChar> ToOwned for UCStr<C>

type Owned = UCString<C>

The resulting type after obtaining ownership.

fn to_owned(&self) -> UCString<C>

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.

impl<C: Eq + UChar> Eq for UCStr<C>

impl<C: UChar> StructuralPartialEq for UCStr<C>