UIZE JavaScript Framework

MODULES Uize.Str.Builder

1. Introduction

The Uize.Str.Builder module implements an object to facilitate the building of very large strings, in a way that minimizes performance costs.

DEVELOPERS: Chris van Rensburg

The Uize.Str.Builder module is an object under the Uize.Str namespace, and is not a Uize.Class subclass.

1.1. In a Nutshell

Building strings using a traditional incremental concatenation approach using the += (incrementing assignment) operator can be slow in certain JavaScript interpreters when very large strings are being built.

One way around this performance issue is to use an array to accumulate all the segments of a large string, and then concatenate all the elements of that array at the end of the string building process using the Array object's join instance method. The Uize.Str.Builder object wraps this pattern up neatly into an object that also provides the benefit of string object parity that wouldn't otherwise be available in a manual array building process. In doing so, the Uize.Str.Builder object can provide a substantial performance benefit in certain applications.

1.1.1. Performance Benefit

The Uize.Str.Builder object can provide significant performance benefits in some JavaScript interpreters when building very large strings.

This can come in handy when writing build scripts that are to generate very large text files. When building small strings, using the Uize.Str.Builder object could actually do more harm than good. Therefore, use the Uize.Str.Builder object judiciously. If possible, test your code in the JavaScript interpreter that is slow at concatenating strings through incremental re-assignment, verifying that using the Uize.Str.Builder object is improving performance in your specific case.

1.1.2. A Before and After Example

To introduce the concept of a string builder object, let's take a look at a simple before and after example...

Let's say we have to build HTML for a gigantic data table from a records array and then write the HTML into the document using document.writeln (old school, indeed). Below is a comparison of how the code might be written before and after being retrofitted to use the Uize.Str.Builder object...

BEFORE

var tableHtml = '<table>';
for (var rowNo = -1; ++rowNo < rows.length;) {
  tableHtml += '<tr>';
  var cols = rows [rowNo];
  for (var colNo = -1; ++colNo < cols.length;) {
    tableHtml += '<td>' + cols [colNo] + '</td>';
  }
  tableHtml += '</tr>';
}
tableHtml += '</table>';
document.writeln (tableHtml);

AFTER

var tableHtml = Uize.Str.Builder ();
for (var rowNo = -1; ++rowNo < rows.length;) {
  tableHtml.append ('<tr>');
  var cols = rows [rowNo];
  for (var colNo = -1; ++colNo < cols.length;) {
    tableHtml.append ('<td>' + cols [colNo] + '</td>');
  }
  tableHtml.append ('</tr>');
}
tableHtml.append ('</table>');
document.writeln (tableHtml);

Note that what changed between the before and after versions is the initial assignment to the tableHtml variable, and the incrementing assignment statements. The document.writeln statement did not need to change, because the Uize.Str.Builder object implements the toString and valueOf Intrinsic Methods.

1.1.3. Initializing the Value

The value for a Uize.Str.Builder instance can be initialized in a number of different ways, as described below...

1.1.3.1. Initializing the Value in the Constructor

The very first opportunity that you have to initialize the value of a Uize.Str.Builder instance is during construction.

The constructor for the Uize.Str.Builder object supports a single parameter, being the initial value for the instance being created.

EXAMPLE

var myStringBuilder = Uize.Str.Builder ('hello');
alert (myStringBuilder);  // displays the text "hello"

If you don't set the value for an instance during construction, the value for the instance will be initialized to '' (empty string). There are still ways of initializing the value after construction.

1.1.3.2. Initializing the Value After Construction

After a Uize.Str.Builder instance has already been constructed, its value can be subsequently re-initialized using the setValue instance method.

The setValue instance method takes a single parameter, being the new value that the instance should be initialized to.

EXAMPLE

var myStringBuilder = Uize.Str.Builder ('hello');
myStringBuilder.setValue ('goodbye');
alert (myStringBuilder);  // displays the text "goodbye"

By specifying the value '' (empty string) when calling the setValue method, this method can be used for clearing the value after construction.

1.1.3.3. Clearing the Value After Construction

As a convenience, a clear instance method is provided to allow you to set the value of an instance to an empty string at any point.

The clear method takes no parameters, and calling it is equivalent to calling the setValue instance method and passing the value '' (empty string) as a parameter, or calling the variation of the setValue method that takes no parameters. The following three statements are all equivalent...

EXAMPLE

myStringBuilder.clear ();
myStringBuilder.setValue ('');
myStringBuilder.setValue ();

