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. |
---|---|
Examples | formatboolean(isempty([number plays]), Never Played, Has Been Played)
formatboolean(math([track #] % 2)
|
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])
formatduration(600)
|
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])
formatfilesize(56123456)
|
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. |
---|---|
Examples | formatnumber([duration,0], 2)
formatnumber([number plays,0], 0, Unplayed, Plays, Play)
formatnumber([number plays,0], 0, , Plays, Play)
formatnumber([number plays,0], , , , Time)
|
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:
| ||||||
---|---|---|---|---|---|---|---|
Examples | formatrange([artist], 3, 1)
a-c, d-f, g-i, etc. formatrange([artist])
formatrange([bitrate], 100, 2)
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: Available NAME values:
| ||||||||
---|---|---|---|---|---|---|---|---|---|
Examples | EXAMPLE1
EXAMPLE2
EXAMPLE3
EXAMPLE4
|
To insert a table of arguments in the DESCRIPTION, use:
Description | orientation()
| ||||||
---|---|---|---|---|---|---|---|
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. |