The Yoix^® Scripting Language

A specification that would normally indicate some subset time unit (e.g., minutes in an hour or hours in a day) will expand to assume the full value of that time unit (e.g., total minutes or total hours) if it is the first specification in the format. Thus, the format string "Mm" means that the given value is represented entirely as minutes, but the format string "H:Mm" means that the given value is represented as some number of hours and whatever remaining minutes there may be. To specify just the number of minutes in a given value modulo the hours, for example, the N or n specification can be used, as in: "Nm".

A format string can consist of literal text tokens and specification tokens. A literal text token is any character outside the range [a-z] and [A-Z], or any characters, except a single-quote, enclosed in single-quotes, or two consecutive single-quotes, which are interpreted as a single single-quote in the result. The following characters outside of a literal string have the special meaning indicated.

B or b	blank fill indicator
D or d	days
F or f	fractional seconds, where a width one specification indicates tenths of a second, a width two specification indicates hundredths of a second and a width three specification indicates milliseconds
H or h	hours
M or m	minutes
N or n	null, does not generate output or padding and is mainly ignored except if it is the first specification letter in the format, in which case it removes the distinction of being first from subsequent specifications in the format, which can affect the result that they produce.
S or s	seconds
Z or z	zero fill indicator

The characters for blank and zero fill will be referred to collectively as padding characters with a specific instance represented in what follows by p or P, while the other characters will be referred to collectively as time characters with a specific instance represented in what follows by t or T.

A specification consists of a sequence of zero or more of the same specification character followed by a single specification character according to the following restrictions.

1.	A specification cannot contain only padding characters.
2.	A specification can only contain one type of time specification character.
3.	The initial sequence in the specification must have all characters in the same case (i.e., all upper or all lower).
4.	A lower-case time character sequence can only be followed by the same time character also in lower-case.

When padding is requested, the total number of characters in the sequence determines the number of characters to which the output is padded.

Using the t or T and p or P notation mentioned above, the following list of two-character specifications, where the first character actually represents a sequence of that character, describe the possibilities for a format string.

tt	time specification is always output; padding is not used
pt	time specification is always output; padding is used
Pt	time specification is always output; padding is used only when at least one of the time components larger than this one is non-zero
TT	time specification is output if the value is non-zero and at least one of the time components larger than this one is non-zero; padding not is used;
pT	time specification is output if the value is non-zero and at least one of the time components larger than this one is non-zero; padding is used when there is output;
PT	time specification is output if the value is non-zero and at least one of the time components larger than this one is non-zero; padding is used when there is output and when at least one of the time components larger than this one is non-zero
Tt	time specification is output if the value is non-zero; padding is not used
Tp	time specification is output if the value is non-zero; padding is used when there is output;
TP	time specification is output if the value is non-zero; padding is used when there is output and when at least one of the time components larger than this one is non-zero

As a special case, the format containing the single letter C, either uppercase or lowercase, invokes a special compact format where only the largest non-zero component in terms of days, hours, minutes, seconds or milliseconds is displayed followed by one of d, h, m, s or ms indicating days, hours, minutes, seconds or milliseconds, respectively.

Finally, when the width of a specification exceeds three, in the case of fractional seconds, and two, in all other cases, then the value expressed is the entire time value rounded to and expressed in the requested unit rather than just the portion of the value that falls into the requested unit. The example should illustrate these points.