1.1.4. Building the Value

As an instance of an object, the value for a Uize.Str.Builder instance must be modified using instance methods.

The Uize.Str.Builder object provides two instance methods for building the value for an instance: the append and prepend instance methods. The append instance method can be used to add to the end of the value for an instance, and the prepend instance method can be used to add to the beginning. Consider the following exmaple...

EXAMPLE

var myStringBuilder = Uize.Str.Builder ();

myStringBuilder.append ('l');
myStringBuilder.prepend ('e');
myStringBuilder.append ('l');
myStringBuilder.prepend ('h');
myStringBuilder.append ('o');

alert (myStringBuilder);  // displays the text "hello"

The above example, while not representative of real world applications, shows how the append and prepend instance methods can be used in combination to build up a value for a Uize.Str.Builder instance.

1.1.5. Getting the Value

The Uize.Str.Builder object provides a number of ways of obtaining the value for an instance, as described below...

1.1.5.1. Using the getValue Instance Method

The most explicit way to obtain the value for a Uize.Str.Builder instance is to call the getValue instance method.

Like other ways of getting the value for an instance, calling the getValue instance method invokes value resolution for the instance, concatenating together any appended or prepended segments that were added since the last time that value resolution was performed for the instance. Consider the following example...

EXAMPLE

var myStringBuilder = Uize.Str.Builder ('solar');
myStringBuilder.append (' power');
alert (myStringBuilder.getValue ());  // displays the text "solar power"

1.1.5.2. Invoking the Intrinsic Methods

The JavaScript language defines intrinsic methods that are called on objects in situations where objects need to be resolved in order for an operation to be completed.

The toString Intrinsic Method is invoked automatically in certain contexts in order to convert an object to a string form, such as when alerting an object using the alert global function. The valueOf Intrinsic Method is invoked automatically in certain contexts in order to convert an object to a value, such as when using an object reference in an expression. As a convenience, the Uize.Str.Builder object defines these two intrinsic methods to perform the same operation as the getValue instance method. Consider the following example...

EXAMPLE

var myStringBuilder  = Uize.Str.Builder ('hello');


// all of the alert statements below will display the text "hello"

alert (myStringBuilder.getValue ());  // using getValue instance method
alert (myStringBuilder);              // invoking toString intrinsic method
alert (myStringBuilder.toString ());  // calling toString intrinsic method explicitly
alert (myStringBuilder + '');         // invoking valueOf intrinsic method
alert (myStringBuilder.valueOf ());   // calling valueOf intrinsic method explicitly

1.1.5.3. Value Resolution

Whether you are using the getvalue instance method or invoking the intrinsic methods, causing the string value for a Uize.Str.Builder instance to be returned will cause the value to be resolved.

Each time that the value of an instance is resolved there is the cost of concatenating any segments that have been appended or prepended and that are pending concatenation. The main performance benefit that comes from using the Uize.Str.Builder object derives from not needing to access the resolved / concatenated string value until at the end of the building process. However, not being able to easily access the value before building is complete could make it that much harder to retrofit existing code to use the Uize.Str.Builder object. Therefore, the methods for getting the value of an instance automatically resolve the value as needed.

1.1.5.4. Variable Type Conversion

When using a variable to store a reference to a Uize.Str.Builder instance, one can easily convert that variable to the string equivalent of the Uize.Str.Builder instance using the += (incrementing assignment) operator, as shown in the example below...

EXAMPLE

var fruitsTable = Uize.Str.Builder ();  // set fruitsTable to string builder instance
for (var fruitNo = -1; ++fruitNo < fruits.length;) {
  // ... ... ...
  // code here to append stuff to fruitsTable
  // ... ... ...
}
fruitsTable += '';  // force string builder to resolve value and reassign to fruitsTable

After the above code has been executed, the value of the fruitsTable variable will be a string, being the value that was built up using the Uize.Str.Builder object. This approach is certainly more concise than the statement fruitsTable = fruitsTable.getValue (). The re-assignment of the fruitsTable variable will cause the Uize.Str.Builder instance to be thrown into the garbage collection pile.

1.1.6. Value to String Coercion

As a convenience, many of the instance methods that are provided for initializing the value or building the value of a Uize.Str.Builder instance allow a value to be specified in any type.

