Section 16.12. Append and AppendFormat Methods of Class StringBuilder

16.12. Append and AppendFormat Methods of Class StringBuilder

Class StringBuilder provides 19 overloaded Append methods for appending values of various types to the end of a StringBuilder's contents. There are versions of this method for each of the primitive types and for character arrays, Strings and Objects. Remember that method ToString produces a String representation of any Object, so any Object's string representation can be appended to a StringBuilder. Each of the methods takes an argument, converts it to a String and appends it to the StringBuilder. Figure 16.11 demonstrates several Append methods.

Figure 16.11. Append methods of StringBuilder.

  1  ' Fig. 16.11: StringBuilderAppend.vb  2  ' Demonstrating StringBuilder Append methods.  3  Imports System.Text  4  5  Module StringBuilderAppend  6     Sub Main()  7        Dim objectValue As Object = "hello"  8        Dim stringValue As String = "good bye"  9        Dim characterArray As Char() = {"a"c, "b"c, "c"c, "d"c, "e"c, "f"c} 10        Dim booleanValue As Boolean = True 11        Dim characterValue As Char = "Z"c 12        Dim integerValue As Integer = 7 13        Dim longValue As Long = 1000000 14        Dim floatValue As Single = 2.5F ' F indicates that 2.5 is a float 15        Dim doubleValue As Double = 33.333 16        Dim buffer As New StringBuilder() 17 18        ' use method Append to append values to buffer 19        buffer.Append(objectValue)                     20        buffer.Append(" ")                             21        buffer.Append(stringValue)                     22        buffer.Append(" ")                             23        buffer.Append(characterArray)                  24        buffer.Append(" ")                             25        buffer.Append(characterArray, 0, 3)            26        buffer.Append(" ")                             27        buffer.Append(booleanValue)                    28        buffer.Append(" ")                             29        buffer.Append(characterValue)                  30        buffer.Append(" ")                             31        buffer.Append(integerValue)                    32        buffer.Append(" ")                             33        buffer.Append(longValue)                       34        buffer.Append(" ")                             35        buffer.Append(floatValue)                      36        buffer.Append(" ")                             37        buffer.Append(doubleValue)                     38 39        Console.WriteLine("buffer = " & buffer.ToString() & vbCrLf) 40     End Sub ' Main 41  End Module ' StringBuilderAppend 

[View full width]
buffer = hello good bye abcdef abc True Z 7  1000000 2.5 33.333 

Lines 1937 use 10 different overloaded Append methods to append the String representations of the variables created in lines 716 to the end of the StringBuilder. Append behaves similarly to the & operator, which is used to concatenate Strings.

Class StringBuilder also provides method AppendFormat, which converts a String to a specified format, then appends it to the StringBuilder. The example in Fig. 16.12 demonstrates this method.

Figure 16.12. StringBuilder's AppendFormat method.

  1  ' Fig. 16.12: StringBuilderAppendFormat.vb  2  ' Demonstrating method AppendFormat.  3  Imports System.Text  4  5  Module StringBuilderAppendFormat  6     Sub Main()  7        Dim buffer As New StringBuilder()  8        Dim string1, string2 As String  9 10        ' formatted string                          11        string1 = "This {0} costs: {1:C}." & vbCrLf 12 13        ' string1 argument array     14        Dim objectArray(2) As Object 15 16        objectArray(0) = "car"   17        objectArray(1) = 1234.56 18 19        ' append to buffer formatted string with argument 20        buffer.AppendFormat(string1, objectArray)         21 22        ' formatted string                                         23        string2 = "Number:{0:d3}." & vbCrLf & _                    24           "Number right aligned with spaces:{0, 4}." & vbCrLf & _ 25           "Number left aligned with spaces:{0, -4}."              26 27        ' append to buffer formatted string with argument 28        buffer.AppendFormat(string2, 5 )                  29 30        ' display formatted strings 31        Console.WriteLine(buffer.ToString()) 32     End Sub ' Main 33  End Module ' StringBuilderAppendFormat 

This car costs: $1,234.56. Number:005. Number right aligned with spaces: 5. Number left aligned with spaces:5 . 

Line 11 creates a String that contains formatting information. The information enclosed within the braces specifies how to format a specific piece of information. Formats have the form {X[,Y] [:FormatString]}, where X is the number of the argument to be formatted, counting from zero. Y is an optional argument, which can be positive or negative, indicating how many characters should be in the formatted String. If the resulting String has fewer characters than the number Y, the String will be padded with spaces to make up for the difference. A positive integer aligns the String to the right; a negative integer aligns it to the left. The optional FormatString applies a particular format to the argumentcurrency, decimal or scientific, among others. In this case, {0} means that the first argument's String representation will be included in the formatted String. {1:C} specifies that the second argument will be formatted as a currency value.

Line 20 shows a version of AppendFormat that takes two parametersa String specifying the format and an array of objects to serve as the arguments to the format String. The argument referred to by {0} is in the object array at index 0.

Lines 2325 define another String used for formatting. The first format {0:D3}, specifies that the first argument will be formatted as a three-digit decimal, meaning any number that has fewer than three digits will have leading zeros, so the total number of formatted digits will be 3. The next format, {0, 4}, specifies that the formatted String should have four characters and should be right aligned. The third format, {0, -4}, specifies that the String should be aligned to the left. For more formatting options, please refer to the online help documentation.

Line 28 uses a version of AppendFormat that takes two parametersa String containing a format and an object to which the format is applied. In this case, the object is the number 5. The output of Fig. 16.12 displays the result of applying these versions of AppendFormat with their respective arguments.