Struct widestring::WideCString
[−]
[src]
pub struct WideCString { /* fields omitted */ }
An owned, mutable C-style "wide" string for FFI that is nul-aware and nul-terminated.
WideCString
is aware of nul values. Unless unchecked conversions are used, all WideCString
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 data. These strings are intended to
be used with FFI functions such as Windows API that may require nul-terminated strings.
WideCString
can be converted to and from many other string types, including WideString
,
OsString
, and String
, making proper Unicode Windows FFI safe and easy.
Examples
The following example constructs a WideCString
and shows how to convert a WideCString
to a
regular Rust String
.
use widestring::WideCString; let v = vec![84u16, 104u16, 101u16]; // 'T' 'h' 'e' // Create a wide string from the vector let wstr = WideCString::new(v).unwrap(); // Convert to a rust string! let rust_str = wstr.to_string_lossy(); assert_eq!(rust_str, "The");
Methods
impl WideCString
[src]
pub fn new<T: Into<Vec<u16>>>(v: T) -> Result<WideCString, NulError>
[src]
Constructs a WideCString
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<u16>
as well as the position of the nul value.
Examples
use widestring::WideCString; let v = vec![84u16, 104u16, 101u16]; // 'T' 'h' 'e' // Create a wide string from the vector let wcstr = WideCString::new(v).unwrap();
The following example demonstrates errors from nul values in a vector.
use widestring::WideCString; let v = vec![84u16, 0u16, 104u16, 101u16]; // 'T' NUL 'h' 'e' // Create a wide string from the vector let res = WideCString::new(v); assert!(res.is_err()); assert_eq!(res.err().unwrap().nul_position(), 1);
pub fn from_vec_with_nul<T: Into<Vec<u16>>>(
v: T
) -> Result<WideCString, MissingNulError>
[src]
v: T
) -> Result<WideCString, MissingNulError>
Constructs a WideCString
from a nul-terminated container of UTF-16 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<u16>
.
Examples
use widestring::WideCString; let v = vec![84u16, 104u16, 101u16, 0u16]; // 'T' 'h' 'e' NUL // Create a wide string from the vector let wcstr = WideCString::from_vec_with_nul(v).unwrap();
The following example demonstrates errors from missing nul values in a vector.
use widestring::WideCString; let v = vec![84u16, 104u16, 101u16]; // 'T' 'h' 'e' // Create a wide string from the vector let res = WideCString::from_vec_with_nul(v); assert!(res.is_err());
pub unsafe fn from_vec_unchecked<T: Into<Vec<u16>>>(v: T) -> WideCString
[src]
Creates a WideCString
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
WideCString
.
pub unsafe fn from_vec_with_nul_unchecked<T: Into<Vec<u16>>>(
v: T
) -> WideCString
[src]
v: T
) -> WideCString
Creates a WideCString
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 WideCString
.
pub fn from_str<T: AsRef<OsStr>>(s: T) -> Result<WideCString, NulError>
[src]
Constructs a WideCString
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::WideCString; let s = "MyString"; // Create a wide string from the string let wcstr = WideCString::from_str(s).unwrap();
The following example demonstrates errors from nul values in a vector.
use widestring::WideCString; let s = "My\u{0}String"; // Create a wide string from the string let res = WideCString::from_str(s); assert!(res.is_err()); assert_eq!(res.err().unwrap().nul_position(), 2);
pub unsafe fn from_str_unchecked<T: AsRef<OsStr>>(s: T) -> WideCString
[src]
Constructs a WideCString
from anything that can be converted to an OsStr
, 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
WideCString
.
Examples
use widestring::WideCString; let s = "MyString"; // Create a wide string from the string let wcstr = unsafe { WideCString::from_str_unchecked(s) };
pub fn from_str_with_nul<T: AsRef<OsStr>>(
s: T
) -> Result<WideCString, MissingNulError>
[src]
s: T
) -> Result<WideCString, MissingNulError>
Constructs a WideCString
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::WideCString; let s = "My\u{0}String"; // Create a wide string from the string let wcstr = WideCString::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::WideCString; let s = "MyString"; // Create a wide string from the string let res = WideCString::from_str_with_nul(s); assert!(res.is_err());
pub unsafe fn from_str_with_nul_unchecked<T: AsRef<OsStr>>(s: T) -> WideCString
[src]
Constructs a WideCString
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_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 WideCString
.
Examples
use widestring::WideCString; let s = "My String\u{0}"; // Create a wide string from the string let wcstr = unsafe { WideCString::from_str_with_nul_unchecked(s) }; assert_eq!(wcstr.to_string_lossy(), "My String");
pub fn from_wide_str<T: AsRef<WideStr>>(s: T) -> Result<WideCString, NulError>
[src]
Constructs a WideCString
from anything that can be converted to a WideStr
.
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.
pub unsafe fn from_wide_str_unchecked<T: AsRef<WideStr>>(s: T) -> WideCString
[src]
Constructs a WideCString
from anything that can be converted to a WideStr
, without
scanning for invalid nul values.
Safety
This method is equivalent to from_wide_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
WideCString
.
pub fn from_wide_str_with_nul<T: AsRef<WideStr>>(
s: T
) -> Result<WideCString, MissingNulError>
[src]
s: T
) -> Result<WideCString, MissingNulError>
Constructs a WideCString
from anything that can be converted to a WideStr
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>
.
pub unsafe fn from_wide_str_with_nul_unchecked<T: AsRef<WideStr>>(
s: T
) -> WideCString
[src]
s: T
) -> WideCString
Constructs a WideCString
from anything that can be converted to a WideStr
with a nul
terminator, without checking the string for any invalid interior nul values.
Safety
This method is equivalent to from_wide_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 WideCString
.
pub unsafe fn from_ptr_str(p: *const u16) -> WideCString
[src]
Constructs a new WideCString
copied from a u16
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(
p: *const u16,
len: usize
) -> Result<WideCString, NulError>
[src]
p: *const u16,
len: usize
) -> Result<WideCString, NulError>
Constructs a new WideCString
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) -> WideCString
[src]
Constructs a new WideCString
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 WideCString
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<WideCString, MissingNulError>
[src]
p: *const u16,
len: usize
) -> Result<WideCString, MissingNulError>
Constructs a new WideString
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
) -> WideCString
[src]
p: *const u16,
len: usize
) -> WideCString
Constructs a new WideString
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
WideCString
will be invalid.
Panics
Panics if len
is greater than 0 but p
is a null pointer.
pub fn as_wide_c_str(&self) -> &WideCStr
[src]
Converts to a WideCStr
reference.
pub fn into_vec(self) -> Vec<u16>
[src]
Converts the wide string into a Vec<u16>
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<u16>
[src]
Converts the wide string into a Vec<u16>
, 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 u16
[src]
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 u16) -> WideCString
[src]
Retakes ownership of a WideCString
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 WideCString
. Additionally, the length of the string will be recalculated
from the pointer.
pub fn into_boxed_wide_c_str(self) -> Box<WideCStr>
[src]
Converts this WideCString
into a boxed WideCStr
.
Examples
use widestring::{WideCString, WideCStr}; let mut v = vec![102u16, 111u16, 111u16]; // "foo" let c_string = WideCString::new(v.clone()).unwrap(); let boxed = c_string.into_boxed_wide_c_str(); v.push(0); assert_eq!(&*boxed, WideCStr::from_slice_with_nul(&v).unwrap());
Methods from Deref<Target = WideCStr>
pub fn to_wide_c_string(&self) -> WideCString
[src]
Copies the wide string to an new owned WideString
.
pub fn to_os_string(&self) -> OsString
[src]
Decodes a wide string to an owned OsString
.
This makes a string copy of the WideCStr
. Since WideCStr
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::WideCString; use std::ffi::OsString; let s = "MyString"; // Create a wide string from the string let wstr = WideCString::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_wide_string(&self) -> WideString
[src]
Copies the wide string to a new owned WideString
.
The WideString
will not have a nul terminator.
pub fn to_string(&self) -> Result<String, FromUtf16Error>
[src]
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::WideCString; let s = "MyString"; // Create a wide string from the string let wstr = WideCString::from_str(s).unwrap(); // Create a regular string from the wide string let s2 = wstr.to_string().unwrap(); assert_eq!(s2, s);
pub fn to_string_lossy(&self) -> String
[src]
Copies the wide string to a String
.
Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
Examples
use widestring::WideCString; let s = "MyString"; // Create a wide string from the string let wstr = WideCString::from_str(s).unwrap(); // Create a regular string from the wide string let s2 = wstr.to_string_lossy(); assert_eq!(s2, s);
pub fn as_slice(&self) -> &[u16]
[src]
Converts to a slice of the wide string.
The slice will not include the nul terminator.
pub fn as_slice_with_nul(&self) -> &[u16]
[src]
Converts to a slice of the wide string, including the nul terminator.
pub fn as_ptr(&self) -> *const u16
[src]
Returns a raw pointer to the wide string.
The pointer is valid only as long as the lifetime of this reference.
pub fn len(&self) -> usize
[src]
Returns the length of the wide string as number of UTF-16 code units (not code points and not number of bytes) not including nul terminator.
pub fn is_empty(&self) -> bool
[src]
Returns whether this wide string contains no data (i.e. is only the nul terminator).
Trait Implementations
impl Debug for WideCString
[src]
fn fmt(&self, __arg_0: &mut Formatter) -> Result
[src]
Formats the value using the given formatter. Read more
impl Clone for WideCString
[src]
fn clone(&self) -> WideCString
[src]
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0[src]
Performs copy-assignment from source
. Read more
impl PartialEq for WideCString
[src]
fn eq(&self, __arg_0: &WideCString) -> bool
[src]
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, __arg_0: &WideCString) -> bool
[src]
This method tests for !=
.
impl Eq for WideCString
[src]
impl PartialOrd for WideCString
[src]
fn partial_cmp(&self, __arg_0: &WideCString) -> Option<Ordering>
[src]
This method returns an ordering between self
and other
values if one exists. Read more
fn lt(&self, __arg_0: &WideCString) -> bool
[src]
This method tests less than (for self
and other
) and is used by the <
operator. Read more
fn le(&self, __arg_0: &WideCString) -> bool
[src]
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
fn gt(&self, __arg_0: &WideCString) -> bool
[src]
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
fn ge(&self, __arg_0: &WideCString) -> bool
[src]
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
impl Ord for WideCString
[src]
fn cmp(&self, __arg_0: &WideCString) -> Ordering
[src]
This method returns an Ordering
between self
and other
. Read more
fn max(self, other: Self) -> Self
1.21.0[src]
Compares and returns the maximum of two values. Read more
fn min(self, other: Self) -> Self
1.21.0[src]
Compares and returns the minimum of two values. Read more
impl Hash for WideCString
[src]
fn hash<__H: Hasher>(&self, __arg_0: &mut __H)
[src]
Feeds this value into the given [Hasher
]. Read more
fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,
1.3.0[src]
H: Hasher,
Feeds a slice of this type into the given [Hasher
]. Read more
impl Into<Vec<u16>> for WideCString
[src]
impl<'a> From<WideCString> for Cow<'a, WideCStr>
[src]
fn from(s: WideCString) -> Cow<'a, WideCStr>
[src]
Performs the conversion.
impl From<WideCString> for OsString
[src]
fn from(s: WideCString) -> OsString
[src]
Performs the conversion.
impl From<WideCString> for WideString
[src]
fn from(s: WideCString) -> WideString
[src]
Performs the conversion.
impl<'a, T: ?Sized + AsRef<WideCStr>> From<&'a T> for WideCString
[src]
fn from(s: &'a T) -> WideCString
[src]
Performs the conversion.
impl Index<RangeFull> for WideCString
[src]
type Output = WideCStr
The returned type after indexing.
fn index(&self, _index: RangeFull) -> &WideCStr
[src]
Performs the indexing (container[index]
) operation.
impl Deref for WideCString
[src]
type Target = WideCStr
The resulting type after dereferencing.
fn deref(&self) -> &WideCStr
[src]
Dereferences the value.
impl Default for WideCString
[src]
fn default() -> WideCString
[src]
Returns the "default value" for a type. Read more
impl Drop for WideCString
[src]
impl Borrow<WideCStr> for WideCString
[src]
impl AsRef<WideCStr> for WideCString
[src]
impl AsRef<[u16]> for WideCString
[src]
impl From<Box<WideCStr>> for WideCString
[src]
fn from(s: Box<WideCStr>) -> WideCString
[src]
Performs the conversion.
impl From<WideCString> for Box<WideCStr>
[src]
fn from(s: WideCString) -> Box<WideCStr>
[src]
Performs the conversion.