Operator Type:
Operator Scope of Action:
Operator Purpose:
Operator First Added:
Operator Last Altered:
Operator Has Optional Arguments:
Operator Has Newer Dot-Operator Variant:
Function [other Function type actions]
Item [operators of similar scope]
Formatting [other Formatting operators]
Baseline
As at baseline
[More on optional operator arguments]
Yes
format(dataStr, formatStr[,additionalArguments])
Note: in most cases it is better to use newer .format() dot-operator for this task.
The operator format() converts various Tinderbox objects to strings. In quoted (") string arguments a \"
is converted into a quotation mark (a.k.a. double quote), \n
to a carriage return and \t
to a tab.
The argument dataStr is evaluated, and is usually an attribute reference or expression. An attribute reference can take both short and long forms:
$MySet
(i.e. the current note's $MySet)
$MySet(Test)
(i.e. set $MySet data from note 'Test')
The meaning of formatStr depends on the type of object represented by what. Additionally, number of additionalArguments may be supplied depending on the dataStr data type. Tinderbox data types Date, Set and Number are handled using different sets of arguments as described below.
This function is being supplemented by per-data-type .format() dot operators which are usually more flexible when writing non-trivial code: links to per-data-type dot operators are added below.
DATE-Type Data
If dataStr is a date, the format string is the same as the format used by Tinderbox's date export codes.
format(dataStr, formatStr)
For example:
$MyString = format($Created,"L");
gets the note's creation date and formats it as a "long local date" such as "Sunday, 23 March, 2007".
Also use Date.format("formatString").
SET/LIST-Type Data
If data is a Set or a List, the format string is the delimiter used to separate set elements:
format(data, formatStr)
The process preserves original data; duplicate values in lists are maintained. For example
$MyString = format($DisplayedAttributes,", ");
converts Displayed Attributes to a comma+space-separated list. To put each item on a separate line use this:
$MyString = format($DisplayedAttributes,"\n");
Thus $Text may be created from concatenation of other texts:
$Text = format(collect(children, $Text),"\n");
To strip duplicates from a List, do not use format(). Instead, simply set a Set attribute to the contents of the List attribute (or any function/expression returning List-type data).
Also use List.format("formatString").
Optionally, you may supply formatStr as four discrete arguments to format a list, for example as an HTML list:
format(data,list-prefix,item-prefix,item-suffix,list-suffix)
For example
$MyString = format($Classes,"<ul>","<li>","</li>","</ul>");
will return HTML code for a bulleted list with each set member marked up as a list item. Note that the tags must be in double quotes. To have each element on a separate line and indent the items add tabs and line breaks:
$MyString = format($Classes,"<ul>\n","\t<li>","</li>\n","</ul>\n");
To make this easier to use in a code export context, you might pass the output of format into another attribute and call the latter within the template with a ^value()^ code. By a repeat call to format it is possible to export lists of links.
Also use List.format("listPrefix","itemPrefix","itemSuffix","listSuffix")
NUMBER-Type Data
Use of format() with number data is deprecated in favour of either the Number.precision() or Number.format() operators.
If dataStr is a number, then the arguments are numeric and interpreted as follows:
format(dataStr,precisionNum[, widthNum][,padStr])
The precisionNum argument controls the number of decimal places returned. The optional widthNum argument allows the returned value to be a string left padded with spaces, e.g. to return a string with the same number of characters as submitted.
For example, if $MyNumber is 3.1415927, then
$MyString = format($MyNumber,2,7);
is " 3.14" (3 spaces + number + period + 3 numbers = 7)
$MyString = format($MyNumber,2);
is 3.14
$MyString = format($MyNumber,0);
is 3
$MyString = format($MyNumber,0,2);
is ' 3' (two left-padding spaces)
$MyString = format(5.1415927,2);
is 5.14
Note that with widthNum, decimal character is not counted as part of the number.
If the optional padStr is given, this specifies the character used for padding. The default is a space:
$MyString = format(7,0,3);
gives " 7"
$MyString = 7.format(7,0,3,"0");
gives "007"
$MyString = format(7,0,3,"#");
gives "##7"
An alternate number format is offered using a quoted format string:
Number.format( formatStr)
Currently only one such string is supported "L". This will return a string of the number formatted with (OS) locale-dependent group & decimal delimiters. For example, for the US locale these are a comma and a period; in other locales they may vary.
Also use Number.format(decimalsN,widthN).
COLOR-Type Data
If dataStr is color type, format strings are ignored:
format(colorStr)
The operator returns the colour colorStr in hex form, e.g. "#ff00ff", regardless of whether the stored value is hex or a named Tinderbox colour.
$MyString = format($MyColor)
is "#ff00ff" if $MyColor is "purple"
Also use Color.format().
INTERVAL-Type Data
If data is interval-type, format strings can use date-type format strings. An interval of 00:00 (hours:minutes) is always displayed as an empty string.
Also use Interval.format().