OpenEuphoria

format

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

outputs a string based on a format_pattern where formated arguments have replaced inset tokens.

Parameters:

1. format_pattern : A sequence: the pattern string that contains zero or more inset tokens.
2. arg_list : An object: Optional list of zero or more arguments.

Returns:

A string sequence, the original format_pattern string after inset tokens are replaced by corresponding formatted arguments.

Comments:

The write function and the writef and writefln procedures all share syntax and the same formatting codes.

The format pattern is "a string containing optional text and zero or more inset tokens." An inset token is a collection of zero or more qualifier codes enclosed by opening [ and closing ] brackets; qualifier codes can be written in any order. A qualifier code is "determines which argument is seleted or how that argument is formatted."

An inset token with no qualifier [] is replaced by the shortest string representation of the argument.

Qualifier codes can be combined and written in any order; no spacers or separators are used when writing qualifier codes.

Qualifier codes are applied in order from left to right. A qualifier code will override a previous conflicting qualifier; conflicting codes are quietly ignored; it is always the right most qualifier that takes effect. For example: you can not have left justify < and right justify > at the same time; You can write >< but only < will be accepted.

Some qualifier codes need their own argument: for example the qualifier :F is written as :10 for a ten character field width.

Unused inset tokens are simply removed from the output string.

Unused arguments are quietly ignored.

Any argument that is not a string will be converted to its pretty format before being used in token replacement; see include std/pretty.e .

When an argument produces a zero-length result then the inset token is removed along with following whitespace characters up to the first non-whitespace character.

The replacement process:

1. The argument is selected.
2. The argument becomes a formatted string based on the collection of qualifier codes.
3. The inset token is removed.
4. The string (zero or more characters) is spliced into the format pattern.

Summary: the output string resembles the format string except that each token is replaced by a corresponding formatted argument.

	Qualifier	Usage