Example:	The following example shows the effect of different formats in expressing a time value of 46807.517824 seconds. import yoix.stdio.printf; import yoix.system.time; import yoix.util.timerFormat; double t = 46807.517824; printf("Case %2d: %25s: '%s'\n", 1, "(no arg)", timerFormat(t)); printf("Case %2d: %25s: '%s'\n", 2, "D:HH:MM:SS.FFF", timerFormat("D:HH:MM:SS.FFF", t)); printf("Case %2d: %25s: '%s'\n", 3, "D:ZH:ZM:zs.f", timerFormat("D:ZH:ZM:zs.f", t)); printf("Case %2d: %25s: '%s'\n", 4, "D:BH:BM:bs.f", timerFormat("D:BH:BM:bs.f", t)); printf("Case %2d: %25s: '%s'\n", 5, "ZD:ZH:ZM:zs.ff", timerFormat("ZD:ZH:ZM:zs.ff", t)); printf("Case %2d: %25s: '%s'\n", 6, "zD:ZH:ZM:zs.fff", timerFormat("zD:ZH:ZM:zs.fff", t)); printf("Case %2d: %25s: '%s'\n", 7, "zd:ZH:ZM:zs.zzf", timerFormat("zd:ZH:ZM:zs.zzf", t)); printf("Case %2d: %25s: '%s'\n", 8, "d:ZH:ZM:zs.f", timerFormat("d:ZH:ZM:zs.f", t)); printf("Case %2d: %25s: '%s'\n", 9, "Zd:Zh:Zm:Zs.f", timerFormat("Zd:Zh:Zm:Zs.f", t)); printf("Case %2d: %25s: '%s'\n", 10, "ns", timerFormat("ns", t)); printf("Case %2d: %25s: '%s'\n", 11, "ss", timerFormat("ss", t)); printf("Case %2d: %25s: '%s'\n", 12, "sss", timerFormat("sss", t)); printf("Case %2d: %25s: '%s'\n", 13, "nm", timerFormat("nm", t)); printf("Case %2d: %25s: '%s'\n", 14, "mm", timerFormat("mm", t)); printf("Case %2d: %25s: '%s'\n", 15, "mmm", timerFormat("mmm", t)); printf("Case %2d: %25s: '%s'\n", 16, "nd", timerFormat("nd", t)); printf("Case %2d: %25s: '%s'\n", 17, "dd", timerFormat("dd", t)); printf("Case %2d: %25s: '%s'\n", 18, "ddd", timerFormat("ddd", t)); printf("Case %2d: %25s: '%s'\n", 19, "ffff", timerFormat("ffff", t)); printf("Case %2d: %25s: '%s'\n", 20, "=>f ff fff ffff", timerFormat("=>f ff fff ffff", t)); printf("Case %2d: %25s: '%s'\n", 21, "n=>f ff fff ffff", timerFormat("n=>f ff fff ffff", t)); printf("Case %2d: %25s: '%s'\n", 22, "zzzzzzzzzf", timerFormat("zzzzzzzzzf", t)); printf("Case %2d: %25s: '%s'\n", 23, "Hz' hr 'Mz' min 'Sz' sec'", timerFormat("Hz' hr 'Mz' min 'Sz' sec'", t)); printf("Case %2d: %25s: '%s'\n", 24, "c", timerFormat("c", t)); printf("\nFYI: Age of UNIX: %s\n", timerFormat(time())); The results on standard output are: Case 1: (no arg): '13h7.5s' Case 2: D:HH:MM:SS.FFF: '13:0:7.518' Case 3: D:ZH:ZM:zs.f: '13:00:07.5' Case 4: D:BH:BM:bs.f: '13: 0: 7.5' Case 5: ZD:ZH:ZM:zs.ff: '13:00:07.52' Case 6: zD:ZH:ZM:zs.fff: '00:13:00:07.518' Case 7: zd:ZH:ZM:zs.zzf: '00:13:00:07.518' Case 8: d:ZH:ZM:zs.f: '0:13:00:07.5' Case 9: Zd:Zh:Zm:Zs.f: '0:13:00:07.5' Case 10: ns: '7' Case 11: ss: '46807' Case 12: sss: '46808' Case 13: nm: '0' Case 14: mm: '780' Case 15: mmm: '780' Case 16: nd: '0' Case 17: dd: '0' Case 18: ddd: '1' Case 19: ffff: '46807518' Case 20: =>f ff fff ffff: '=>468075 52 518 46807518' Case 21: n=>f ff fff ffff: '=>5 52 518 46807518' Case 22: zzzzzzzzzf: '0046807518' Case 23: Hz' hr 'Mz' min 'Sz' sec': '13 hr 07 sec' Case 24: c: '13h' FYI: Age of UNIX: 11789d17h6m46.6s
Return:	String
See Also:	currentTimeMillis, date, nanoTime, parseDate, parseTimer, sleep, time