Cold Help System: Programming: ColdC Reference Manual: Functions: String: strfmt()

STRING strfmt(STRING format, ANY arg, ...)

This function formats its arguments and returns the result. How the arguments are formatted depends upon the argument format. The format contains two types of sequences: plain characters, which are simply copied to the new string, and format specifications, each of which causes printing of the next successive argument. The format begins with a percent character (%), followed by:

Pad Length

The pad length is an integer which specifies the length of characters to pad the argument in. Pad Length is optional. Specifying a zero pad length will be ignored, and is equivalent to not specifying a pad length.

Precision

A period (.), followed by an integer specifies the precision, which specifies the number of digits to appear after the decimal point when printing FLOAT arguments. Precision is optional, and does not have to be specified. If it is specified it must come after the Pad Length (if specified), and before the Filler (if specified) or Format Type.

Filler

Filler specifies what is used when padding a string within the Pad Length. Filler is specified within curly braces ({ and }). To include a curly brace in the filler prefix it with a backslash. The Filler must come after Pad Length or Precision, if they are specified, and before Format Type.

Format Type

Format type must be specified last, and is not optional. Format Type specifies how the argument is to be handled. It is one of the following characters:

d or D

literal data

s or S or l or L

any data, align left

r or R

any data, align right

c or C

any data, align centered

e

any data, align left with an elipse

If the Format Type is anything but d or D, the data will be converted as if it were "added" to a string using the arithmetic operator. If an uppercase character is used in the Format Type, any argument which has a length longer than the Pad Length will be truncated accordingly. Otherwise the argument will not be truncated. If an elipse is used, the argument will always be truncated three characters shorter than the Pad Length, with "..." being placed at the end.

Examples:

strfmt("%r", "test")
=> "test"

strfmt("%l", "test")
=> "test"

strfmt("%c", "test")
=> "test"

strfmt("%d", "test")
=> ""test""

strfmt("%10r", "test")
=> " test"

strfmt("%10l", "test")
=> "test "

strfmt("%10c", "test")
=> " test "

strfmt("%10{|>}r", "test")
=> "|>|>|>test"

strfmt("%10{|>}l", "test")
=> "test|>|>|>"

strfmt("%10{|>}c", "test")
=> "|>|test|>|"

strfmt("%.2l", 1.1214)
=> "1.12"

strfmt("%10.3{0}r", 1.1214)
=> "000001.121"

strfmt("%10.3{0}r", 1.1214)
=> "1.12100000"

strfmt("%5e", "testing")
=> "te..."

strfmt("%s parents: %25e", "$user", [$body, $interaction, $mail_ui]);
=> "$user parents: [$body, $interaction, ..."

crypt() | explode() | lowercase() | match_begin() | match_pattern() | match_regexp() | match_template() | pad() | regexp() | strcmp() | strfmt() | strgraft() | strlen() | strsed() | strsub() | substr() | uppercase() | match_crypted() | split() | stridx()