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) Argument tail is optional (defaults to SPACE). Argument head is optional (defaults to EMPTY). 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 #], .) Appends a period after a track number if [Track #] is not empty, such as 12. delimit([Date (year)], {, }) Outputs the year surrounded by curly braces, for example 2012.

(Back to top)   (Function index)

FormatBoolean(…)

Formats a boolean (true / false) value in a specified manner.

Description

FormatBoolean(conditional, true string, false string) Argument true string is optional (defaults to true). Argument false string is optional (defaults to false). 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) 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.

(Back to top)   (Function index)

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.

(Back to top)   (Function index)

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.

(Back to top)   (Function index)

FormatNumber(…)

Formats and rounds a number to a specified number of decimal places.

Description

FormatNumber(value, decimal places, label zero, label plural, label singular) Argument decimal places is optional (defaults to 0). Argument label zero is optional (defaults to label plural). Argument label plural is optional (defaults to omitted). Argument label singular is optional (defaults to omitted). 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) 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).

(Back to top)   (Function index)

FormatRange(…)

Formats a value as a range.

Description

FormatRange(value, range size, mode) Argument range size is optional (defaults to 1). Argument mode is optional (defaults to 0). 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: 0 Automatically choose between number / letter grouping 1 Letter grouping 2 Number grouping

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: How to produce 1-based range values.

(Back to top)   (Function index)

Orientation(…)

Outputs the orientation of an image.

Description	Orientation() The Orientation() function outputs a term indicating the orientation of an image file. Available output values: Portrait When height > width. Square When height = width. Landscape When width > height
Examples	if(isequal(orientation(), Square), Square, Rectangle) Outputs Square for square images or Rectangle for portrait and landscape images.

(Back to top)   (Function index)

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. This function can also be used to reduce or remove the current level of padding by specifying a lower number digits than are currently used, or 0 to remove all additional padding.
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. PadNumber(0005, 0) Removes extra padding and outputs 5.

(Back to top)   (Function index)

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 ★★★★.

(Back to top)   (Function index)

RatingStars10(…)

Outputs the value of a 10 star rating field as a number of star characters.

Description	RatingStars10(rating) The RatingStars10() function outputs a given 10 star rating field's value as the equivalent number of black star characters. Note: This function only requires the field name, without the usual square brackets.
Examples	ratingstars10(10 Star Rating) For a file that has a [10 Star Rating] value of 8, return will be ★★★★★★★★.

(Back to top)   (Function index)

Watched(…)

Outputs a formatted video bookmark.

Description

Watched(mode) Argument mode is optional (defaults to 0). The Watched() function outputs a video's bookmark position in a human-readable format, using a specified mode. Available mode values: 0 Output a human-readable watched status. 1 Output a numeric watched value (see Watched Status Values below). 2 Output a watched checkmark ✓ if watched. Available numeric watched status values: -1 File type is not Video 0 Not watched. 1 Partially watched. 2 Entirely watched.

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.

(Back to top)   (Function index)