updating oE text format

note "format" is not unique, may need namespace prefix


include text.e 
namespace text 
public function format(sequence format_pattern, object arg_list = {}) 

formats a set of arguments in to a string based on a supplied pattern.

  1. format_pattern : A sequence: the pattern string that contains zero or more tokens.
  2. arg_list : An object: Zero or more arguments used in token replacement.

A string sequence, the original format_pattern but with tokens replaced by corresponding arguments.


The format_pattern string contains text and argument tokens. The resulting string is the same as the format string except that each token is replaced by an item from the argument list.

A token has the form [<Q>], where <Q> is are optional qualifier codes.

The qualifier. <Q> is a set of zero or more codes that modify the default way that the argument is used to replace the token. The default replacement way is to convert the argument to its shortest string representation and use that to replace the token. This may be modified by the following codes, which can occur in any order.

Qualifier Usage
N ('N' is an integer) The index of the argument to use
{id} Uses the argument that begins with "id=" where "id"
is an identifier name.
%envvar% Uses the Environment Symbol 'envar' as an argument
w For string arguments, if capitalizes the first
letter in each word
u For string arguments, it converts it to upper case.
l For string arguments, it converts it to lower case.
< For numeric arguments, it left justifies it.
> For string arguments, it right justifies it.
c Centers the argument.
z For numbers, it zero fills the left side.
:S ('S' is an integer) The maximum size of the
resulting field. Also, if 'S' begins with '0' the
field will be zero-filled if the argument is an integer
.N ('N' is an integer) The number of digits after
the decimal point
+ For positive numbers, show a leading plus sign
( For negative numbers, enclose them in parentheses
b For numbers, causes zero to be all blanks
s If the resulting field would otherwise be zero
length, this ensures that at least one space occurs
between this token's field
t After token replacement, the resulting string up to this point is trimmed.
X Outputs integer arguments using hexadecimal digits.
B Outputs integer arguments using binary digits.
? The corresponding argument is a set of two strings. This
uses the first string if the previous token's argument is
not the value 1 or a zero-length string, otherwise it
uses the second string.
[ Does not use any argument. Outputs a left-square-bracket symbol
,X Insert thousands separators. The <X> is the character
to use. If this is a dot "." then the decimal point
is rendered using a comma. Does not apply to zero-filled
N.B. if hex or binary output was specified, the
separators are every 4 digits otherwise they are
every three digits.
T If the argument is a number it is output as a text character,
otherwise it is output as text string

Clearly, certain combinations of these qualifier codes do not make sense and in those situations, the rightmost clashing code is used and the others are ignored.

Any tokens in the format that have no corresponding argument are simply removed from the result. Any arguments that are not used in the result are ignored.

Any sequence argument that is not a string will be converted to its pretty format before being used in token replacement.

If a token is going to be replaced by a zero-length argument, all white space following the token until the next non-whitespace character is not copied to the result string.

Example 1:
format("Cannot open file '[]' - code []", {"/usr/temp/work.dat", 32}) 
-- "Cannot open file '/usr/temp/work.dat' - code 32" 
format("Err-[2], Cannot open file '[1]'", {"/usr/temp/work.dat", 32}) 
-- "Err-32, Cannot open file '/usr/temp/work.dat'" 
format("[4w] [3z:2] [6] [5l] [2z:2], [1:4]", {2009,4,21,"DAY","MONTH","of"}) 
-- "Day 21 of month 04, 2009" 
format("The answer is [:6.2]%", {35.22341}) 
-- "The answer is  35.22%" 
format("The answer is [.6]", {1.2345}) 
-- "The answer is 1.234500" 
format("The answer is [,,.2]", {1234.56}) 
-- "The answer is 1,234.56" 
format("The answer is [,..2]", {1234.56}) 
-- "The answer is 1.234,56" 
format("The answer is [,:.2]", {1234.56}) 
-- "The answer is 1:234.56" 
format("[] [?]", {5, {"cats", "cat"}}) 
-- "5 cats" 
format("[] [?]", {1, {"cats", "cat"}}) 
-- "1 cat" 
format("[<:4]", {"abcdef"}) 
-- "abcd" 
format("[>:4]", {"abcdef"}) 
-- "cdef" 
format("[>:8]", {"abcdef"}) 
-- "  abcdef" 
format("seq is []", {{1.2, 5, "abcdef", {3}}}) 
-- `seq is {1.2,5,"abcdef",{3}}` 
format("Today is [{day}], the [{date}]", {"date=10/Oct/2012", "day=Wednesday"}) 
-- "Today is Wednesday, the 10/Oct/2012" 
format("'A' is [T]", 65) 
-- `'A' is A` 
See Also:


Not Categorized, Please Help


Quick Links

User menu

Not signed in.

Misc Menu