| CorString: Format |
Replaces the format item in a specified string with the string representation of a corresponding value in a specified array.
Public Function Format( ByRef FormatText As String, ParamArray Args ( ) As Variant ) As String
This method uses the composite formatting feature of VBCorLib to convert the value of an object to its text representation and embed that representation in a string.
The FormatText parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to a value in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding value.
The syntax of a format item is as follows:
{index[,length][:formatString]}
Elements in square brackets are optional. The following table describes each element.
| Element | Description |
|---|---|
| index | The zero-based position in the parameter list of the value to be formatted. If the value specified by index is Nothing, the format item is replaced by an empty string (""). If there is no parameter in the index position, a FormatException is thrown. |
| ,length | The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned. |
| :formatString | A standard or custom format string that is supported by the value to be formatted. Possible values for formatString are the same as the values supported by the values ToString(FormatText) method. If formatString is not specified and the value to be formatted implements the IFormattable interface, vbNullString is passed as the value of the Format parameter that is used as the IFormattable.ToString format string. |
The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in FormatText, specify two leading or trailing brace characters; that is, "{{" or "}}".
| Exception | Condition |
|---|---|
| FormatException |
FormatText is invalid. -or- The index of a format item is less than zero, or greater than or equal to the length of the Args array. |
The following example creates a string that contains data on the high and low temperature on a particular date. Two of the format items define the width of their corresponding values string representation, and the first format item also includes a standard date and time format string.
Public Sub Main() Dim Date1 As Date Dim HiTime As TimeSpan Dim HiTemp As Variant Dim LowTime As TimeSpan Dim LowTemp As Variant Dim Result As String Dim Values() As Variant Date1 = #7/1/2009# Set HiTime = NewTime(#2:17:32 PM#) HiTemp = CDec(62.1) Set LowTime = NewTime(#3:16:10 AM#) LowTemp = CDec(54.8) Result = CorString.Format("Temperature on {0:d}:{5}{1,11}: {2} degrees (hi){5}{3,11}: {4} degrees (lo)", Date1, HiTime, HiTemp, LowTime, LowTemp, vbCrLf) Debug.Print Result Debug.Print Values = Array(Date1, HiTime, HiTemp, LowTime, LowTemp, vbCrLf) Result = CorString.FormatArray("Temperature on {0:d}:{5}{1,11}: {2} degrees (hi){5}{3,11}: {4} degrees (lo)", Values) Debug.Print Result End Sub ' This code produces the following output. ' ' Temperature on 7/1/2009: ' 14:17:32: 62.1 degrees (hi) ' 03:16:10: 54.8 degrees (lo) ' ' Temperature on 7/1/2009: ' 14:17:32: 62.1 degrees (hi) ' 03:16:10: 54.8 degrees (lo)