Methods such as the append, equals, prepend, and setValue instance methods, along with the constructor, all support a valueANYTYPE parameter. The value for this parameter can be of any type, and will be coerced to a string. If the value is an instance of an object or a Uize.Class subclass, then it will be coerced to a string by invoking the object's valueOf Intrinsic Method. So, string type values, boolean type values, number type values, etc. can be used with these methods. As an example, following is a list of mappings between value and string equivalent...

HOW DIFFERENT TYPES OF VALUES ARE COERCED TO STRINGS
TYPE VALUE STRING EQUIVALENT
string 'fish' 'fish'
boolean true 'true'
number 42 '42'
number Infinity 'Infinity'
number NaN 'NaN'
object null 'null'
object (regular expression) /\s+/ '/\\s+/'
object (Uize instance) Uize.Class ({value:'foo'}) 'foo'
undefined undefined 'undefined'
function function () {alert (1)} 'function () {alert (1)}'

EXAMPLE

var myStringBuilder = Uize.Str.Builder ();
myStringBuilder.append ('hello');
myStringBuilder.append (true);
myStringBuilder.append (42);
myStringBuilder.append (null);

alert (myStringBuilder);  // displays "hellotrue42null"

1.1.7. String Object Parity

As a convenience, and to ease retrofitting of code to use the Uize.Str.Builder object, the Uize.Str.Builder object is designed to have as much parity with JavaScript's built-in String object as possible.

It does this in a number of ways, as described below...

1.1.7.1. Mixed in String Object Instance Methods

The Uize.Str.Builder object mixes instance methods from the String object's prototype into its own prototype.

This means that instance methods like charAt, indexOf, lastIndexOf, match, replace, substring, toLowerCase, etc. can be called on instances of the Uize.Str.Builder object, just as you would call these same methods on String object instances. Consider the following example...

EXAMPLE

var myStringBuilder = Uize.Str.Builder ('solar');
myStringBuilder.append (' power');
alert (myStringBuilder.toUpperCase ());  // displays the text "SOLAR POWER"

In the above example, when the toUpperCase instance method is called on the myStringBuilder instance, value resolution is triggered in the Uize.Str.Builder object. This is a pleasant side effect of the way that the methods of the String object are implemented.

For the full list of mixed in methods, see the section String Object Instance Methods.

1.1.7.2. length Property

A length property is maintained for Uize.Str.Builder object instances, to reflect the current length of the value - even before value resolution has been performed.

The length property lets code query the length of the string value represented by a Uize.Str.Builder instance, even before all the segments that may make up the value have been concatenated during value resolution. Consider the following example...

EXAMPLE

var myStringBuilder = Uize.Str.Builder ();
alert (myStringBuilder.length);  // displays the text "0"

myStringBuilder.append ('f');
alert (myStringBuilder.length);  // displays the text "1"

myStringBuilder.append ('o');
alert (myStringBuilder.length);  // displays the text "2"

myStringBuilder.append ('o');
alert (myStringBuilder.length);  // displays the text "3"

The value of the length property is maintained while building the value for the instance using the append and prepend instance methods, and when initializing the value during construction or when calling the clear and setValue instance methods. Unlike getting the value for a Uize.Str.Builder instance, simply querying its length property does not trigger value resolution, so querying length will not defeat the performance benefit of using this object.

You can use the length property to test if a Uize.Str.Builder instance has an empty value as follows...

var myStringBuilderIsEmpty = !myStringBuilder.length;

1.1.7.3. toString and valueOf Intrinsic Methods

To match how instances of the String object behave when involved in operations or passed as parameters in function and method calls, the Uize.Str.Builder object implements the toString Intrinsic Method and the valueOf Intrinsic Method.

Involving an instance of the Uize.Str.Builder object in an operation can result in JavaScript invoking the intrinsic methods in order to obtain a value that can be used in the operation. Consider the following example...

EXAMPLE

var
  myString = 'solar',
  myStringBuilder = Uize.Str.Builder ('solar')
;
alert (myString);                    // displays the text "solar"
alert (myStringBuilder);             // displays the text "solar"
alert (myString + ' power');         // displays the text "solar power"
alert (myStringBuilder + ' power');  // displays the text "solar power"

In the above example, the myStringBuilder instance behaves the same as the string variable myString. In the alert statement without concatenation, the toString Intrinsic Method is invoked for the myStringBuilder instance, but in the alert statement with concatenation the valueOf Intrinsic Method is invoked. For further discussion on this, see the section Invoking the Intrinsic Methods.

1.2. Examples

There are no dedicated showcase example pages for the Uize.Str.Builder module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Str.Builder module...

SEARCH

