format(data, "formatString")

---

---

format(data,"formatString")

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 data 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 formatString depends on the type of object represented by what. Tinderbox data types Date, Set and Number are handled using different sets of arguments as described below.

From v5.8.0, this function is being supplemented by per-data-type .format() dot operators which are usually more flexible when writing no-trivial code - links to per-data-type dot operators are added below.

DATE-Type Data

If data is a date, the format string is the same as the format used by Tinderbox's date export codes.

format(data,"formatString")

For example:

format($Created,"L") 

gets the note's creation date and formats it as a "long local date" such as "Sunday, 23 March, 2007".

v5.5.0 fixes an issue whereby data per Mac era (1/1/1904) were misinterpreted.

Also use Date.format("formatString").

SET/LIST-Type Data

If data is a Set or (from v5.6.0) a List, the format string is the delimiter used to separate set elements:

format(data,"formatString")

The process preserves original data - duplicate values in lists are maintained. For example

format($KeyAttributes,", ") 

converts key attributes to a comma+space-separated list. To put each item on a separate line use this:

format($KeyAttributes,"\n") 

Thus $Text may be created from concatenation of other texts:

$Text = format(collect(children, $Text),"\n") 

To strip duplicates from a List, don't 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 five arguments to format the set as an HTML list:

format(data,list-prefix,item-prefix,item-suffix,list-suffix)

For example

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:

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

From v5.7.0, use of format() with number data is deprecated in favour of either the Number.precision() or Number.format() operators.

If data is a number, then the arguments are numeric and interpreted as follows:

format(data,precision[, width])

The precision argument controls the number of decimal places returned. The optional width 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 $MyNum is 3.1415927, then

format($MyNum,2,7) is "   3.14" (3 spaces + number + period + 3 numbers = 7)

format($MyNum,2) is 3.14

format($MyNum,0) is 3

format($MyNum,0,2) is '  3' (two left-padding spaces) 

format(5.1415927,2) is 5.14

Note that with widthN, decimal character is not counted as part of the number

From v5.10.3 an alternate number format is offered using a quoted format string:

Number.format("formatString")

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 data is color type, format strings are ignored:

format(color)

The operator returns the colour color in hex form, e.g. "#ff00ff", regardless of whether the stored value is hex or a named Tinderbox colour.

format($MyColor) is "#ff00ff" if $MyColor is "purple"

Also use Color.format().