Struct widestring::ucstring::UCString

pub struct UCString<C: UChar> { /* fields omitted */ }

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

impl<C: UChar> UCString<C>

pub fn from_vec(v: impl Into<Vec<C>>) -> Result<Self, ContainsNul<C>>

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();

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

pub fn from_vec_truncate(v: impl Into<Vec<C>>) -> Self

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

pub unsafe fn from_vec_unchecked(v: impl Into<Vec<C>>) -> Self

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.

pub fn from_ustr(s: impl AsRef<UStr<C>>) -> Result<Self, ContainsNul<C>>

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.

pub fn from_ustr_truncate(s: impl AsRef<UStr<C>>) -> Self

Constructs a UCString from anything that can be converted to a UStr, truncating at the first nul terminator.

The string will be truncated at the first nul value in the string.

pub unsafe fn from_ustr_unchecked(s: impl AsRef<UStr<C>>) -> Self

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.

pub unsafe fn from_ptr_str(p: *const C) -> Self

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.

pub unsafe fn from_ptr(p: *const C, len: usize) -> Result<Self, ContainsNul<C>>

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.

pub unsafe fn from_ptr_truncate(p: *const C, len: usize) -> Self

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.

pub unsafe fn from_ptr_unchecked(p: *const C, len: usize) -> Self

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.

pub fn as_ucstr(&self) -> &UCStr<C>

Converts to a UCStr reference.

pub fn as_mut_ucstr(&mut self) -> &mut UCStr<C>

Converts to a mutable UCStr reference.

pub fn into_ustring(self) -> UString<C>

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.

pub fn into_ustring_with_nul(self) -> UString<C>

Converts this string into a UString with a nul terminator.

The resulting vector will contain a nul-terminator and no interior nul values.

pub fn into_vec(self) -> Vec<C>

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.

pub fn into_vec_with_nul(self) -> Vec<C>

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.

pub fn into_raw(self) -> *mut C

Transfers ownership of the string to a C caller.

Safety

The pointer must be returned to Rust and reconstituted using from_raw to be properly deallocated. Specifically, one should not use the standard C free function to deallocate this string. Failure to call from_raw will lead to a memory leak.

pub unsafe fn from_raw(p: *mut C) -> Self

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.

pub fn into_boxed_ucstr(self) -> Box<UCStr<C>>

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());

impl UCString<u16>

pub fn from_str(s: impl AsRef<str>) -> Result<Self, ContainsNul<u16>>

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

pub unsafe fn from_str_unchecked(s: impl AsRef<str>) -> Self

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) };

pub fn from_str_truncate(s: impl AsRef<str>) -> Self

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");

pub fn from_os_str(s: impl AsRef<OsStr>) -> Result<Self, ContainsNul<u16>>

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

pub unsafe fn from_os_str_unchecked(s: impl AsRef<OsStr>) -> Self

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) };

pub fn from_os_str_truncate(s: impl AsRef<OsStr>) -> Self

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");

impl UCString<u32>

pub fn from_chars(v: impl Into<Vec<char>>) -> Result<Self, ContainsNul<u32>>

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

pub fn from_chars_truncate(v: impl Into<Vec<char>>) -> Self

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

pub unsafe fn from_chars_unchecked(v: impl Into<Vec<char>>) -> Self

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.

pub fn from_str(s: impl AsRef<str>) -> Result<Self, ContainsNul<u32>>

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

pub unsafe fn from_str_unchecked(s: impl AsRef<str>) -> Self

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) };

pub fn from_str_truncate(s: impl AsRef<str>) -> Self

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");

pub unsafe fn from_char_ptr_str(p: *const char) -> Self

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.

pub unsafe fn from_char_ptr(
    p: *const char,
    len: usize
) -> Result<Self, ContainsNul<u32>>

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.

pub unsafe fn from_char_ptr_truncate(p: *const char, len: usize) -> Self

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.

pub unsafe fn from_char_ptr_unchecked(p: *const char, len: usize) -> Self

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.

pub fn from_os_str(s: impl AsRef<OsStr>) -> Result<Self, ContainsNul<u32>>

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

pub unsafe fn from_os_str_unchecked(s: impl AsRef<OsStr>) -> Self

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) };

pub fn from_os_str_truncate(s: impl AsRef<OsStr>) -> Self

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

pub fn to_ucstring(&self) -> UCString<C>

Copies the string reference to a new owned UCString.

pub fn to_ustring(&self) -> UString<C>

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

pub fn as_slice(&self) -> &[C]

Converts to a slice of the underlying code units.

The slice will not include the nul terminator.

pub unsafe fn as_mut_slice(&mut self) -> &mut [C]

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

pub fn as_slice_with_nul(&self) -> &[C]

Converts to a slice of the underlying code units, including the nul terminator.

pub fn as_ptr(&self) -> *const C

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.

pub unsafe fn as_mut_ptr(&mut self) -> *mut C

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

pub fn as_ptr_range(&self) -> Range<*const C>

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

pub fn as_mut_ptr_range(&mut self) -> Range<*mut 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++.

pub fn len(&self) -> usize

Returns the length of the string as number of elements (not number of bytes) not including nul terminator.

pub fn is_empty(&self) -> bool

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

pub fn as_ustr(&self) -> &UStr<C>

Returns a UStr reference to this string reference.

The UStr reference will not include the nul-terminator.

