The String Builder is a function that lets you create, manipulate and analyse a special collection of string data known as an Object, before returning its contents as a regular string value. When the string object is initialised, you have the option to specify a maximum character capacity. Any part of the object can be modified, but as soon as the object reaches its capacity, some or all of its contents must be deleted to make room for more data.
An object created using the String Builder can be modified far more easily than regular string data, and is not written away until all modifications are complete, reducing the performance overhead associated with repeatedly updating a string-based value.
The BuildString function is especially useful when paired with While loops, ForEach functions, or any other type of flow control statement that may result in a string being modified many times in a short period.
Syntax
The BuildString function has several different methods of operation, one of which is used each time the function is called. The method chosen - otherwise known as the Instruction - is determined by the value passed to the function's first parameter. The basic syntax of the function is as follows:
BuildString( InstructionType, [other parameters determined by instruction] );
InstructionType is a string containing a number. The number determines which of BuildString's instructions are activated by the function call. The following table contains a full list of instruction types:
| Instruction | Description | Required parameters | Optional Parameters | |
|---|---|---|---|---|
| 1 | Initialise | Creates the initial string, with or without a character limit. This must be done before any of the other methods can be carried out. | Capacity | |
| 2 | Append | Adds a new value to the end of the current string. | Value | |
| 3 | Insert | Adds a new value at a specific location inside the current string. | Position, Value | |
| 4 | Remove | Deletes a specified amount of data from the current string, starting from a specific character. | StartPosition, Length | |
| 5 | Replace | Replaces all instances of a particular item found in the current string with a new value. You can optionally restrict the action so it affects a specific sub-set of the string. | OldValue, NewValue | StartPosition, Length |
| 6 | Length | Returns the length of the current string, in characters. | ||
| 7 | Clear | Permanently deletes all existing content from the current string, returning it to the state it was in when first initialised. | ||
| 8 | GetString | Returns the full contents of the current string, allowing you to pass them into a variable or use them as part of another expression. |
With the exception of the GetString method, all BuildString methods return True on successful completion, or False if the method failed.
Capacity is the number of characters you expect your BuildString object to contain. This determines the amount of system memory allocated for storing the object's contents. If the object grows beyond its capacity, additional memory will be allocated automatically. By default, the Capacity of a new BuildString object is 16 characters.
You should try to specify an appropriate Capacity for your BuildString object where possible. Because there is a resource overhead every time the system expands the Capacity it is better to over-estimate, but do not choose a capacity that has no realistic likelihood of being reached, or you will needlessly reserve memory that might be better used elsewhere.
Value is a string containing the data you want to insert or append to the object.
Position is a string containing the zero-based index where you want to insert new data into the BuildString object.
StartPosition is a string containing the zero-based index of the character in your BuildString object from where you want to modify the object's contents. Where StartPosition is optional, 0 will be used by default.
Length is a string containing the number of characters, starting from the character found at StartPosition, that you want your expression to affect.
Any time you provide a StartPosition argument for the BuildString function, you must also provide a Length. If StartPosition is optional and omitted, a Length argument is not required.
Use Case
A company named Firebird Limited is in the process of re-branding itself following a merger with a second company called DK Tools Incorporated. Part of the rebranding process involves changing the part code of all former DK Tools products to a new entry in the Firebird catalogue.
Firebird product codes use the following format:
FBIRD00000
Meanwhile, DK Tools product codes use the following format:
DK0000
DK Tools product details are extracted from the DK product database one row at a time, with each value being temporarily assigned to a matching variable. The product code is then transformed in the following way:
| Step | Description | BuildString contents |
|---|---|---|
| 1 | The BuildString object is initialised. | Empty. |
| 2 | The contents of the product code variable are appended to the BuildString object. | DK0000 |
| 3 | The first two characters of the product code are removed from the BuildString object by specifying a start position of 0 and a length of 2. | 0000 |
| 4 | The literal string "FBIRD0" is inserted at the 0 index of the BuildString object. | FBIRD00000 |
| 5 | To indicate that the modified part code originally referred to a DK Tools product, the literal string "DK" is appended to the BuildString object. | FBIRD00000DK |
| 6 | The contents of the BuildString object are assigned back to the original variable using the GetString method. | No change. |
The process described above is accomplished using a BuildString expression with the following syntax:
BuildString(1);
BuildString(2, ProductID);
BuildString(4, 0, 2);
BuildString(3, 0, "FBIRD0");
BuildString(2, "DK");
ProductID:= BuildString(8);
The modified product code, together with the other values originally taken from the DK Tools database, are then written into a new row in the Firebird database. When each of the product codes has been converted, the original DK Tools catalogue will have been effectively merged with that of Firebird.