Eight basic rules for manipulating BStrings

[02]

Rule 1: Allocate, destroy, and measure BStrings only through the functions and subroutines provided in f90VB.

Those who use their knowledge of BString internals are doomed to an unknowable but horrible fate in future versions.

Rule 2: You may have your way with all the characters of strings you own.

The last character you own is the last character reported by the f90VB function StrLen, not the last non-null character. You may fool functions that believe in null-terminated strings by inserting null characters in BStrings, but do not fool yourself.

Rule 3: You may change the handles to strings you own, but only by following the rules.

In other words, you can change those handles by calling the appropriate f90VB subroutines. The trick with this rule (and rule 2) is determining whether you own the strings.

Rule 4: You do not own any BString passed to you by value.

The only thing you can do with such a string is copy it or pass it to other procedures that will not modify it. The caller owns the string and will dispose of it accordingly.

Rule 5: You own any BString passed to you by reference.

You can modify the contents of the string, or you can replace the original handle with a new one (using the appropriate f90VB subroutines).

Rule 6: You must create any BString passed to you by reference as an out string.

The string parameter you receive is not really a string. It is a placeholder. The caller expects you to assign an allocated string to the unallocated handle, and you had better do it. Otherwise the caller will probably crash when it tries to perform string operations on the uninitialized pointer.

Rule 7: You must create a BString in order to return it.

A string returned by a function is different from any other string. You cannot just take a string parameter passed to you, modify its content, and return it. If you did, you would have two string variables referring to the same memory location, and unpleasant things would happen when different parts of the client code tried to modify them. So if you want to return a modified string, you allocate a copy, modify the copy, and return it.

Rule 8: A null handle is the same as an empty string to a BString.

An empty BString is a pointer to a zero-length string. It has a single null character to the right of the address being pointed to, and a long integer containing zero to the left. A null BString is a null pointer pointing to nothing. There cannot be any characters to the right of nothing, and there cannot be any length to the left of nothing. Nevertheless, a null handle is considered to have a length of zero. When dealing with BStrings, you may get unexpected results if you fail to take this into account. When you receive a string parameter, keep in mind that it may be a null handle. Visual Basic makes all uninitialized strings null handles.