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.

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.

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 ();

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"

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

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.

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.

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.

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;

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.