Struct widestring::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 or 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 new(v: impl Into<Vec<C>>) -> Result<Self, NulError<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 nul values.

Failures

This function will return an error if the data contains a nul value. The returned error will contain the 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::new(v).unwrap();

use widestring::U32CString;
let v = vec![84u32, 104u32, 101u32]; // 'T' 'h' 'e'
// Create a wide string from the vector
let wcstr = U32CString::new(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::new(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::new(v);
assert!(res.is_err());
assert_eq!(res.err().unwrap().nul_position(), 1);

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

Constructs a UCString from a nul-terminated container of UTF-16 or UTF-32 data.

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.

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec.

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_with_nul(v).unwrap();

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_with_nul(v).unwrap();

The following example demonstrates errors from missing nul values in a vector.

use widestring::U16CString;
let v = vec![84u16, 104u16, 101u16]; // 'T' 'h' 'e'
// Create a wide string from the vector
let res = U16CString::from_vec_with_nul(v);
assert!(res.is_err());

use widestring::U32CString;
let v = vec![84u32, 104u32, 101u32]; // 'T' 'h' 'e'
// Create a wide string from the vector
let res = U32CString::from_vec_with_nul(v);
assert!(res.is_err());

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

Creates 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 new except that no runtime assertion is made that v contains no nul values. Providing a vector with nul values will result in an invalid UCString.

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

Creates a UCString from a vector that should have a nul terminator, without checking for any nul values.

Safety

This method is equivalent to from_vec_with_nul except that no runtime assertion is made that v contains no nul values. Providing a vector with interior nul values or without a terminating nul value will result in an invalid UCString.

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

Constructs a UCString from anything that can be converted to a UStr.

The string will be scanned for invalid nul values.

Failures

This function will return an error if the data contains a nul value. The returned error will contain a Vec as well as the position of the nul value.

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_u16_str except that no runtime assertion is made that s contains no nul values. Providing a string with nul values will result in an invalid UCString.

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

Constructs a UCString from anything that can be converted to a UStr with a nul terminator.

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

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec.

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

Constructs a UCString from anything that can be converted to a UStr with a nul terminator, without checking the string for any invalid interior nul values.

Safety

This method is equivalent to from_u16_str_with_nul except that no runtime assertion is made that s contains no nul values. Providing a vector with interior nul values or without a terminating nul value 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.

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 fn as_ucstr(&self) -> &UCStr<C>

Converts to a UCStr reference.

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

Converts the wide 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 wide 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 wide 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.

Safety

This should only ever be called with a pointer that was earlier obtained by calling into_raw on a UCString. Additionally, the length of the string will be recalculated from the 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::new(v.clone()).unwrap();
let boxed = c_string.into_boxed_ucstr();
v.push(0);
assert_eq!(&*boxed, U16CStr::from_slice_with_nul(&v).unwrap());

use widestring::{U32CString, U32CStr};

let mut v = vec![102u32, 111u32, 111u32]; // "foo"
let c_string = U32CString::new(v.clone()).unwrap();
let boxed = c_string.into_boxed_ucstr();
v.push(0);
assert_eq!(&*boxed, U32CStr::from_slice_with_nul(&v).unwrap());

impl UCString<u16>

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

Constructs a U16CString from a str.

The string will be scanned for invalid nul values.

Failures

This function will return an error if the data contains a nul value. 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 vector.

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

Constructs a U16CString from a str, without checking for interior nul values.

Safety

This method is equivalent to from_str except that no runtime assertion is made that s contains no nul values. Providing a string with nul values 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_with_nul(
    s: impl AsRef<str>
) -> Result<Self, MissingNulError<u16>>

Constructs a U16CString from a str with a nul terminator.

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

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec<u16>.

Examples

use widestring::U16CString;
let s = "My\u{0}String";
// Create a wide string from the string
let wcstr = U16CString::from_str_with_nul(s).unwrap();
assert_eq!(wcstr.to_string_lossy(), "My");

The following example demonstrates errors from missing nul values in a vector.

use widestring::U16CString;
let s = "MyString";
// Create a wide string from the string
let res = U16CString::from_str_with_nul(s);
assert!(res.is_err());

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

Constructs a U16CString from str str that should have a terminating nul, but without checking for any nul values.

Safety

This method is equivalent to from_str_with_nul except that no runtime assertion is made that s contains no nul values. Providing a vector with interior nul values or without a terminating nul value will result in an invalid U16CString.

Examples

use widestring::U16CString;
let s = "My String\u{0}";
// Create a wide string from the string
let wcstr = unsafe { U16CString::from_str_with_nul_unchecked(s) };
assert_eq!(wcstr.to_string_lossy(), "My String");

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

Constructs a new U16CString copied from a u16 pointer and a length.

The len argument is the number of u16 elements, not the number of bytes.

The string will be scanned for invalid nul values.

Failures

This function will return an error if the data contains a nul value. The returned error will contain a Vec<u16> 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.

Panics

Panics if len is greater than 0 but p is a null pointer.

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

Constructs a new U16CString copied from a u16 pointer and a length.

The len argument is the number of u16 elements, not the number of bytes.

The string will not be checked for invalid nul values.

Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements. In addition, no checking for invalid nul values is performed, so if any elements of p are a nul value, the resulting U16CString will be invalid.

Panics

Panics if len is greater than 0 but p is a null pointer.

pub unsafe fn from_ptr_with_nul(
    p: *const u16,
    len: usize
) -> Result<Self, MissingNulError<u16>>

Constructs a new U16String copied from a u16 pointer and a length.

The len argument is the number of u16 elements, not the number of bytes.

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

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec<u16>.

Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements.

Panics

Panics if len is greater than 0 but p is a null pointer.

pub unsafe fn from_ptr_with_nul_unchecked(p: *const u16, len: usize) -> Self

Constructs a new U16String copied from a u16 pointer and a length.

The len argument is the number of u16 elements, not the number of bytes.

The data should end with a nul terminator, but no checking is done on whether the data actually ends with a nul terminator, or if the data contains any interior nul values.

Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements. In addition, no checking for nul values is performed, so if there data does not end with a nul terminator, or if there are any interior nul values, the resulting U16CString will be invalid.

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, NulError<u16>>

Constructs a U16CString from anything that can be converted to an OsStr.

The string will be scanned for invalid nul values.

Failures

This function will return an error if the data contains a nul value. 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 a vector.

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

Constructs a U16CString from anything that can be converted to an OsStr, without checking for interior nul values.

Safety

This method is equivalent to from_os_str except that no runtime assertion is made that s contains no nul values. Providing a string with nul values 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_with_nul(
    s: impl AsRef<OsStr>
) -> Result<Self, MissingNulError<u16>>

Constructs a U16CString from anything that can be converted to an OsStr with a nul terminator.

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

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec<u16>.

Examples

use widestring::U16CString;
let s = "My\u{0}String";
// Create a wide string from the string
let wcstr = U16CString::from_os_str_with_nul(s).unwrap();
assert_eq!(wcstr.to_string_lossy(), "My");

The following example demonstrates errors from missing nul values in a vector.

use widestring::U16CString;
let s = "MyString";
// Create a wide string from the string
let res = U16CString::from_os_str_with_nul(s);
assert!(res.is_err());

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

Constructs a U16CString from anything that can be converted to an OsStr that should have a terminating nul, but without checking for any nul values.

Safety

This method is equivalent to from_os_str_with_nul except that no runtime assertion is made that s contains no nul values. Providing a vector with interior nul values or without a terminating nul value will result in an invalid U16CString.

Examples

use widestring::U16CString;
let s = "My String\u{0}";
// Create a wide string from the string
let wcstr = unsafe { U16CString::from_os_str_with_nul_unchecked(s) };
assert_eq!(wcstr.to_string_lossy(), "My String");

impl UCString<u32>

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

Constructs a U32CString 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 nul values.

Failures

This function will return an error if the data contains a nul value. 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_with_nul(
    v: impl Into<Vec<char>>
) -> Result<Self, MissingNulError<u32>>

Constructs a U32CString from a nul-terminated container of UTF-32 data.

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.

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec<u32>.

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_with_nul(v).unwrap();

The following example demonstrates errors from missing nul values in a vector.

use widestring::U32CString;
let v: Vec<char> = "Test".chars().collect();
// Create a wide string from the vector
let res = U32CString::from_chars_with_nul(v);
assert!(res.is_err());

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

Creates a U32CString 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 new except that no runtime assertion is made that v contains no nul values. Providing a vector with nul values will result in an invalid U32CString.

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

Creates a U32CString from a vector that should have a nul terminator, without checking for any nul values.

Safety

This method is equivalent to from_vec_with_nul except that no runtime assertion is made that v contains no nul values. Providing a vector with interior nul values or without a terminating nul value will result in an invalid U32CString.

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

Constructs a U32CString from a str.

The string will be scanned for invalid nul values.

Failures

This function will return an error if the data contains a nul value. 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 vector.

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

Constructs a U32CString from a str, without checking for interior nul values.

Safety

This method is equivalent to from_str except that no runtime assertion is made that s contains no nul values. Providing a string with nul values 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_with_nul(
    s: impl AsRef<str>
) -> Result<Self, MissingNulError<u32>>

Constructs a U32CString from a str with a nul terminator.

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

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec<u32>.

Examples

use widestring::U32CString;
let s = "My\u{0}String";
// Create a wide string from the string
let wcstr = U32CString::from_str_with_nul(s).unwrap();
assert_eq!(wcstr.to_string_lossy(), "My");

The following example demonstrates errors from missing nul values in a vector.

use widestring::U32CString;
let s = "MyString";
// Create a wide string from the string
let res = U32CString::from_str_with_nul(s);
assert!(res.is_err());

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

Constructs a U32CString from a str that should have a terminating nul, but without checking for any nul values.

Safety

This method is equivalent to from_str_with_nul except that no runtime assertion is made that s contains no nul values. Providing a vector with interior nul values or without a terminating nul value will result in an invalid U32CString.

Examples

use widestring::U32CString;
let s = "My String\u{0}";
// Create a wide string from the string
let wcstr = unsafe { U32CString::from_str_with_nul_unchecked(s) };
assert_eq!(wcstr.to_string_lossy(), "My String");

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

Constructs a new U32CString copied from a u32 pointer and a length.

The len argument is the number of u32 elements, not the number of bytes.

The string will be scanned for invalid nul values.

Failures

This function will return an error if the data contains a nul value. The returned error will contain a Vec<u32> 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.

Panics

Panics if len is greater than 0 but p is a null pointer.

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

Constructs a new U32CString copied from a u32 pointer and a length.

The len argument is the number of u32 elements, not the number of bytes.

The string will not be checked for invalid nul values.

Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements. In addition, no checking for invalid nul values is performed, so if any elements of p are a nul value, the resulting U16CString will be invalid.

Panics

Panics if len is greater than 0 but p is a null pointer.

pub unsafe fn from_ptr_with_nul(
    p: *const u32,
    len: usize
) -> Result<Self, MissingNulError<u32>>

Constructs a new U32String copied from a u32 pointer and a length.

The len argument is the number of u32 elements, not the number of bytes.

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

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec<u32>.

Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements.

Panics

Panics if len is greater than 0 but p is a null pointer.

pub unsafe fn from_ptr_with_nul_unchecked(p: *const u32, len: usize) -> Self

Constructs a new U32String copied from a u32 pointer and a length.

The len argument is the number of u32 elements, not the number of bytes.

The data should end with a nul terminator, but no checking is done on whether the data actually ends with a nul terminator, or if the data contains any interior nul values.

Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements. In addition, no checking for nul values is performed, so if there data does not end with a nul terminator, or if there are any interior nul values, the resulting U32CString will be invalid.

Panics

Panics if len is greater than 0 but p is a null pointer.

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

Constructs a new U32CString copied from a char pointer and a length.

The len argument is the number of char elements, not the number of bytes.

The string will be scanned for invalid nul values.

Failures

This function will return an error if the data contains a nul value. The returned error will contain a Vec<u32> 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.

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 new U32CString copied from a char pointer and a length.

The len argument is the number of char elements, not the number of bytes.

The string will not be checked for invalid nul values.

Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements. In addition, no checking for invalid nul values is performed, so if any elements of p are a nul value, the resulting U32CString will be invalid.

Panics

Panics if len is greater than 0 but p is a null pointer.

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

Constructs a new U32String copied from a char pointer and a length.

The len argument is the number of char elements, not the number of bytes.

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

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec<u32>.

Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements.

Panics

Panics if len is greater than 0 but p is a null pointer.

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

Constructs a new U32String copied from a char pointer and a length.

The len argument is the number of char elements, not the number of bytes.

The data should end with a nul terminator, but no checking is done on whether the data actually ends with a nul terminator, or if the data contains any interior nul values.

Safety

This function is unsafe as there is no guarantee that the given pointer is valid for len elements. In addition, no checking for nul values is performed, so if there data does not end with a nul terminator, or if there are any interior nul values, the resulting U32CString will be invalid.

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, NulError<u32>>

Constructs a U32CString from anything that can be converted to an OsStr.

The string will be scanned for invalid nul values.

Failures

This function will return an error if the data contains a nul value. 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 vector.

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

Constructs a U32CString from anything that can be converted to an OsStr, without checking for interior nul values.

Safety

This method is equivalent to from_os_str except that no runtime assertion is made that s contains no nul values. Providing a string with nul values 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_with_nul(
    s: impl AsRef<OsStr>
) -> Result<Self, MissingNulError<u32>>

Constructs a U32CString from anything that can be converted to an OsStr with a nul terminator.

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

Failures

This function will return an error if the data does not contain a nul to terminate the string. The returned error will contain the consumed Vec<u16>.

Examples

use widestring::U32CString;
let s = "My\u{0}String";
// Create a wide string from the string
let wcstr = U32CString::from_os_str_with_nul(s).unwrap();
assert_eq!(wcstr.to_string_lossy(), "My");

The following example demonstrates errors from missing nul values in a vector.

use widestring::U32CString;
let s = "MyString";
// Create a wide string from the string
let res = U32CString::from_os_str_with_nul(s);
assert!(res.is_err());

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

Constructs a U32CString from anything that can be converted to an OsStr that should have a terminating nul, but without checking for any nul values.

Safety

This method is equivalent to from_os_str_with_nul except that no runtime assertion is made that s contains no nul values. Providing a vector with interior nul values or without a terminating nul value will result in an invalid U32CString.

Examples

use widestring::U32CString;
let s = "My String\u{0}";
// Create a wide string from the string
let wcstr = unsafe { U32CString::from_os_str_with_nul_unchecked(s) };
assert_eq!(wcstr.to_string_lossy(), "My String");

Methods from Deref<Target = UCStr<C>>

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

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 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> Borrow<UCStr<C>> for UCString<C>

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

Immutably 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: Debug + UChar> Debug for UCString<C>

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

Formats the value using the given formatter.

impl Default for UCString<u16>

fn default() -> Self

Returns the "default value" for a type.

impl Default for UCString<u32>

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> Drop for UCString<C>

fn drop(&mut self)

Executes the destructor for this type.

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

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>>> for UCString<C>

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

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<'a> From<UCString<u16>> for Cow<'a, UCStr<u16>>

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

Performs the conversion.

impl From<UCString<u16>> for OsString

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

Performs the conversion.

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

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

Performs the conversion.

impl From<UCString<u32>> for OsString

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

Performs the conversion.

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> Into<Vec<C>> for UCString<C>

fn into(self) -> Vec<C>

Performs the conversion.

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

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

This method returns an Ordering between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

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

Restrict a value to a certain interval.

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: 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: &UCString<C>) -> bool

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

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

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

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

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

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

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

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

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