pub fn as_ustr_with_nul(&self) -> &UStr<C>

Returns a UStr reference to this string reference.

The UStr reference will include the nul-terminator.

pub unsafe fn as_mut_ustr(&mut self) -> &mut UStr<C>

Returns a mutable UStr reference to this string reference.

The UStr reference 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).

pub fn display(&self) -> Display<'_, C>

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"
);

pub fn to_os_string(&self) -> OsString

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

pub fn to_string(&self) -> Result<String, FromUtf16Error>

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

pub fn to_string_lossy(&self) -> String

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

Returns an iterator over the chars 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 chars directly. If you would like a lossy iterator over charss 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<'_>

Returns a lossy iterator over the chars 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<'_>

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 chars directly. If you would like a lossy indices iterator over charss 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<'_>

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.

pub fn to_os_string(&self) -> OsString

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

pub fn to_string(&self) -> Result<String, FromUtf32Error>

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

pub fn to_string_lossy(&self) -> String

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

Returns an iterator over the chars 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 chars directly. If you would like a lossy iterator over charss 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<'_>

Returns a lossy iterator over the chars 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

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

fn as_mut(&mut self) -> &mut UCStr<C>

Performs the conversion.

impl<C: UChar> AsRef<[C]> for UCString<C>

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

Performs the conversion.

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

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

Performs the conversion.

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

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

Performs the conversion.

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

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

Immutably borrows from an owned value.

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

fn borrow_mut(&mut self) -> &mut UCStr<C>

Mutably borrows from an owned value.

impl<C: Clone + UChar> Clone for UCString<C>

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

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<C: UChar> Default for UCString<C>

fn default() -> Self

Returns the “default value” for a type.

impl<C: UChar> Deref for UCString<C>

type Target = UCStr<C>

The resulting type after dereferencing.

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

Dereferences the value.

impl<C: UChar> DerefMut for UCString<C>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<C: UChar> Drop for UCString<C>

fn drop(&mut self)

Executes the destructor for this type.

impl<C: UChar> Extend<UCString<C>> for UString<C>

fn extend<T: IntoIterator<Item = UCString<C>>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, C: UChar, T: ?Sized + AsRef<UCStr<C>>> From<&'a T> for UCString<C>

fn from(s: &'a T) -> Self

Performs the conversion.

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

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

Performs the conversion.

impl<C: UChar> From<UCString<C>> for Vec<C>

fn from(value: UCString<C>) -> Self

Performs the conversion.

impl<'a, C: UChar> From<UCString<C>> for Cow<'a, UCStr<C>>

fn from(s: UCString<C>) -> Cow<'a, UCStr<C>>

Performs the conversion.

impl<C: UChar> From<UCString<C>> for UString<C>

fn from(s: UCString<C>) -> Self

Performs the conversion.

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

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

Performs the conversion.

impl From<UCString<u16>> for OsString

fn from(s: UCString<u16>) -> OsString

Performs the conversion.

impl From<UCString<u32>> for OsString

fn from(s: UCString<u32>) -> OsString

Performs the conversion.

impl<C: UChar> FromIterator<UCString<C>> for UString<C>

fn from_iter<T: IntoIterator<Item = UCString<C>>>(iter: T) -> Self

Creates a value from an iterator.

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

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

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<C: UChar> Index<RangeFull> for UCString<C>

type Output = UCStr<C>

The returned type after indexing.

fn index(&self, _index: RangeFull) -> &UCStr<C>

Performs the indexing (container[index]) operation.

impl<C: UChar> IndexMut<RangeFull> for UCString<C>

fn index_mut(&mut self, _index: RangeFull) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

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

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<'a, C: UChar> PartialEq<&'a UCStr<C>> for UCString<C>

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<'a, C: UChar> PartialEq<&'a UStr<C>> for UCString<C>

fn eq(&self, other: &&'a UStr<C>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<'a, C: UChar> PartialEq<Cow<'a, UCStr<C>>> for UCString<C>

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<'a, C: UChar> PartialEq<Cow<'a, UStr<C>>> for UCString<C>

fn eq(&self, other: &Cow<'a, UStr<C>>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

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

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

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

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &UCString<C>) -> bool

This method tests for !=.

impl<C: UChar> PartialEq<UCString<C>> for UString<C>

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<C: UChar> PartialEq<UStr<C>> for UCString<C>

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<C: UChar> PartialEq<UString<C>> for UCString<C>

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<'a, C: UChar> PartialOrd<&'a UCStr<C>> for UCString<C>

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<'a, C: UChar> PartialOrd<&'a UStr<C>> for UCString<C>

fn partial_cmp(&self, other: &&'a UStr<C>) -> Option<Ordering>

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<'a, C: UChar> PartialOrd<Cow<'a, UCStr<C>>> for UCString<C>

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<'a, C: UChar> PartialOrd<Cow<'a, UStr<C>>> for UCString<C>

fn partial_cmp(&self, other: &Cow<'a, UStr<C>>) -> Option<Ordering>

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<C: UChar> PartialOrd<UCStr<C>> for UCString<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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

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

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<C: UChar> PartialOrd<UCString<C>> for UString<C>

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<C: UChar> PartialOrd<UStr<C>> for UCString<C>

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<C: UChar> PartialOrd<UString<C>> for UCString<C>

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

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

impl<C: UChar> StructuralEq for UCString<C>

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