2.5.4.43 FormatEx
The FormatEx function formats a value as a string.
ABNF:
-
FormatEx = val val val val val val " FORMATEX():128"
Required Arguments:
Name: FormatValue
Type: vDoubleEx
An argument that specifies the value to be formatted.
Name: Format
Type: PtgStr1
An argument that specifies the formatting information used to format FormatValue. It MUST have the following format.
"Formatting@ServerAction@UnitLabel@CurrencyID"
The elements of the string are separated by "@" and are defined in the following paragraphs.
Formatting: A vFormatString that specifies the formatting information.
If Formatting is an empty string, a default value from the following table is used.
|
Value |
Meaning |
|---|---|
|
"{0} {1}" |
Default string format. This is used if the type of the source token of FormatValue is PtgStr1, PtgEDay, PtgEHour, PtgEMin, PtgESec, PtgEWeek, or PtgTDurDft. |
|
"{0:0.####} {1}" |
Default numeric format for numbers with less than 16 digits to the left of the decimal point. This is used if the type of the source token of FormatValue is PtgBool, PtgCy, PtgMissArg, PtgNum, PtgUnsWord, or a vUnitType other than PtgDate, PtgEDay, PtgEHour, PtgEMin, PtgESec, PtgEWeek, and PtgTDurDft. |
|
"{0:0.####e0} {1}" |
Default numeric format for numbers with 16 or more digits to the left of the decimal point. This is used if the type of the source token of FormatValue is PtgBool, PtgCy, PtgMissArg, PtgNum, PtgUnsWord, or a vUnitType other than PtgDate, PtgEDay, PtgEHour, PtgEMin, PtgESec, PtgEWeek, and PtgTDurDft. |
|
"G" |
Default date and time format when the time value is not equal to zero. This is used if the type of the source token of FormatValue is PtgDate. |
|
"d" |
Default date and time format when the time value is equal to zero. This is used if the type of the source token of FormatValue is PtgDate. |
If Formatting is not empty and FormatValue is a PtgDate, Formatting MUST be a vFormatString with valid syntax for formatting a date and time value. If Formatting is not empty and FormatValue is not a PtgDate, Formatting MUST be a vFormatString with valid syntax for formatting a numeric value.
ServerAction: A vServerAction that specifies the custom formatting to apply to a string after all other formatting has been performed.
UnitLabel: A vUnitLabel that specifies the rules for formatting the unit of the resulting string.
CurrencyID: A vCurrencyID that specifies the currency identifier.
Name: SrcUnit
Type: vUnitType
An argument that specifies the unit of FormatValue. The value is unused and MUST be ignored. If FormatValue is a vUnitType, this argument is unused and MUST be ignored.
Name: DstUnit
Type: vNum
An argument that specifies the unit displayed in the resulting string. The value is unused and MUST be ignored. If the type is PtgNum, the type of SrcUnit is used.
Name: LangID
Type: vLanguageID
An argument that specifies an LCID used to format FormatValue.
Name: CalID
Type: vCalendar
An argument that specifies a calendar system used to format FormatValue. If FormatValue is not a PtgDate, this argument is unused and MUST be ignored.
Return Value:
Type: PtgStr1, PtgErr
This function returns a PtgStr1 containing FormatValue, converted into the unit specified by DstUnit, formatted as a string as specified by Format, LangID, and CalID.
FormatValue is converted into the unit specified by DstUnit as follows. If FormatValue is not a vUnitType, the value of FormatValue is multiplied by a factor that converts the unit of SrcUnit into the custom internal unit type associated with the type of SrcUnit. The resulting value, or the value of FormatValue if FormatValue is a vUnitType, is multiplied by a factor that converts the custom internal unit type associated with the type of DstUnit into the unit of DstUnit
If FormatValue is a PtgDate, FormatValue is formatted using date and time format strings, as described in [MSDN-FormattingTypes]. If FormatValue is not a PtgDate, the value of FormatValue is formatted using numeric format strings, as described in [MSDN-FormattingTypes].
If the formatting does not succeed or an argument is invalid, the function returns a PtgErr with an error code of #VALUE!.