Struct bstr::BString

pub struct BString(_);

System allocated BSTR.

This type can safely move ownership of the string in and out of COM FFI interfaces.

Examples

Create an empty string.

let empty = BString::new();
assert_eq!(empty.len(), 0);

Take ownership of a system allocated BSTR.

let raw = ::std::ptr::null_mut();
unsafe {
    let bstring = BString::from_raw(raw);
    assert_eq!(bstring, "");
}
// Make sure to not use `raw` afterwards!

Surrender ownership of the BSTR for FFI.

let bstring = BString::from("Leaked BString");
let raw = bstring.into_raw();
// `raw` contains system allocated `BSTR` that won't be automatically freed.

Encode anything AsRef<OsStr>.

let bstring = BString::from("Hello BString");
assert_eq!(bstring, "Hello BString");

Encode anything IntoIterator<Item = OLECHAR>. Requires a clonable iterator as it needs to know the length before allocation.

use ::std::ffi::OsStr;
use ::std::os::windows::ffi::OsStrExt;
use ::bstr::IntoBString;

let bstring = OsStr::new("Encoded BString").encode_wide().into_bstring();
assert_eq!(bstring, "Encoded BString");

Collect anything Iterator<Item = OLECHAR>. Allocates an intermediary Vec<OLECHAR> because its length needs to be known beforehand.

use ::std::ffi::OsStr;
use ::std::os::windows::ffi::OsStrExt;

let bstring: BString = OsStr::new("Collected BString").encode_wide().collect();
assert_eq!(bstring, "Collected BString");

Methods

impl BString

fn new() -> BString

Creates an empty string.

Does not allocate system memory.

unsafe fn from_raw(raw: BSTR) -> BString

Takes ownership of a system allocated BSTR.

Null is allowed, as it is semantically equivalent to the empty string.

fn into_raw(self) -> BSTR

Surrenders ownership of the BSTR for FFI.

Methods from Deref<Target=BStr>

fn to_os_string(&self) -> OsString

Clones the string encoded as OsString.

Trait Implementations

impl Borrow<BStr> for BString

fn borrow(&self) -> &BStr

Immutably borrows from an owned value.

impl Clone for BString

fn clone(&self) -> BString

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for BString

fn default() -> BString

Returns the "default value" for a type.

impl Drop for BString

fn drop(&mut self)

A method called when the value goes out of scope.

impl<T: AsRef<OsStr>> From<T> for BString

fn from(s: T) -> BString

Performs the conversion.

impl FromIterator<OLECHAR> for BString

fn from_iter<T: IntoIterator<Item=OLECHAR>>(ty: T) -> BString

Creates a value from an iterator.

impl AsRef<BStr> for BString

fn as_ref(&self) -> &BStr

Performs the conversion.

impl Deref for BString

type Target = BStr

The resulting type after dereferencing

fn deref(&self) -> &BStr

The method called to dereference a value

impl AsRawBStr for BString

fn as_raw(&self) -> BSTR

Returns the raw BSTR for this type.

impl Eq for BString

impl PartialEq<BString> for BString

fn eq(&self, rhs: &BString) -> 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 PartialEq<BStr> for BString

fn eq(&self, rhs: &BStr) -> 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> PartialEq<&'a BStr> for BString

fn eq(&self, rhs: &&'a BStr) -> 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<T: ?Sized + AsRef<OsStr>> PartialEq<T> for BString

fn eq(&self, rhs: &T) -> 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 Debug for BString

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

Formats the value using the given formatter.