Skip to content

SFormat

See Also: String Functions, Replace, Replaces

Purpose

Creates a formatted string by replacing markers in a host string (%1, %2, etc.) with sub-string values.

Return Type

String

Syntax

Use GlobalFunctionsProcedures.pkg
(SFormat({host-string}, {new-substring-1}, ..., {new-substring-9}))

Where:

  • {host-string} is a string value with (%1, %2, ...) placeholders for string substitution.
  • {new-substring-1}, ..., {new-substring-9} are string values to replace the respective placeholders (%1, %2, ...) with.

What It Does

SFormat is passed a host string and 1 to 9 replacement sub-strings. The host string contains replacement markers for each sub-string. The function returns a formatted string where all markers are replaced with the passed sub-strings. A replacement marker is defined as the % symbol followed by the replacement number. The first replacement marker is %1, the second is %2, and so on.

Examples

The following example will return "Hello, John how are you today":

Move (
    SFormat("Hello, %1 how are you today", "John")
) to sReply

Replacement markers may be placed in any order and used more than once. The following example will return the string "I want to say Hello, Goodbye, Hello":

Move (
    SFormat("I want to say %2, %1, %2", "Goodbye", "Hello")
) to sReply

This function is used extensively by the packages to support multi-language text. For example:

Send Log_Status (
    SFormat(C_$EndProcessNumberOfErrors, Process_Title(self), ErrCount)
)

where the constant C_$EndProcessNumberOfErrors is defined in a separate language package. The English version of this constant is "End Process: %1 (number of errors=%2)".

Notes

Note that the above sample passes the replacement parameter ErrCount as an integer. The integer will be converted to a string before being inserted into the host string. This can be a useful automatic conversion technique.

If your host string needs to display a % symbol followed by a number, you should use %% instead of % to represent the text. The following example will return "This first parameter %1, will get replaced with coffee":

Move "coffee" to sSomeSymbol

Move (
    SFormat("This first parameter %%1, will get replaced with %1", sSomeSymbol)
) to sReply