FormatEx

Replaces the format item in a specified string with the string representation of a corresponding object in a specified array. A specified parameter supplies culture-specific formatting information.

 Public Function FormatEx(
	  ByVal Provider As IFormatProvider,
	  ByRef FormatText As String,
	  ParamArray Args ( ) As Variant ) As String

Parameters

Provider

[ByVal] IFormatProvider. An object that supplies culture-specific formatting information.

FormatText

[ByRef] String. A composite format string (see Remarks).

Args

[ByRef] Variant. An argument array that contains zero or more values to format.

Return Values

Remarks

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 provider parameter supplies custom and culture-specific information used to moderate the formatting process. The Provider parameter is an IFormatProvider implementation whose GetFormat method is called by the CorString.FormatEx(IFormatProvider, String,Object()) method. The method must return an object to supply formatting information that is of the same type as the FormatType parameter. The Provider parameters GetFormat method is called one or more times, depending on the specific type of objects in Args, as follows:

• It is always passed the format type name "ICustomFormatter".
• It is passed the format type name "DateTimeFormatInfo" for each format item whose corresponding data type is a date and time value.
• It is passed the format type name "NumberFormatInfo" for each format item whose corresponding data type is numeric.

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.

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 "}}".

Exceptions

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.

Examples

The following example uses the CorString.FormatEx(IFormatProvider, String,Object()) method to display the string representation of some date and time and numeric values using several different cultures.

Public Sub Main()
    Dim CultureNames() As String
    Dim CultureName As Variant
    Dim DateToDisplay As Date
    Dim Value As Double
    
    CultureNames = NewStrings("en-US", "fr-FR", "de-DE", "es-ES")
    DateToDisplay = #9/1/2009 6:32:00 PM#
    Value = 9164.32
    
    Debug.Print "Culture     Date                                Value"
    Debug.Print
    
    For Each CultureName In CultureNames
        Dim Culture As CultureInfo
        Dim Output As String
        
        Set Culture = NewCultureInfo(CultureName)
        Output = CorString.FormatEx(Culture, "{0,-11} {1,-35:D} {2:N}", Culture.Name, DateToDisplay, Value)
        
        Debug.Print Output
    Next
End Sub

' This code produces the following output.
'
'    Culture     Date                                Value
'
'    en-US       Tuesday, September 1, 2009          9,164.32
'    fr-FR       mardi 1 septembre 2009              9 164,32
'    de-DE       Dienstag, 1. September 2009         9.164,32
'    es-ES       martes, 1 de septiembre de 2009     9.164,32

The following example defines a customer number format provider that formats an integer value as a customer account number in the form x-xxxxx-xx.

There are two modules created for this example. A BAS module containing the Main method and a Class module implementing the IFormatProvider interface and ICustomFormatter interface.

The following is a Visual Basic Class module named CustomerFormatter.

Option Explicit
Implements IFormatProvider
Implements ICustomFormatter


Private Function IFormatProvider_GetFormat(FormatType As String) As Object
    If CorString.Equals(FormatType, "ICustomFormatter", OrdinalIgnoreCase) Then
        Set IFormatProvider_GetFormat = Me
    End If
End Function

Private Function ICustomFormatter_Format(ByVal FormatText As String, Arg As Variant, ByVal Provider As CorLib.IFormatProvider) As String
    Dim CustomerString As String
    Dim Separator As String
    Dim Result As String
    
    If Not Provider Is Me Then
        Exit Function
    End If
    
    CustomerString = Object.ToString(Arg)
    
    If Len(CustomerString) < 8 Then
        CustomerString = CorString.PadLeft(CustomerString, 8, "0")
    End If
    
    Select Case FormatText
        Case "", "G"
            Separator = "-"
        Case "S"
            Separator = "/"
        Case "P"
            Separator = "."
        Case Else
            Throw NewFormatException(CorString.Format("The '{0}' format specifier is not supported.", FormatText))
    End Select
    
    ICustomFormatter_Format = Left$(CustomerString, 1) & Separator & Mid$(CustomerString, 2, 5) & Separator & Mid$(CustomerString, 7)
End Function

The following is a Visual Basic BAS module containing Main start-up method.

Public Sub Main()
    Const AcctNumber As Long = 79203159
    
    Debug.Print CorString.FormatEx(New CustomerFormatter, "{0}", AcctNumber)
    Debug.Print CorString.FormatEx(New CustomerFormatter, "{0:G}", AcctNumber)
    Debug.Print CorString.FormatEx(New CustomerFormatter, "{0:S}", AcctNumber)
    Debug.Print CorString.FormatEx(New CustomerFormatter, "{0:P}", AcctNumber)
    
    On Error GoTo Catch
    Debug.Print CorString.FormatEx(New CustomerFormatter, "{0:X}", AcctNumber)
    Exit Sub
    
Catch:
    Dim Ex As FormatException
    
    Catch Ex
    Debug.Print Ex.Message
End Sub

' This code produces the following output.
'
'    7-92031-59
'    7-92031-59
'    7/92031/59
'    7.92031.59
'    The 'X' format specifier is not supported.

See Also

Project CorLib Overview

Class CorString Overview

Format

FormatArray

FormatArrayEx

NumberFormatInfo

DateTimeFormatInfo