FormatResult Method [Visio 2003 SDK Documentation]

Article
05/01/2007

Formats a string or number into a string according to a format picture. Uses specified units for scaling and formatting.

stringRet = object**.FormatResult**(StringOrNumber, UnitsIn, UnitsOut, Format)

stringRet String. The evaluated result formatted according to format and UnitsOut.

object Required. An expression that returns an Application object.

StringOrNumber Required Variant. String or number to be formatted; can be passed as a string, floating point number, or integer.

UnitsIn Required Variant. Measurement units to attribute to StringOrNumber.

UnitsOut Required Variant. Measurement units to express the result in.

Format Required String. Picture of what the result string should look like.

Version added

4.5

Remarks

If passed as a string, StringOrNumber might be the formula or prospective formula of a cell or the result or prospective result of a cell expressed as a string. The FormatResult method evaluates the string and formats the result. Because the string is being evaluated outside the context of being the formula of a particular cell, the FormatResult method returns an error if the string contains any cell references.

Possible values for StringOrNumber include:

1.7

"2.5"

"4.1 cm"

"12 ft - 17 in. + (12 cm / SQRT(7))"

The UnitsIn and UnitsOut arguments can be strings such as "inches", "inch", "in.", or "i". Strings may be used for all supported Microsoft Office Visio units such as centimeters, meters, miles, and so on. You can also use any of the unit constants declared by the Visio type library in VisUnitCodes. A list of valid units is also included in About units of measure.

If StringOrNumber is a string, UnitsIn specifies how to interpret the evaluated result and is only used if the result is a scalar. For example, the expression "4 * 5 cm" evaluates to 20 cm, which is not a scalar, so UnitsIn is ignored. The expression "4 * 5" evaluates to 20, which is a scalar and is interpreted using the specified UnitsIn.

The UnitsOut argument specifies the units in which the returned string should be expressed. If you want the results expressed in the same units as the evaluated expression, pass "NOCAST" or visNoCast.

Format is a string that specifies a template or picture of the string produced by the FormatResult method. For details, see the FORMAT function. A few of the possibilities are:

# : Output a single digit, but not if it's a leading or trailing 0.

0 : Output a single digit, even if it is a leading or trailing 0.

. : Decimal placeholder.

, : Thousands separator.

"text" or 'text' : Output enclosed text as is.

\c : Output the character c.

Example

Where a string is specified

' Prints 1.00
Debug.Print Application.FormatResult("0.5 * 2", "ft", "ft", "#.00 u")

' Prints 12.00 in.    
Debug.Print Application.FormatResult("0.5 * 2", "ft", "in", "#.00 u")

' Prints .39 in.    
Debug.Print Application.FormatResult("1 cm", "ft", "in", "#.00 u")

' Prints 1.00 cm. 
Debug.Print Application.FormatResult("1 cm", "ft", "NOCAST", "#.00 u")    

' Prints 0.39
Debug.Print Application.FormatResult("1 cm", "ft", "", "0.00 u")   

' Prints 1858.06 sq. cm.
Debug.Print Application.FormatResult("1 sq. ft. * 2", "in^2", "cm^2", "0.00 u")

' Throws an exception because of bad measurement unit ("bozo")
Debug.Print Application.FormatResult("1 cm", "ft", "bozo", "#.00 u")

Where a number is specified

' Prints 1.00
Debug.Print Application.FormatResult(1, "ft", "ft", "#.00 u")

' Prints 12.00 in.    
Debug.Print Application.FormatResult(1, "ft", "in", "#.00 u")

' Prints .08 ft.
Debug.Print Application.FormatResult(1.0, "in", "ft", "#.00 u")   

' Prints 12.00
Debug.Print Application.FormatResult(1.0, visFeet, "", "#.00 u")  

' Throws an exception because of bad measurement unit ("bozo")
Debug.Print Application.FormatResult(1, "bozo", "in", "#.00 u")

The following macro shows how to use the FormatResult method to convert a value from centimeters to inches and display the result in a message box.

Public Sub FormatResult_Example() 

    Dim strOldValue As String 
    Dim strNewValue As String
 
    'Set old value. 
    strOldValue = "1 cm"
 
    'Format value. 
    strNewValue = Application.FormatResult _ 
        (strOldValue, "ft", "in", "#.00 u")
 
    'Display new value. 
    MsgBox (strNewValue) 

End Sub

Applies to | Application object | InvisibleApp object

See Also | ConvertResult method | Result property

Share via