1.3. Implementation Info

The Uize.Str.Builder module defines the Uize.Str.Builder object under the Uize.Str namespace.

1.3.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

INSTANCE METHODS

anchor | append | big | blink | bold | charAt | charCodeAt | clear | concat | equals | fixed | fontcolor | fontsize | getValue | indexOf | italics | lastIndexOf | link | match | prepend | replace | search | setValue | slice | small | split | strike | sub | substr | substring | sup | toLowerCase | toString | toUpperCase | valueOf

STATIC PROPERTIES

Uize.Str.Builder.moduleName | Uize.Str.Builder.pathToResources

1.3.2. Features Overridden in This Module

No features have been overridden in this module.

1.3.3. Features Inherited From Other Modules

This module has no inherited features.

1.3.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.3.5. Unit Tests

The Uize.Str.Builder module is unit tested by the Uize.Test.Uize.Str.Builder test module.

2. Constructor

Returns a freshly constructed instance of the Uize.Str.Builder object.

SYNTAX

stringBuilderOBJ = Uize.Str.Builder (valueANYTYPE);

VARIATION

stringBuilderOBJ = Uize.Str.Builder ();

When no valueANYTYPE parameter is specified in the constructor, then the newly created Uize.Str.Builder instance will be initialized to an empty string.

For an in-depth discussion on setting the value for an instance, see the section Initializing the Value.

NOTES

the constructor supports value to string coercion for the valueANYTYPE parameter

3. Instance Properties

3.1. length

An integer, specifying the current length of the instance's value.

For an in-depth discussion of this property, see the section length Property.

4. Instance Methods

4.1. String Object Instance Methods

In addition to the instance methods implemented specifically to facilitate building strings, the Uize.Str.Builder object also supports the instance methods from JavaScript's String object.

These instance methods include: charAt, charCodeAt, concat, indexOf, lastIndexOf, match, replace, search, slice, split, substr, substring, toLowerCase, toUpperCase, anchor, big, blink, bold, fixed, fontcolor, fontsize, italics, link, small, strike, sub, and sup.

All of the String object instance methods implemented for the Uize.Str.Builder object have exactly the same signatures and behave in exactly the same way as they do for the String object. Because of this, they have not been documented in detail here. For a detailed explanation for any of them, consult a good JavaScript reference. For some examples, you can read through the section string object parity.

4.2. anchor

IMPLEMENTATION INFO

this feature was introduced in this module

4.3. append

Lets you append the specified value to the value of the instance.

SYNTAX

myStringBuilder.append (valueANYTYPE);

EXAMPLE

var myStringBuilder = Uize.Str.Builder ('solar');
myStringBuilder.append (' power');
alert (myStringBuilder);  // displays "solar power"

NOTES

see the companion prepend instance method
this method supports value to string coercion for the valueANYTYPE parameter

IMPLEMENTATION INFO

this feature was introduced in this module

4.4. big

IMPLEMENTATION INFO

this feature was introduced in this module

4.5. blink

IMPLEMENTATION INFO

this feature was introduced in this module

4.6. bold

IMPLEMENTATION INFO

this feature was introduced in this module

4.7. charAt

IMPLEMENTATION INFO

this feature was introduced in this module

4.8. charCodeAt

IMPLEMENTATION INFO

this feature was introduced in this module

4.9. clear

Lets you initialize the instance to an empty string.

SYNTAX

myStringBuilder.clear ();

The statement myStringBuilder.clear () has the same effect as the statements myStringBuilder.setValue ('') and myStringBuilder.setValue (). For a more in-depth discussion on setting the value for an instance, see the section Initializing the Value.

NOTES

see the related setValue instance method

IMPLEMENTATION INFO

this feature was introduced in this module

4.10. concat

IMPLEMENTATION INFO

this feature was introduced in this module

4.11. equals

Returns a boolean, indicating whether or not the instance's value is equal to the specified comparison value.

SYNTAX

equalBOOL = myStringBuilder.equals (valueANYTYPE);

EXAMPLE

var myStringBuilder = Uize.Str.Builder (' ');
myStringBuilder.append ('power');
myStringBuilder.prepend ('solar');
alert (myStringBuilder.equals ('solar power'));  // displays "true"

Because the Uize.Str.Builder object implements a valueOf Intrinsic Method, you can also coerce the value of an instance to a string before doing a normal equality operation, using the simple + '' trick. So, the following alert statement would produce the same result as the one shown in the above example...

