Formatting Functions
- See also: Expression Language and Function Index
The functions in this section format their arguments in specific ways. Some functions are used for formatting values for better presentation, or according to some format, while other functions work on Media Center internal "raw" data to convert to user-friendly formats.
Certain Media Center fields are used to store values in ways that are internally convenient or efficient. But these field values are not terribly useful or meaningful when used directly.
For example, the Duration field holds values as a number seconds of length, while various Date/Time fields such as Date or Last Played store values as floating point numbers specifying a number of days and fractions of a day since a particular epoch time.
Media Center will generally format fields using the "display" format where necessary, such as in panes, file list columns, or various tools such as the Rename, Move & Copy tool. When a function requires a raw field value, or you want to access a raw field value, by sure to use the raw field format. This is done by appending a ,0 to the field's name inside the brackets, for example [Date Imported,0].
Delimit(…)
- Outputs a value with head/tail strings when value is non-empty.
| Description | Delimit(expression, tail, head)
The Delimit() function outputs the value of expression prepended with a head string and/or appended with a tail string, but only if the value of the expression is non-empty. Nothing is output when the expression evaluates to empty.
|
|---|---|
| Examples | delimit([Track #], .)
delimit([Date (year)], {, })
|
FormatBoolean(…)
- Formats a boolean (true / false) value in a specified manner.
| Description | formatboolean(conditional, true string, false string)
The FormatBoolean() function outputs true string and false string values to represent the 0 or 1 Boolean output resulting from the conditional expression. When the conditional evaluates to 1, the true string will be output, otherwise the false string will be output. Argument true string is optional (defaults to True). Argument false string is optional (defaults to False). |
|---|---|
| Examples | formatboolean(isempty([number plays]), Never Played, Has Been Played)
Returns Never Played when the expression IsEmpty() evaluates to 0, and Has Been Played when it evaluates to 1. formatboolean(math([track #] % 2) Outputs the default True label for odd track numbers, and the default False label for even ones. |
FormatDuration(…)
- Presents a duration of seconds in a reader friendly format.
| Description | formatduration(duration value)
The FormatDuration() function formats a duration value into a friendly format. The duration value argument is expected to be a value representing a number of seconds, typically used for media file duration. Media Center internally stores duration values in seconds. |
|---|---|
| Examples | formatduration([duration,0])
Outputs a friendly display of the duration field. This is the same output shown using the Duration field in a file list. formatduration(600) This will output ten minutes in the format 10:00. |
FormatFileSize(…)
- Presents a number of bytes in a reader friendly format.
| Description | formatfilesize(bytes value)
The FormatFileSize() function formats a bytes value into a friendly format. The bytes value argument is expected to be a value representing a number of bytes, typically used for media file size. Media Center internally stores file size values in bytes. FormatFileSize() will convert those byte values into unitized friendly formats such as 50 bytes, 3.2 KB or 10.4 MB. |
|---|---|
| Examples | formatfilesize([file size,0])
Outputs a friendly format of the file size field. This is the same output shown using the File Size field in a file list. formatfilesize(56123456) Outputs the bytes value 56,123,456 as 53.5 MB. |
FormatNumber(…)
- Formats and rounds a number to a specified number of decimal places.
| Description | formatnumber(value, decimal places, label zero, label plural, label singular)
The FormatNumber() function formats a numeric value to a specified number of decimal places, rounding its value, and optionally outputs value-dependent labels, which can be used to construct more grammatically-correct output. The value can be any numeric value. The decimal places argument specifies the number of digits to be used after the decimal point. Use -1 to output as many decimal places as available. The label selected depends on the original value, not the resulting formatted value. The label zero argument is output instead of a formatted value when the original value is 0. When this label is specified as empty, label plural is used. The label plural argument is appended to the formatted value when the original value is more than 1. The label singular argument is appended to the formatted value when the original value is equal to 1. Note: FormatNumber() will not output additional zero's after the decimal point. In other words, FormatNumber() rounds fractional values, but does not zero fill. Argument decimal places is optional (defaults to 0). Argument label zero is optional (defaults to label plural). Argument label plural is optional (defaults to 0). Argument label singular is optional. |
|---|---|
| Examples | formatnumber([duration,0], 2)
Returns a file's duration (which are in seconds) rounding to two decimal places. formatnumber([number plays,0], 0, Unplayed, Plays, Play) Outputs values in whole number formats (no decimals shown). When the number of plays is 0, the output will be Unplayed. When it is more than one, such as six, outputs 6 Plays. And when the number of plays is one, outputs 1 Play. formatnumber([number plays,0], 0, , Plays, Play) Same as the previous example, but uses the default value for label zero (which is label plural), so that when number of plays is zero, output is 0 Plays. formatnumber([number plays,0], , , , Time) In this example, only label singular argument is specified (as Time), so all other arguments use their defaults values. The output will be 0 when number of plays is zero, 1 Time when number of plays is one, and the actual number of plays for other values (e.g. 6). |
FormatRange(…)
- Formats a value as a range.
| Description | formatrange(value, range size, mode)
The FormatRange() function creates numerical or alphabetic groupings of size range size, and returns the grouping where value falls. Only the first character of value is considered and used. The range size is a numerical value specifying how wide the range should be. Numeric ranges are 0-based. The mode specifies the type of range grouping. Available mode values:
Argument range size is optional (defaults to 1). Argument mode is optional (defaults to 0). | ||||||
|---|---|---|---|---|---|---|---|
| Examples | formatrange([artist], 3, 1)
Outputs the range that the artist's first letter falls within. With a range size of 3 and using mode 1 (letter grouping), ranges will be produced in the form of a-c, d-f, g-i, etc. formatrange([artist]) With range size and mode values left unspecified, default values are used, so automatic range groupings of size 1 are output. Hence, the first character of [artist] will be output. formatrange([bitrate], 100, 2) Numeric range groupings of size 100 will be output, for the value of [bitrate]. Possible outputs are: 0-99, 100-199, 200-299, etc. Additional Examples |
Orientation(…)
- Outputs the orientation of an image.
| Description | orientation()
The Orientation() function outputs one of the following words indicating the orientation of an image file:
| ||||||
|---|---|---|---|---|---|---|---|
| Examples | if(isequal(orientation(), Square), Square, Rectangle)
Outputs Square for square images or Rectangle for portrait and landscape images. |
PadNumber(…)
- Adds leading zeros to any given number====
| Description | padnumber(value, number digits)
The PadNumber() function adds leading zeros to any given number value, producing a value of length number digits. |
|---|---|
| Examples | padnumber([track #], 2)
This will pad the track number with leading zeros sufficient to ensure the output is minimally two digits in length. padnumber(counter(), 4) Outputs 4 digits of zero-padded numbers produced by Counter(). For example, 0001, 0002, 0003, etc. |
RatingStars(…)
- Outputs the value of Rating as a number of star characters.
| Description | ratingstars()
The RatingStars() function outputs the Rating field's value as the equivalent number of black star characters. |
|---|---|
| Examples | ratingstars()
For a file that has a Rating of 4, outputs ★★★★. |
Watched(…)
- Outputs a formatted video bookmark.
| Description | watched(mode)
The Watched() function outputs a video's bookmark position in a human-readable format, using a specified mode. Available mode values:
Watched Status Values
Argument mode is optional (defaults to 0). | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Examples | watched()
Outputs formatted watched status, such as 57% on Sep 25, or Aug 21, or nothing when the video has not been watched. ifelse(compare(watched(1), =, 1), Finish Me, compare(watched(1), =, 2), I'm Done) Outputs Finish Me if the video has been partially watched, and I'm Done when completely watched. |