A format string is a string which may contain <var>format specifiers</var> and <var>escape sequences</var>. Any character which is not part of one of these is treated as a literal character and is copied directly to the output string.
If the value to be formatted is being treated as a date see the <a href="#dates">seperate section below</a> otherwise for format strings which are used with values treated as strings, integers or floating point the <var>format specifiers</var> and <var>escape sequences</var> are those provided in standard ANSI c. The general form of a <var>format specifier</var> is
where <var>type</var> is one of the following characters:
<ul>
d, i - decimal integer
o - unsigned octal
x, X - unsigned hexadecimal
u * not applicable to Zonk *
c * not applicable to Zonk *
s - character string
f - floating-point number
e, E - floating-point number in exponential format
g, G - floating-point number in either fixed decimal or exponential format, whichever is more compact
</ul>
Remember: you must use the appropriate Zonk 'treatas' (# for integer, ~ for floating point) modifier on the variable name corresponding to the format specifier you use, otherwise you will get junk output. For octal and hexadecimal output the modifier should be #. No modifier is required for string output.
Also remember that in <ref ctagv>zonk tagvalue</r> you should only have one <var>format specifier</var> in your format but with <ref cmakt>zonk maketag</r> you should have as many as the number of variables you name.
To output a percent sign use <lit>%%</lit>
<var>width</var> is a number that represents the minimum field for displaying a number. The number is right justified unless z negative is used, in which case the number is left justified. If the value to be output would not fit in the width specified then the width is automatically expanded to the minimum needed, the number is never truncated. Thus is no field width is given, the minimun needed will be used.
The <var>precision</var> after the decimal point will force an integer value to have at least that many digits, using leading zeros if necessary. For a floating-point value it represents the number of decimal places to use.
<var>escape sequences</var> take the general form <lit>\<var>character</var></lit> where <var>character</var> may be
<ul>
n - new line
r - carriage return
\ - backslash
</ul>
<a name="dates"></a><sh>Date formats</sh>
When you request that a variable be treated as a date (using the @ modifier) then you should use a date format string. Again the string may contain <var>format specifiers</var> and <var>escape sequences</var> (as above). Any character which is not part of one of these is treated as a literal character and is copied directly to the output string.
The general form of a date <var>format specifier</var> is
<lit>&[z]<var>twolettercode</var></lit> where <var>twolettercode</var> can be any of
<ul>
SE - Seconds
MI - Minutes
12 - Hours in 12-hour format
24 - Hours in 24-hour format
AM - AM or PM indicator
WE - Weekday name in full
W3 - 3-Character weekday abbreviation
WN - Weekday number (Sunday=0 to Saturday=6)
DY - Day of the month
ST - Ordinal suffix (eg st,nd etc) apropriate for day number
MO - Month name in full
M3 - 3-Character abbreviation of month name
MN - Month number
MR - Month number in Roman numerals
CE - Century
YR - Year within century
WK - Week of year
DN - Day of the year
TZ - Timezone (if known otherwise the empty string)
</ul>
Numerical items are by default output with leading zeros, prefix the code with 'z' to suppress them. 'z' has no effect no textual items but is not faulted.
Date <var>format specifiers</var> are not case sensitive, however there is an additional feature for textual items whereby if the first letter of the <var>twolettercode</var> is in upper case then the textual string will be returned in upper case, otherwise it will be returned in lower case (with initial capital if appropriate).
To insert an '&' use '&&'. An invalid date format specifier is passed to the output string as is.
Some of you my realise that these specifiers are nearly identical to the ones RISC-OS provides. However Zonk does not use the RISC-OS system routines for dates in order that the code is easily portable to Windows and MacOS. One side effect of this is that, at the current time, there is no local language support. All text output is in English.
Before Zonk can output a date format it needs to parse the string value of the variable to try to interpret it as a date. Zonk has a very liberal date parser whereby, if the string can possibly be a date or part of a date, Zonk will treat it as such. Any missing parts are filled in from the current date. Zonk does not always get it right with partial dates especially if they are all numbers but it usually does. Two or three colon-seperated number parts (e.g. 12:34:12) are always treated as a time.
When Zonk encounters a two-digit year it will assume a century of '19' for anything in the range 80-99 and a century of '20' for anything else. Remember though, two digit years are bad...
By default Zonk interprets numeric dates in UK format that is day-month-year however if the date does not make sense that way round (eg 4/24/1999) then Zonk will try the US format month-day-year. However if you would prefer to use US date format there is a switch in the <ref sconf>configuration file</r> which reverses the default behaviour.
If Zonk is unable to understand the date for some reason then the output format will be ignored and you will get an error message instead.
As with date output, there is presently no local language support. Only English is understood for textual parts of the input date.
Remember, if you want the current date and/or time you can use %now, without a format for a default date/time string or as %now@ with a format to output it the way you want.
<sh>Translating between time zones.</sh>
If the input string has a recognisable timezone part (eg. GMT, EST, etc or a numeric offset such as -0800) then you can ask Zonk to convert the time/date to either GMT or your computer's local time. To do this, start the date format string with either <lit>#gmt:</lit> or <lit>#local:</lit> Note that these directives <i>are</i> case sensitive, they must be in lower case and that there must be <i>no whitespace</i> before them e.g.
<lit><zonk tagvalue mydate@ format (#gmt:&24:&mi:&se &tz)></lit>
(in this example &tz will print as GMT and not the original time zone, similarly, if you use <lit>#local:</lit> then &tz will give the zonename that your computer is currently set to)
If there is no timezone part in the input string then no time offset is applied since Zonk has no way of knowing what the zone of the original time is and &tz will return an empty string.