General
[]		Empty opening and closing brackets. Inset tokens and arguments are matched in the order they are originally written. The default format is the shortest string representation of the argument.
	t	After token replacement, the resulting string up to this point is trimmed.
	s	Splice in at least one space; used when a formatted argument could produce a zero-length string.
	:F	A field F characters wide.
	>	Right justify argument.
	<	Left justify argument.
	c	Center the argument.
	[	Write [[] to output a literal opening bracket character; the closing bracket ] is output without added syntax.
Select Argument
	I	Select argument by index I (an integer value).
	{id}	Select argument by name; each argument may be written as a string using the syntax "id=value" where id is an identfier name and value is the normal value of the argument. The id when enclosed by braces {} will select the argument.
	%envvar%	Select the Environment Symbol envvar as an argument
Text
	T	Force output as a characer or as a string.
	w	Capitalize the first letter in each word.
	u	Convert to upper case.
	l	Convert to lower case.
Number
	.N	There are N digits after the decimal point
	z	Fill with leading zeros.
	:0F	A field F characters wide and filled with leading zeros when the argument is an integer.
	+	Show a leading plus sign for positive value.
	(	Enclose negative value in parentheses.
	b	The value zero 0 becomes all blanks.
	,G	Group digits and insert a separator character; the G is the character to use as a separator. The decimal point is normally a period (.), however if a period is the selected characer then the decimal point becomes a comma. Does not apply to zero-filled fields. Decimal values are grouped by three digits; hexadecimal and binary values are grouped by four digits.
	X	Display using hexadecimal digits.
	B	Display using binary digits.
Special
	?	The ? qualifier requires an argument that is a sequence of two strings. The value of the previous argument selects which string is selected; if the value of the previous argument is not one (!1) or a zero-length string then select the first string; otherwise select the second string.

Note:

Related output routines.

% Inset	[] Inset
built-in routines	library routines
sprintf	write
printf	writef
	writefln

The built-in routines are faster but offer fewer formatting options.

Example 1:

Arguments selected in the order they were written.

format("Cannot open file '[]' - code []", {"/usr/temp/work.dat", 32}) 
-->  "Cannot open file '/usr/temp/work.dat' - code 32" 

Order of arguments selected by the user.

format("Err-[2], Cannot open file '[1]'", {"/usr/temp/work.dat", 32}) 
--> "Err-32, Cannot open file '/usr/temp/work.dat'" 

Example 2:

First integer selects the argument for a custom order. Codes, like w z, format text. Numbers after a colon : determine the inset width.

format("[4w] [3z:2] [6] [5l] [2z:2], [1:4]", {2009,4,21,"DAY","MONTH","of"}) 
--> "Day 21 of month 04, 2009" 

Example 3:

Number field width and digits after the decimal point.

format("The answer is [:6.2]%", {35.22341}) 
-->  "The answer is  35.22%" 

Trailing zeros will pad a number field.

format("The answer is [.6]", {1.2345}) 
--> "The answer is 1.234500" 

Example 4:

The code ,, means group digits in threes using a comma separator.

format("The answer is [,,.2]", {1234.56}) 
--> "The answer is 1,234.56" 

The code ,. means group decimal digits into threes using a period . as a sepratator. This means the decimal point becomes a comma.

format("The answer is [,..2]", {1234.56}) 
--> "The answer is 1.234,56" 

The code ,: groups decimal digits into threes using a colon : as a separator.

format("The answer is [,:.2]", {1234.56}) 
--> "The answer is 1:234.56" 

Example 5:

Use the ? qualifier to select the correct gramatical form from a pair of arguments:

format("[] [?]", {5, {"cats", "cat"}}) 
--> "5 cats" 
 
format("[] [?]", {1, {"cats", "cat"}}) 
--> "1 cat" 

Example 6:

Left justify the first four characters.

format("[<:4]", {"abcdef"}) 
--> "abcd" 

Right justify the last four characters.

format("[>:4]", {"abcdef"}) 
--> "cdef" 

Right justify six characters in a field of eight spaces.

format("[>:8]", {"abcdef"}) 
--> "  abcdef" 

Example 7:

Note that the argument is one item; length is one.

format("seq is []", {{1.2, 5, "abcdef", {3}}}) 
--> `seq is {1.2,5,"abcdef",{3}}` 

Example 8:

The arguments are given identifiers and then selected by identifier in the inset tokens.

format("Today is [{day}], the [{date}]", {"date=10/Oct/2012", "day=Wednesday"}) 
--> "Today is Wednesday, the 10/Oct/2012" 

Example 9:

Force the display of an integer as text.

format("'A' is [T]", 65) 
--> `'A' is A` 

See Also:

writef | writefln
sprintf | printf

writef

include std/io.e 
namespace io 
public procedure writef(object fm, object data = {}, object fn = 1, object data_not_string = 0) 

outputs, with flexible options, formatted text to a file or a terminal (console).

Depending on the data-type of the first argument, effectively, two different parameter lists are permitted.

• Start with the output device--the first argument is an integer:

• Start with the format pattern--the first argument is a character sequence:

The [] Inset formatting codes are describe in text.e

General	Select Argument	Text	Numbers	Special
t	I	T	.N	?
s	{id}	w	z
:F	%envvar%	u	:0F
<		l	+
>			(
c			b
[			,G
			X
			B

Example 1

include std/io.e 
 
    -- Simple message to console 
writef("A message") 
    --> A message 
     
    -- Another console message 
writef(STDERR, "This is a []", "message") 
    --> This is a message 

Example 2

-- Outputs two numbers 
 
writef(STDERR, "First [], second []", {65, 100}, 1) 
    --> First 65, second 100 
     
     -- the number sequence {65, 100}  
     -- contains two items 
      
-- Outputs one string 
 
writef(STDERR, "First [], second []", {65, 100}, 0) 
    --> First Ad, second 
 
     -- {65, 100} is equivalent to the character sequence "Ad" 
     -- is one item       

Example 3

    -- Preliminary: get the date 
    include std/datetime.e 
    object dt = date(), Year, MonthName, Day, DayName 
 
    {Year, MonthName, Day, DayName} = {dt[1]+1900, month_names[dt[2]], dt[3], day_names[dt[7]] } 
 
 
-- Output using writef 
     
include std/io.e 
 
-- To console 
writef("Today is [4], [u2:3] [3:02], [1:4].",  
       {Year, MonthName, Day, DayName}) 
    --> Today is Saturday, MAY 03, 2014. 
     
-- To "sample.txt" 
writef("Today is [4], [u2:3] [3:02], [1:4].",  
       {Year, MonthName, Day, DayName}, "sample.txt") 
 
    -- examine the file: sample.txt 
    -->  
    -- Today is Saturday, MAY 03, 2014. 

Example 4

-- Create and write to "sample.log" 
integer dat = open("sample.log", "w") 
writef("Today is [4], [u2:3] [3:02], [1:4].",  
       {Year, MonthName, Day, DayName}, dat) 
close(dat) 
 
 
 
-- Appended to "sample.log" 
writef("\nToday is [4], [u2:3] [3:02], [1:4].",  
       {Year, MonthName, Day, DayName}, {"sample.log", "a"}) 
 
    --  examine the file: "sample.log" 
    -->  
    -- Today is Saturday, MAY 03, 2014. 
    -- Today is Saturday, MAY 03, 2014.