The subject of strings can be quite confusing, but this confusion tends to disappear with some careful attention to detail (as is usually the case). The problem stems from the tendency of many programmers to think of a string as an array of characters.

Indeed, the Visual Basic documentation tends to support this erroneous viewpoint at times. According to the VB documentation, a string is

It seems to me that Microsoft is trying to say that the underlying set for the VB String data type is the set of finite-length sequences of characters. For Visual Basic, all characters are represented by two-byte Unicode integers. For instance, the ASCII representation for the character h is &H68 so the Unicode representation is &H0068, appearing in memory as 68 00.

Thus, the "string" help is represented as

Note, however, that because words are written with their bytes reversed in memory, the "string" help appears in memory as

This is fine, but it is definitely not how we should think of strings in VB programming. To avoid any possibility of ambiguity, we will refer to this type of object as a Unicode character array which is, after all, precisely what it is! This also helps distinguish it from an ANSI character array, that is, an array of characters represented using single-byte ANSI character codes.

Here is the key to understanding VB strings. When we write the VB code

we are not defining a Unicode character array per se. We are defining a member of a data type called BSTR, which is short for Basic String. A BSTR is, in fact, a pointer to a null-terminated Unicode character array that is preceeded by a 4-byte length field. We had better elaborate on this.

Actually, the VB string data type defined by

underwent a radical change between versions 3 and 4 of Visual Basic, due in part to an effort to make the type more compatible with the Win32 operating system.

Just for comparison (and to show that we are more fortunate now), Figure 1 shows the format for the VB string data type under Visual Basic 3, called an HLSTR (high-level string).

The rather complex HLSTR format starts with a pointer to a string descriptor, which contains the 2-byte length of the string along with another pointer to the character array, which is in ANSI format (one byte per character).

With respect to the Win32 API, this string format is a nightmare. Beginning with Visual Basic 4, the VB string data type changed. The new data type, called a BSTR, is shown in Figure 2.

This data type is actually defined in the OLE 2.0 specifications, that is, it is part of Microsoft's ActiveX specification.

There are several important things to note about the BSTR data type:

• The BSTR is the actual pointer variable. It has size 32 bits, like all pointers, and points to a Unicode character array. Thus, a Unicode character array and a BSTR are not the same thing. It is correct to refer to a BSTR as a string (or VB string) but, unfortunately, the Unicode character array is also often called a string! Hence, we will not refer to a BSTR simply as a string-we will refer to it by its unequivocal name-BSTR.
• The Unicode character array that is pointed to by a BSTR must be preceded by a 4-byte length field and terminated by a single null two-byte character (ANSI = 0).
• There may be additional null characters anywhere within the Unicode character array, so we cannot rely on a null character to signal the end of the character array. This is why the length field is vital.
• Again, the pointer points to the beginning of the character array, not to the 4-byte length field that preceeds the array. This is critical to interpreting a BSTR as a VC++-style string, which is often done when programming the Win32 API from Visual Basic.
• The length field contains the number of bytes (not the number of characters) in the character array, excluding the terminating null bytes. Since the array is Unicode, the character count is one-half the byte count.

We should emphasize that an embedded null Unicode character is a 16-bit 0, not an 8-bit 0. Watch out for this when testing for null characters in Unicode arrays.

Note that it is common practice to speak of "the BSTR help" or to say that a BSTR may contain embedded null characters when what is really being referred to is the character array pointed to by the BSTR.

Because a BSTR may contain embedded null characters, the terminating null is not of much use, at least as far as VB is concerned. However, its presence is extremely important for Win32. The reason is that the Unicode version of a Win32 string (denoted by LPWSTR) is defined as a pointer to a null-terminated Unicode character array which is not allowed to contain embedded null characters.

This makes it clear why BSTR's are null terminated. A BSTR with no embedded nulls is also an LPWSTR. We will not discuss VC++ strings in this article. (For more on VC++ strings, please see my book Win32 API Programming with Visual Basic.)

Let us emphasize that code such as

means that str is the name of a BSTR, not a Unicode character array. In other words, str is the name of the variable that holds the address xxxx, as shown in Figure 2.

Here is a brief experiment we can do to test the fact that a VB string is a pointer to a character array and not a character array. Consider the following code, which defines a structure whose members are strings:

The output from this code is

In the case of the string variable s, the Len function reports the length of the character array, in this case there are 7 characters in the character array 'testing'. However, in the case of the structure variable uTest, the Len function actually reports the length of the structure (in bytes). The return value of 8 clearly indicates that each of the two BSTRs has length 4. This is because a BSTR is a pointer!

The functions VarPtr and StrPtr are not documented by Microsoft, but they can be very useful in understanding the structure of BSTRs.

If var is a variable, then

is the address of that variable, returned as a long. If str is a BSTR variable then

is contents of the BSTR! This contents is the address of the Unicode character array pointed to by the BSTR.

Let us verify these statements. Figure 3 shows a BSTR

The code for this figure is simply

Note that the variable str is located at address aaaa and the character array begins at address xxxx, which is the contents of the pointer variable str.

To see that

just run the following code:

The output is

This shows that the character array in a BSTR is indeed in Unicode format and that the length field does indeed hold the byte count and not the character count.

Finally, we note that you can also simulate StrPtr using VarPtr as follows:

This code copies the contents of the BSTR pointer, which is the value of StrPtr to a long variable lng.