Struct widestring::WideString
[−]
[src]
pub struct WideString { /* fields omitted */ }
An owned, mutable "wide" string for FFI that is not nul-aware.
WideString
is not aware of nul values. Strings may or may not be nul-terminated, and may
contain invalid and ill-formed UTF-16 data. These strings are intended to be used with
FFI functions (such as Windows API) that directly use string length, where the strings are
known to have proper nul-termination already, or where strings are merely being passed through
without modification.
WideCString
should be used instead if nul-aware strings are required.
WideString
can be converted to and from many other string types, including OsString
and
String
, making proper Unicode Windows FFI safe and easy.
Examples
The following example constructs a WideString
and shows how to convert a WideString
to a
regular Rust String
.
use widestring::WideString; let v = vec![84u16, 104u16, 101u16]; // 'T' 'h' 'e' // Create a wide string from the vector let wstr = WideString::from_vec(v); // Convert to a rust string! let rust_str = wstr.to_string_lossy(); assert_eq!(rust_str, "The");
Methods
impl WideString
[src]
pub fn new() -> WideString
[src]
Constructs a new empty WideString
.
pub fn from_vec<T: Into<Vec<u16>>>(raw: T) -> WideString
[src]
Constructs a WideString
from a vector of possibly invalid or ill-formed UTF-16 data.
No checks are made on the contents of the vector.
Examples
use widestring::WideString; let v = vec![84u16, 104u16, 101u16]; // 'T' 'h' 'e' // Create a wide string from the vector let wstr = WideString::from_vec(v);
pub fn from_str<S: AsRef<OsStr> + ?Sized>(s: &S) -> WideString
[src]
Encodes a WideString
copy from an OsStr
.
This makes a wide string copy of the OsStr
. Since OsStr
makes no guarantees that it is
valid data, there is no guarantee that the resulting WideString
will be valid UTF-16.
Examples
use widestring::WideString; let s = "MyString"; // Create a wide string from the string let wstr = WideString::from_str(s); assert_eq!(wstr.to_string().unwrap(), s);
pub unsafe fn from_ptr(p: *const u16, len: usize) -> WideString
[src]
Constructs a WideString
from a u16
pointer and a length.
The len
argument is the number of u16
elements, not the number of bytes.
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 fn with_capacity(capacity: usize) -> WideString
[src]
Creates a WideString
with the given capacity.
The string will be able to hold exactly capacity
partial code units without reallocating.
If capacity
is set to 0, the string will not initially allocate.
pub fn capacity(&self) -> usize
[src]
Returns the capacity this WideString
can hold without reallocating.
pub fn clear(&mut self)
[src]
Truncate the WideString
to zero length.
pub fn reserve(&mut self, additional: usize)
[src]
Reserves the capacity for at least additional
more capacity to be inserted in the given
WideString
.
More space may be reserved to avoid frequent allocations.
pub fn reserve_exact(&mut self, additional: usize)
[src]
Reserves the minimum capacity for exactly additional
more capacity to be inserted in the
given WideString
. Does nothing if the capcity is already sufficient.
Note that the allocator may give more space than is requested. Therefore capacity can not be
relied upon to be precisely minimal. Prefer reserve
if future insertions are expected.
pub fn as_wide_str(&self) -> &WideStr
[src]
Converts to a WideStr
reference.
pub fn into_vec(self) -> Vec<u16>
[src]
Converts the wide string into a Vec<u16>
, consuming the string in the process.
pub fn push<T: AsRef<WideStr>>(&mut self, s: T)
[src]
Extends the wide string with the given &WideStr
.
No checks are performed on the strings. It is possible to end up nul values inside the string, and it is up to the caller to determine if that is acceptable.
Examples
use widestring::WideString; let s = "MyString"; let mut wstr = WideString::from_str(s); let cloned = wstr.clone(); // Push the clone to the end, repeating the string twice. wstr.push(cloned); assert_eq!(wstr.to_string().unwrap(), "MyStringMyString");
pub fn push_slice<T: AsRef<[u16]>>(&mut self, s: T)
[src]
Extends the wide string with the given &[u16]
slice.
No checks are performed on the strings. It is possible to end up nul values inside the string, and it is up to the caller to determine if that is acceptable.
Examples
use widestring::WideString; let s = "MyString"; let mut wstr = WideString::from_str(s); let cloned = wstr.clone(); // Push the clone to the end, repeating the string twice. wstr.push_slice(cloned); assert_eq!(wstr.to_string().unwrap(), "MyStringMyString");
pub fn push_str<T: AsRef<OsStr>>(&mut self, s: T)
[src]
Extends the string with the given &OsStr
.
No checks are performed on the strings. It is possible to end up nul values inside the string, and it is up to the caller to determine if that is acceptable.
Examples
use widestring::WideString; let s = "MyString"; let mut wstr = WideString::from_str(s); // Push the original to the end, repeating the string twice. wstr.push_str(s); assert_eq!(wstr.to_string().unwrap(), "MyStringMyString");
pub fn shrink_to_fit(&mut self)
[src]
Shrinks the capacity of the WideString
to match its length.
Examples
use widestring::WideString; let mut s = WideString::from_str("foo"); s.reserve(100); assert!(s.capacity() >= 100); s.shrink_to_fit(); assert_eq!(3, s.capacity());
pub fn into_boxed_wide_str(self) -> Box<WideStr>
[src]
Converts this WideString
into a boxed WideStr
.
Examples
use widestring::{WideString, WideStr}; let s = WideString::from_str("hello"); let b: Box<WideStr> = s.into_boxed_wide_str();
Methods from Deref<Target = WideStr>
pub fn to_os_string(&self) -> OsString
[src]
Decodes a wide string to an owned OsString
.
This makes a string copy of the WideStr
. Since WideStr
makes no guarantees that it is
valid UTF-16, there is no guarantee that the resulting OsString
will be valid data.
Examples
use widestring::WideString; use std::ffi::OsString; let s = "MyString"; // Create a wide string from the string let wstr = WideString::from_str(s); // 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
.
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::WideString; let s = "MyString"; // Create a wide string from the string let wstr = WideString::from_str(s); // 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::WideString; let s = "MyString"; // Create a wide string from the string let wstr = WideString::from_str(s); // Create a regular string from the wide string let lossy = wstr.to_string_lossy(); assert_eq!(lossy, s);
pub fn as_slice(&self) -> &[u16]
[src]
Converts to a slice of the wide string.
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).
pub fn is_empty(&self) -> bool
[src]
Returns whether this wide string contains no data.
Trait Implementations
impl Debug for WideString
[src]
fn fmt(&self, __arg_0: &mut Formatter) -> Result
[src]
Formats the value using the given formatter. Read more
impl Default for WideString
[src]
fn default() -> WideString
[src]
Returns the "default value" for a type. Read more
impl Clone for WideString
[src]
fn clone(&self) -> WideString
[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 WideString
[src]
fn eq(&self, __arg_0: &WideString) -> bool
[src]
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, __arg_0: &WideString) -> bool
[src]
This method tests for !=
.
impl Eq for WideString
[src]
impl PartialOrd for WideString
[src]
fn partial_cmp(&self, __arg_0: &WideString) -> Option<Ordering>
[src]
This method returns an ordering between self
and other
values if one exists. Read more
fn lt(&self, __arg_0: &WideString) -> bool
[src]
This method tests less than (for self
and other
) and is used by the <
operator. Read more
fn le(&self, __arg_0: &WideString) -> 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: &WideString) -> bool
[src]
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
fn ge(&self, __arg_0: &WideString) -> 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 WideString
[src]
fn cmp(&self, __arg_0: &WideString) -> 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 WideString
[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 WideString
[src]
impl<'a> From<WideString> for Cow<'a, WideStr>
[src]
fn from(s: WideString) -> Cow<'a, WideStr>
[src]
Performs the conversion.
impl From<String> for WideString
[src]
fn from(s: String) -> WideString
[src]
Performs the conversion.
impl From<OsString> for WideString
[src]
fn from(s: OsString) -> WideString
[src]
Performs the conversion.
impl From<WideString> for OsString
[src]
fn from(s: WideString) -> OsString
[src]
Performs the conversion.
impl<'a, T: ?Sized + AsRef<WideStr>> From<&'a T> for WideString
[src]
fn from(s: &'a T) -> WideString
[src]
Performs the conversion.
impl Index<RangeFull> for WideString
[src]
type Output = WideStr
The returned type after indexing.
fn index(&self, _index: RangeFull) -> &WideStr
[src]
Performs the indexing (container[index]
) operation.
impl Deref for WideString
[src]
type Target = WideStr
The resulting type after dereferencing.
fn deref(&self) -> &WideStr
[src]
Dereferences the value.
impl PartialEq<WideStr> for WideString
[src]
fn eq(&self, other: &WideStr) -> bool
[src]
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests for !=
.
impl PartialOrd<WideStr> for WideString
[src]
fn partial_cmp(&self, other: &WideStr) -> Option<Ordering>
[src]
This method returns an ordering between self
and other
values if one exists. Read more
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests less than (for self
and other
) and is used by the <
operator. Read more
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
impl<'a> PartialEq<&'a WideStr> for WideString
[src]
fn eq(&self, other: &&'a WideStr) -> bool
[src]
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests for !=
.
impl<'a> PartialOrd<&'a WideStr> for WideString
[src]
fn partial_cmp(&self, other: &&'a WideStr) -> Option<Ordering>
[src]
This method returns an ordering between self
and other
values if one exists. Read more
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests less than (for self
and other
) and is used by the <
operator. Read more
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
impl<'a> PartialEq<Cow<'a, WideStr>> for WideString
[src]
fn eq(&self, other: &Cow<'a, WideStr>) -> bool
[src]
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests for !=
.
impl<'a> PartialOrd<Cow<'a, WideStr>> for WideString
[src]
fn partial_cmp(&self, other: &Cow<'a, WideStr>) -> Option<Ordering>
[src]
This method returns an ordering between self
and other
values if one exists. Read more
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests less than (for self
and other
) and is used by the <
operator. Read more
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
impl Borrow<WideStr> for WideString
[src]
impl AsRef<WideStr> for WideString
[src]
impl AsRef<[u16]> for WideString
[src]
impl From<Box<WideStr>> for WideString
[src]
fn from(boxed: Box<WideStr>) -> WideString
[src]
Performs the conversion.
impl From<WideString> for Box<WideStr>
[src]
fn from(s: WideString) -> Box<WideStr>
[src]
Performs the conversion.
impl From<WideCString> for WideString
[src]
fn from(s: WideCString) -> WideString
[src]
Performs the conversion.