STRINGBUILDER Object

Purpose

The StringBuilder object offers the ability to concatenate many string sections at a very high level of performance. The speed of execution is particularly noticeable when the concatenation is performed in many separate operations over a period of time. If all of the string sections are known and available at once, the use of the BUILD$() function could be a better choice. However, both options offer a very large boost as compared to the standard concatenation operators (& or +). In addition to concatenation, the StringBuilder Class also offers a few additional string operations to assist in building the string.

Remarks

There are two forms of the StringBuilder object, one for ANSI strings, and one for WIDE (Unicode) strings. While they could have been combined into a single hybrid object, that would have added additional overhead not acceptable for PowerBASIC. To concatenate ANSI strings, use the StringBuilderA class and the IStringBuilderA interface. To concatenate WIDE (Unicode) strings, use the StringBuilderW class and the IStringBuilderW interface. The methods and mode of operation are identical for both forms.

If you choose the ANSI form, parameter strings must be ANSI, and result strings will be ANSI. With the WIDE (Unicode) form, parameter strings must be wide, and result strings will be wide. Keep those requirements in mind when reviewing the following method definitions. The Dispatch ID (DispID) for each member method is displayed within angle brackets.

When you create a StringBuilder object, a dynamic string buffer is created to hold the target string. If you know the size of the result string (or even an approximation), it's usually prudent to use the CAPACITY method first, to establish a size at least as large as the final string. If it's not known, PowerBASIC will try to make appropriate decisions for you. Once the object is created, the ADD method is used to append string sections as many times as necessary. Finally, the STRING method is used to extract the combined items.

StringBuilder Methods/Properties

ADD (PowerString$) Method<1>

The PowerString$ parameter is appended to the string held in the StringBuilder object. If the internal string buffer overflows, PowerBASIC will automatically extend it to an appropriate size. If a necessary buffer extension fails, an HResult of E_OUTOFMEMORY (&H8007000E) is returned, and an Object Error (99) is generated.

CAPACITY () AS Long Get Property<2>

The size of the internal string buffer is retrieved and returned to the caller. The size is the number of characters which can be stored without further expansion.

CAPACITY () = Long Set Property<2>

The internal string buffer is expanded to the number of characters specified by the Long Integer. If the new capacity is smaller or equal to the current capacity, no operation is performed.

CHAR (Index&) AS Long Get Property<3>

The numeric character code of the character at the position Index& is retrieved and returned to the caller. Index&=1 for the first character, 2 for the second, etc. If Index& is beyond the current length of the string, the value -1 is returned.

CHAR (Index&) = Long Set Property<3>

The character at the position Index& is changed to that specified by the Long Integer character code. Index&=1 for the first character, 2 for the second, etc.

CLEAR Method<4>

All data in the object is erased.

DELETE (Index&, Count&) Method<5>

Count& characters are removed starting at the position given by Index&. Index&=1 for the first character, 2 for the second, etc.

INSERT (PowerString$, Index&) Method<6>

The PowerString$ parameter is inserted in the string starting at the position given by Index&. Index&=1 for the first character, 2 for the second, etc. If Index& is beyond the current length of the string, no operation is performed.

LEN () AS Long Method<7>

The number of characters currently stored in the object is returned as a long integer value.

STRING AS String Method<8>

The string stored in the object is returned to the caller. This string will contain LEN characters.