Variable type BSTR

With COM functions usually are used strings of type BSTR. It is Unicode UTF-16 string.

 

The BSTR type supports operator = (assign). You can assign values of intrinsic types (str, int, etc) and other OLE types (VARIANT, DATE, etc). They are automatically converted to BSTR. A BSTR variable itself can be assigned to a str or other variable. Read more about converting to/from UTF-16.

Functions

Here var is a variable of type BSTR. Where the return type is not specified, the function returns var itself.

 


 

var.add([left] right)

 

Joins left and right (var = left + right). Arguments can have any type. If left is omitted, var is used (var = var + right).

 


 

int var.cmp(string [flags])

 

Compares var and string. Returns -1 if var is less than string, 0 if equal, 1 if greater.

 

Here "less" means that var would be above string in a sorted list.

 

QM 2.3.5. Added flags. Flag 1 - case insensitive. Other flags are rarely used and are the same as with VarBstrCmp, documented in the MSDN Library.

 


 

var.alloc(nchar)

 

Allocates memory for a string of nchar characters, and appends null character.

 

If the variable was empty, the function sets the first character in the allocated memory to 0 (QM 2.3.0). The remaining part is not initialized.

 

If the variable was not empty, preserves the string, but no more than nchar characters. The remaining part is not initialized.

 


 

var.free

 

Frees string.

 


 

int var.len

 

Returns string length. It is number of 2-byte characters, not including the terminating null character.

 

To get UTF-16 string length also can be used function len (QM 2.3.0) or wcslen. They calculate string length by searching for the terminating null character, and therefore may return different value if the string contains binary data (null characters in middle).

 

Examples

BSTR a = "string1"
BSTR b.add(a " string2")
 now b is "string1 string2"
str s = a
a = s