alert (myStringBuilder + '' == 'solar power');  // displays "true"

VARIATION

equalBOOL = myStringBuilder.equals ();

When no valueANYTYPE parameter is specified, then the equals method tests whether or not the instance's value is an empty string. You can also use the length instance property to test if a Uize.Str.Builder instance has an empty value (see the section length Property for details).

NOTES

this method supports value to string coercion for the valueANYTYPE parameter

IMPLEMENTATION INFO

this feature was introduced in this module

4.12. fixed

IMPLEMENTATION INFO

this feature was introduced in this module

4.13. fontcolor

IMPLEMENTATION INFO

this feature was introduced in this module

4.14. fontsize

IMPLEMENTATION INFO

this feature was introduced in this module

4.15. getValue

Returns a string, being the current value of the instance.

SYNTAX

valueSTR = myStringBuilder.getValue ();

For a more in-depth discussion on accessing the value for an instance, see the section Getting the Value.

NOTES

see the equivalent toString Intrinsic Method and valueOf Intrinsic Method
calling this method will trigger value resolution

IMPLEMENTATION INFO

this feature was introduced in this module

4.16. indexOf

IMPLEMENTATION INFO

this feature was introduced in this module

4.17. italics

IMPLEMENTATION INFO

this feature was introduced in this module

4.18. lastIndexOf

IMPLEMENTATION INFO

this feature was introduced in this module

4.19. link

IMPLEMENTATION INFO

this feature was introduced in this module

4.20. match

IMPLEMENTATION INFO

this feature was introduced in this module

4.21. prepend

Lets you prepend the specified value to the value of the instance.

SYNTAX

myStringBuilder.prepend (valueANYTYPE);

EXAMPLE

var myStringBuilder = Uize.Str.Builder ('power');
myStringBuilder.prepend ('solar ');
alert (myStringBuilder);  // displays "solar power"

NOTES

see the companion append instance method
this method supports value to string coercion for the valueANYTYPE parameter

IMPLEMENTATION INFO

this feature was introduced in this module

4.22. replace

IMPLEMENTATION INFO

this feature was introduced in this module

4.23. search

IMPLEMENTATION INFO

this feature was introduced in this module

4.24. setValue

Lets you set the value for the instance.

SYNTAX

myStringBuilder.setValue (valueANYTYPE);

VARIATION

myStringBuilder.setValue ();

When no valueANYTYPE parameter is specified, then calling setValue has the same effect as calling clear.

For a more in-depth discussion on setting the value for an instance, see the section Initializing the Value.

NOTES

see the related clear instance method
see the companion getValue instance method
this method supports value to string coercion for the valueANYTYPE parameter

IMPLEMENTATION INFO

this feature was introduced in this module

4.25. slice

IMPLEMENTATION INFO

this feature was introduced in this module

4.26. small

IMPLEMENTATION INFO

this feature was introduced in this module

4.27. split

IMPLEMENTATION INFO

this feature was introduced in this module

4.28. strike

IMPLEMENTATION INFO

this feature was introduced in this module

4.29. sub

IMPLEMENTATION INFO

this feature was introduced in this module

4.30. substr

IMPLEMENTATION INFO

this feature was introduced in this module

4.31. substring

IMPLEMENTATION INFO

this feature was introduced in this module

4.32. sup

IMPLEMENTATION INFO

this feature was introduced in this module

4.33. toLowerCase

IMPLEMENTATION INFO

this feature was introduced in this module

4.34. toString

this feature was introduced in this module

IMPLEMENTATION INFO

4.35. toString Intrinsic Method

Returns a string, being the current value of the instance.

SYNTAX

valueSTR = myStringBuilder.toString ();

For a more in-depth discussion on accessing the value for an instance, see the section getting the value.

NOTES

see the equivalent getValue instance method and valueOf Intrinsic Method
calling this method will trigger value resolution

4.36. toUpperCase

IMPLEMENTATION INFO

this feature was introduced in this module

4.37. valueOf

this feature was introduced in this module

IMPLEMENTATION INFO

4.38. valueOf Intrinsic Method

Returns a string, being the current value of the instance.

SYNTAX

valueSTR = myStringBuilder.valueOf ();

For a more in-depth discussion on accessing the value for an instance, see the section getting the value.

NOTES

see the equivalent getValue instance method and toString Intrinsic Method
calling this method will trigger value resolution

5. Static Properties

5.1. Uize.Str.Builder.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

5.2. Uize.Str.Builder.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module