Formatting Functions: Difference between revisions

From wiki.jriver.com
Jump to navigation Jump to search
No edit summary
 
(38 intermediate revisions by one other user not shown)
Line 16: Line 16:


{{function description box
{{function description box
| name=NAME
| name=Delimit
| arguments=ARGUMENTS
| arguments=expression, tail, head
| description=
| description=
{{argument optional|tail|SPACE}}
DESCRIPTION
{{argument optional|head|EMPTY}}
The [[#Delimit|Delimit()]] function outputs the value of <i>expression</i> prepended with a <i>head</i> string and/or appended with a <i>tail</i> string, but only if the value of the <i>expression</i> is non-empty. Nothing is output when the <i>expression</i> evaluates to empty.
| examples=
| examples=
'''{{monospace|EXAMPLE1}}'''
'''{{monospace|<nowiki>delimit([Track #], .)</nowiki>}}'''
: Appends a period after a track number if [Track #] is not empty, such as {{monospace|12}}.
: EXAMPLETEXT
'''{{monospace|EXAMPLE2}}'''
'''{{monospace|<nowiki>delimit([Date (year)], {, })</nowiki>}}'''
: Outputs the year surrounded by curly braces, for example {{monospace|2012}}.
: EXAMPLETEXT
'''{{monospace|EXAMPLE3}}'''
: EXAMPLETEXT
'''{{monospace|EXAMPLE4}}'''
: EXAMPLETEXT
}}
}}

<pre>
To insert a table of arguments in the DESCRIPTION, use:
{{subst:argument table preset}}
</pre>

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="Delimit" valign="top"
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>delimit(</b><i>expression</i><b>, </b><i>tail</i><b>, </b><i>head</i><b>)</b></span>
The [[#Delimit|Delimit()]] function outputs the value of <i>expression</i> prepended with a <i>head</i> string and/or appended with a <i>tail</i> string, but only if the value of the <i>expression</i> is non-empty. Nothing is output when the <i>expression</i> evaluates to empty.

Argument <i>tail</i> is optional (defaults to SPACE).

Argument <i>head</i> is optional (defaults to EMPTY).

|- valign="top"
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>delimit([Track #], .)</nowiki></b></span>
<p style="margin-left:20pt;">Appends a period after a track number if [Track #] is not empty, such as <span style="font-family: monospace,monospace; font-size:1em;">12.</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>delimit([Date (year)], {, })</nowiki></b></span>
<p style="margin-left:20pt;">Outputs the year surrounded by curly braces, for example <span style="font-family: monospace,monospace; font-size:1em;">{2012</span>}.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>


=== <span id="FormatBoolean">FormatBoolean(&hellip;)</span> ===
=== <span id="FormatBoolean">FormatBoolean(&hellip;)</span> ===
: Formats a boolean (true / false) value in a specified manner.
: Formats a boolean (true / false) value in a specified manner.


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="FormatBoolean" valign="top"
| name=FormatBoolean
| arguments=conditional, true string, false string
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>formatboolean(</b><i>conditional</i><b>, </b><i>true string</i><b>, </b><i>false string</i><b>)</b></span>
{{argument optional|true string|true}}
The [[#FormatBoolean|FormatBoolean()]] function outputs <i>true string</i> and <i>false string</i> values to represent the 0 or 1 Boolean output resulting from the <i>conditional</i> expression.
{{argument optional|false string|false}}
When the <i>conditional</i> evaluates to 1, the <i>true string</i> will be output, otherwise the <i>false string</i> will be output.
The [[#FormatBoolean|FormatBoolean()]] function outputs <i>true string</i> and <i>false string</i> values to represent the 0 or 1 Boolean output resulting from the <i>conditional</i> expression. When the <i>conditional</i> evaluates to 1, the <i>true string</i> will be output, otherwise the <i>false string</i> will be output.

| examples=
Argument <i>true string</i> is optional (defaults to True).
'''{{monospace|<nowiki>formatboolean(isempty([number plays]), Never Played, Has Been Played)</nowiki>}}'''

: Returns <span style="font-family: monospace,monospace; font-size:1em;">Never Played</span> when the expression [[#IsEmpty|IsEmpty()]] evaluates to 0, and <span style="font-family: monospace,monospace; font-size:1em;">Has Been Played</span> when it evaluates to 1.
Argument <i>false string</i> is optional (defaults to False).
'''{{monospace|<nowiki>formatboolean(math([track #] % 2)</nowiki>}}'''

: Outputs the default True label for odd track numbers, and the default False label for even ones.
|- valign="top"
}}
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatboolean(isempty([number plays]), Never Played, Has Been Played)</nowiki></b></span>
<p style="margin-left:20pt;">Returns <span style="font-family: monospace,monospace; font-size:1em;">Never Played</span> when the expression [[#IsEmpty|IsEmpty()]] evaluates to 0, and <span style="font-family: monospace,monospace; font-size:1em;">Has Been Played</span> when it evaluates to 1.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatboolean(math([track #] % 2)</nowiki></b></span>
<p style="margin-left:20pt;">Outputs the default True label for odd track numbers, and the default False label for even ones.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>


=== <span id="FormatDuration">FormatDuration(&hellip;)</span> ===
=== <span id="FormatDuration">FormatDuration(&hellip;)</span> ===
: Presents a duration of seconds in a reader friendly format.
: Presents a duration of seconds in a reader friendly format.


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="FormatDuration" valign="top"
| name=FormatDuration
| arguments=duration value
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>formatduration(</b><i>duration value</i><b>)</b></span>
The [[#FormatDuration|FormatDuration()]] function formats a <i>duration value</i> into a friendly format.
The [[#FormatDuration|FormatDuration()]] function formats a <i>duration value</i> into a friendly format. The <i>duration value</i> 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=
The <i>duration value</i> argument is expected to be a value representing a number of seconds, typically used for media file duration.
'''{{monospace|<nowiki>formatduration([duration,0])</nowiki>}}'''
Media Center internally stores duration values in seconds.
: Outputs a friendly display of the duration field. This is the same output shown using the Duration field in a file list.
|- valign="top"
'''{{monospace|<nowiki>formatduration(600)</nowiki>}}'''
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatduration([duration,0])</nowiki></b></span>
: This will output ten minutes in the format <span style="font-family: monospace,monospace; font-size:1em;">10:00</span>.
}}
<p style="margin-left:20pt;">Outputs a friendly display of the duration field. This is the same output shown using the Duration field in a file list.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatduration(600)</nowiki></b></span>
<p style="margin-left:20pt;">This will output ten minutes in the format <span style="font-family: monospace,monospace; font-size:1em;">10:00</span>.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>


=== <span id="FormatFileSize">FormatFileSize(&hellip;)</span> ===
=== <span id="FormatFileSize">FormatFileSize(&hellip;)</span> ===
: Presents a number of bytes in a reader friendly format.
: Presents a number of bytes in a reader friendly format.


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="FormatFileSize" valign="top"
| name=FormatFileSize
| arguments=bytes value
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>formatfilesize(</b><i>bytes value</i><b>)</b></span>
The [[#FormatFileSize|FormatFileSize()]] function formats a <i>bytes value</i> into a friendly format.
The [[#FormatFileSize|FormatFileSize()]] function formats a <i>bytes value</i> into a friendly format. The <i>bytes value</i> 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|FormatFileSize()]] will convert those byte values into unitized friendly formats such as 50 bytes, 3.2 KB or 10.4 MB.
| examples=
The <i>bytes value</i> argument is expected to be a value representing a number of bytes, typically used for media file size.
'''{{monospace|<nowiki>formatfilesize([file size,0])</nowiki>}}'''
Media Center internally stores file size values in bytes. [[#FormatFileSize|FormatFileSize()]] will convert those byte values into unitized friendly formats such as 50 bytes, 3.2 KB or 10.4 MB.
: Outputs a friendly format of the file size field. This is the same output shown using the File Size field in a file list.
|- valign="top"
'''{{monospace|<nowiki>formatfilesize(56123456)</nowiki>}}'''
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatfilesize([file size,0])</nowiki></b></span>
: Outputs the <i>bytes value</i> 56,123,456 as <span style="font-family: monospace,monospace; font-size:1em;">53.5 MB</span>.
}}
<p style="margin-left:20pt;">Outputs a friendly format of the file size field. This is the same output shown using the File Size field in a file list.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatfilesize(56123456)</nowiki></b></span>
<p style="margin-left:20pt;">Outputs the <i>bytes value</i> 56,123,456 as <span style="font-family: monospace,monospace; font-size:1em;">53.5 MB</span>.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>


=== <span id="FormatNumber">FormatNumber(&hellip;)</span> ===
=== <span id="FormatNumber">FormatNumber(&hellip;)</span> ===
: Formats and rounds a number to a specified number of decimal places.
: Formats and rounds a number to a specified number of decimal places.


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="FormatNumber" valign="top"
| name=FormatNumber
| arguments=value, decimal places, label zero, label plural, label singular
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>formatnumber(</b><i>value</i><b>, </b><i>decimal places</i><b>, </b><i>label zero</i><b>, </b><i>label plural</i><b>, </b><i>label singular</i><b>)</b></span>
{{argument optional|decimal places|0}}
The [[#FormatNumber|FormatNumber()]] function formats a numeric <i>value</i> to a specified number of <i>decimal places</i>, rounding its <i>value</i>, and optionally outputs <i>value</i>-dependent labels, which can be used to construct more grammatically-correct output.
{{argument optional|label zero|''label plural''}}
The <i>value</i> can be any numeric <i>value</i>.
{{argument optional|label plural|''omitted''}}
The <i>decimal places</i> argument specifies the number of digits to be used after the decimal point. Use -1 to output as many <i>decimal places</i> as available.
{{argument optional|label singular|''omitted''}}
The [[#FormatNumber|FormatNumber()]] function formats a numeric <i>value</i> to a specified number of <i>decimal places</i>, rounding its <i>value</i>, and optionally outputs <i>value</i>-dependent labels, which can be used to construct more grammatically-correct output. The <i>value</i> can be any numeric <i>value</i>. The <i>decimal places</i> argument specifies the number of digits to be used after the decimal point. Use -1 to output as many <i>decimal places</i> as available.


The label selected depends on the original <i>value</i>, not the resulting formatted <i>value</i>.
The label selected depends on the original <i>value</i>, not the resulting formatted <i>value</i>.


The <i>label zero</i> argument is output instead of a formatted <i>value</i> when the original <i>value</i> is 0. When this label is specified as empty, <i>label plural</i> is used.
The <i>label zero</i> argument is output instead of a formatted <i>value</i> when the original <i>value</i> is 0. When this label is specified as empty, <i>label plural</i> is used. The <i>label plural</i> argument is appended to the formatted <i>value</i> when the original <i>value</i> is more than 1. The <i>label singular</i> argument is appended to the formatted <i>value</i> when the original <i>value</i> is equal to 1.
The <i>label plural</i> argument is appended to the formatted <i>value</i> when the original <i>value</i> is more than 1.
The <i>label singular</i> argument is appended to the formatted <i>value</i> when the original <i>value</i> is equal to 1.


Note: [[#FormatNumber|FormatNumber()]] will not output additional zero's after the decimal point. In other words, [[#FormatNumber|FormatNumber()]] rounds fractional values, but does not zero fill.
'''''Note''''': [[#FormatNumber|FormatNumber()]] will not output additional zero's after the decimal point. In other words, [[#FormatNumber|FormatNumber()]] rounds fractional values, but does not zero fill.
| examples=

'''{{monospace|<nowiki>formatnumber([duration,0], 2)</nowiki>}}'''
Argument <i>decimal places</i> is optional (defaults to 0).
: Returns a file's duration (which are in seconds) rounding to two <i>decimal places</i>.

'''{{monospace|<nowiki>formatnumber([number plays,0], 0, Unplayed, Plays, Play)</nowiki>}}'''
Argument <i>label zero</i> is optional (defaults to <i>label plural</i>).
: Outputs values in whole number formats (no decimals shown). When the number of plays is 0, the output will be <span style="font-family: monospace,monospace; font-size:1em;">Unplayed</span>. When it is more than one, such as six, outputs <span style="font-family: monospace,monospace; font-size:1em;">6 Plays</span>. And when the number of plays is one, outputs <span style="font-family: monospace,monospace; font-size:1em;">1 Play</span>.

'''{{monospace|<nowiki>formatnumber([number plays,0], 0, , Plays, Play)</nowiki>}}'''
Argument <i>label plural</i> is optional (defaults to 0).
: Same as the previous example, but uses the default <i>value</i> for <i>label zero</i> (which is <i>label plural</i>), so that when number of plays is zero, output is <span style="font-family: monospace,monospace; font-size:1em;">0 Plays</span>.

'''{{monospace|<nowiki>formatnumber([number plays,0], , , , Time)</nowiki>}}'''
Argument <i>label singular</i> is optional.
: In this example, only <i>label singular</i> argument is specified (as <span style="font-family: monospace,monospace; font-size:1em;">Time</span>), so all other arguments use their defaults values. The output will be <span style="font-family: monospace,monospace; font-size:1em;">0</span> when number of plays is zero, <span style="font-family: monospace,monospace; font-size:1em;">1 Time</span> when number of plays is one, and the actual number of plays for other values (e.g. <span style="font-family: monospace,monospace; font-size:1em;">6</span>).

}}
|- valign="top"
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatnumber([duration,0], 2)</nowiki></b></span>
<p style="margin-left:20pt;">Returns a file's duration (which are in seconds) rounding to two <i>decimal places</i>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatnumber([number plays,0], 0, Unplayed, Plays, Play)</nowiki></b></span>
<p style="margin-left:20pt;">Outputs values in whole number formats (no decimals shown). When the number of plays is 0, the output will be <span style="font-family: monospace,monospace; font-size:1em;">Unplayed</span>.
When it is more than one, such as six, outputs <span style="font-family: monospace,monospace; font-size:1em;">6 Plays</span>.
And when the number of plays is one, outputs <span style="font-family: monospace,monospace; font-size:1em;">1 Play</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatnumber([number plays,0], 0, , Plays, Play)</nowiki></b></span>
<p style="margin-left:20pt;">Same as the previous example, but uses the default <i>value</i> for <i>label zero</i> (which is <i>label plural</i>), so that when number of plays is zero, output is <span style="font-family: monospace,monospace; font-size:1em;">0 Plays</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatnumber([number plays,0], , , , Time)</nowiki></b></span>
<p style="margin-left:20pt;">In this example, only <i>label singular</i> argument is specified (as <span style="font-family: monospace,monospace; font-size:1em;">Time</span>), so all other arguments use their defaults values.
The output will be <span style="font-family: monospace,monospace; font-size:1em;">0</span> when number of plays is zero, <span style="font-family: monospace,monospace; font-size:1em;">1 Time</span> when number of plays is one, and the actual number of plays for other values (e.g. <span style="font-family: monospace,monospace; font-size:1em;">6</span>).</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>


=== <span id="FormatRange">FormatRange(&hellip;)</span> ===
=== <span id="FormatRange">FormatRange(&hellip;)</span> ===
: Formats a value as a range.
: Formats a value as a range.


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="FormatRange" valign="top"
| name=FormatRange
| arguments=value, range size, mode
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>formatrange(</b><i>value</i><b>, </b><i>range size</i><b>, </b><i>mode</i><b>)</b></span>
{{argument optional|range size|1}}
The [[#FormatRange|FormatRange()]] function creates numerical or alphabetic groupings of size <i>range size</i>, and returns the grouping where <i>value</i> falls.
{{argument optional}}
Only the first character of <i>value</i> is considered and used.
The <i>range size</i> is a numerical <i>value</i> specifying how wide the range should be. Numeric ranges are 0-based.
The [[#FormatRange|FormatRange()]] function creates numerical or alphabetic groupings of size <i>range size</i>, and returns the grouping where <i>value</i> falls. Only the first character of <i>value</i> is considered and used. The <i>range size</i> is a numerical <i>value</i> specifying how wide the range should be. Numeric ranges are 0-based. The <i>mode</i> specifies the type of range grouping.
The <i>mode</i> specifies the type of range grouping.


{{argument table
Available <i>mode</i> values:
| name=mode

| contents=
<div style="margin-left: 0pt;"><table style="border-spacing:0px; border-collapse:collapse; background: #f9f9f9">
<tr><td style="text-align:left; padding-right:20pt"><b>0</b></td><td>Automatically choose between number / letter grouping</td></tr>
{{argument table row|0|Automatically choose between number / letter grouping}}
{{argument table row|1|Letter grouping}}
<tr><td style="text-align:left; padding-right:20pt"><b> 1</b></td><td>Letter grouping</td></tr>
{{argument table row|2|Number grouping}}
<tr><td style="text-align:left; padding-right:20pt"><b> 2</b></td><td>Number grouping</td></tr>
}}
</table></div>
| examples=

'''{{monospace|<nowiki>formatrange([artist], 3, 1)</nowiki>}}'''
Argument <i>range size</i> is optional (defaults to 1).
: Outputs the range that the artist's first letter falls within. With a <i>range size</i> of 3 and using <i>mode</i> 1 (letter grouping), ranges will be produced in the form of

<span style="font-family: monospace,monospace; font-size:1em;">a-c</span>, <span style="font-family: monospace,monospace; font-size:1em;">d-f</span>, <span style="font-family: monospace,monospace; font-size:1em;">g-i</span>, etc.
Argument <i>mode</i> is optional (defaults to 0).
'''{{monospace|<nowiki>formatrange([artist])</nowiki>}}'''

: With <i>range size</i> and <i>mode</i> 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.
|- valign="top"
'''{{monospace|<nowiki>formatrange([bitrate], 100, 2)</nowiki>}}'''
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatrange([artist], 3, 1)</nowiki></b></span>
: Numeric range groupings of size 100 will be output, for the <i>value</i> of <span style="font-family: monospace,monospace; font-size:1em;">[bitrate]</span>. Possible outputs are: <span style="font-family: monospace,monospace; font-size:1em;">0-99</span>, <span style="font-family: monospace,monospace; font-size:1em;">100-199</span>, <span style="font-family: monospace,monospace; font-size:1em;">200-299</span>, etc.
'''Additional Examples:'''
<p style="margin-left:20pt;">Outputs the range that the artist's first letter falls within.
* [http://wiki.jriver.com/index.php/CD_Reference_Number How to produce 1-based range values.]
With a <i>range size</i> of 3 and using <i>mode</i> 1 (letter grouping), ranges will be produced in the form of
}}
<span style="font-family: monospace,monospace; font-size:1em;">a-c</span>, <span style="font-family: monospace,monospace; font-size:1em;">d-f</span>, <span style="font-family: monospace,monospace; font-size:1em;">g-i</span>, etc.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatrange([artist])</nowiki></b></span>
<p style="margin-left:20pt;">With <i>range size</i> and <i>mode</i> 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.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatrange([bitrate], 100, 2)</nowiki></b></span>
<p style="margin-left:20pt;">Numeric range groupings of size 100 will be output, for the <i>value</i> of <span style="font-family: monospace,monospace; font-size:1em;">[bitrate]</span>. Possible outputs are: <span style="font-family: monospace,monospace; font-size:1em;">0-99</span>, <span style="font-family: monospace,monospace; font-size:1em;">100-199</span>, <span style="font-family: monospace,monospace; font-size:1em;">200-299</span>, etc.</p>

Additional Examples

:[http://wiki.jriver.com/index.php/CD_Reference_Number How to produce 1-based range values.]
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>


=== <span id="Orientation">Orientation(&hellip;)</span> ===
=== <span id="Orientation">Orientation(&hellip;)</span> ===
: Outputs the orientation of an image.
: Outputs the orientation of an image.


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="Orientation" valign="top"
| name=Orientation
| arguments=
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>orientation(</b><b>)</b></span>
The [[#Orientation|Orientation()]] function outputs one of the following words indicating the orientation of an image file:
The [[#Orientation|Orientation()]] function outputs a term indicating the orientation of an image file. {{argument table
| name=output

| contents=
<div style="margin-left: 20pt;"><table style="border-spacing:0px; border-collapse:collapse; background: #f9f9f9">
<tr><td style="text-align:left; padding-right:20pt">Portrait</td><td>When height > width</td></tr>
{{argument table row|Portrait|When height > width.}}
{{argument table row|Square|<nowiki>When height = width.</nowiki>}}
<tr><td style="text-align:left; padding-right:20pt">Landscape</td><td>When width > height</td></tr>
{{argument table row|Landscape|When width > height}}
<tr><td style="text-align:left; padding-right:20pt">Portrait</td><td>When height = width</td></tr>
}}
</table></div>
| examples=
|- valign="top"
'''{{monospace|<nowiki>if(isequal(orientation(), Square), Square, Rectangle)</nowiki>}}'''
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>if(isequal(orientation(), Square), Square, Rectangle)</nowiki></b></span>
: Outputs <span style="font-family: monospace,monospace; font-size:1em;">Square</span> for square images or <span style="font-family: monospace,monospace; font-size:1em;">Rectangle</span> for portrait and landscape images.
}}
<p style="margin-left:20pt;">Outputs <span style="font-family: monospace,monospace; font-size:1em;">Square</span> for square images or <span style="font-family: monospace,monospace; font-size:1em;">Rectangle</span> for portrait and landscape images.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>


=== <span id="PadNumber">PadNumber(&hellip;)</span> ===
=== <span id="PadNumber">PadNumber(&hellip;)</span> ===
: Adds leading zeros to any given number====
: Adds leading zeros to any given number


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="PadNumber" valign="top"
| name=PadNumber
| arguments=value, number digits
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>padnumber(</b><i>value</i><b>, </b><i>number digits</i><b>)</b></span>
The [[#PadNumber|PadNumber()]] function adds leading zeros to any given number <i>value</i>, producing a <i>value</i> of length <i>number digits</i>.
The [[#PadNumber|PadNumber()]] function adds leading zeros to any given number <i>value</i>, producing a <i>value</i> of length <i>number digits</i>. 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=
|- valign="top"
'''{{monospace|<nowiki>padnumber([track #], 2)</nowiki>}}'''
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
: This will pad the track number with leading zeros sufficient to ensure the output is minimally two digits in length.
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>padnumber([track #], 2)</nowiki></b></span>
'''{{monospace|<nowiki>padnumber(counter(), 4)</nowiki>}}'''
<p style="margin-left:20pt;">This will pad the track number with leading zeros sufficient to ensure the output is minimally two digits in length.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>padnumber(counter(), 4)</nowiki></b></span>
: Outputs 4 digits of zero-padded numbers produced by [[Counter()]]. For example, <span style="font-family: monospace,monospace; font-size:1em;">0001</span>, <span style="font-family: monospace,monospace; font-size:1em;">0002</span>, <span style="font-family: monospace,monospace; font-size:1em;">0003</span>, etc.
'''{{monospace|PadNumber(0005, 0)}}'''
<p style="margin-left:20pt;">Outputs 4 digits of zero-padded numbers produced by [[#Counter|Counter()]]. For example, <span style="font-family: monospace,monospace; font-size:1em;">0001</span>, <span style="font-family: monospace,monospace; font-size:1em;">0002</span>, <span style="font-family: monospace,monospace; font-size:1em;">0003</span>,
: Removes extra padding and outputs {{monospace|5}}.
etc.</p>
|}
}}
<div style="text-align:right;">([[#top|Back to top)]]</div>


=== <span id="RatingStars">RatingStars(&hellip;)</span> ===
=== <span id="RatingStars">RatingStars(&hellip;)</span> ===
: Outputs the value of Rating as a number of star characters.
: Outputs the value of Rating as a number of star characters.


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="RatingStars" valign="top"
| name=RatingStars
| arguments=
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>ratingstars(</b><b>)</b></span>
The [[#RatingStars|RatingStars()]] function outputs the Rating field's value as the equivalent number of black star characters.
The [[#RatingStars|RatingStars()]] function outputs the Rating field's value as the equivalent number of black star characters.
| examples=
|- valign="top"
'''{{monospace|<nowiki>ratingstars()</nowiki>}}'''
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
: For a file that has a Rating of 4, outputs &#9733;&#9733;&#9733;&#9733;.
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>ratingstars()</nowiki></b></span>
}}
<p style="margin-left:20pt;">For a file that has a Rating of 4, outputs &#9733;&#9733;&#9733;&#9733;.</p>

|}
=== <span id="RatingStars10">RatingStars10(&hellip;)</span> ===
<div style="text-align:right;">([[#top|Back to top)]]</div>
: Outputs the value of a 10 star rating field as a number of star characters.

{{function description box
| name=RatingStars10
| arguments=rating
| description=
The [[#RatingStars10|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=
'''{{monospace|<nowiki>ratingstars10(10 Star Rating)</nowiki>}}'''
: For a file that has a <nowiki>[10 Star Rating]</nowiki> value of 8, return will be &#9733;&#9733;&#9733;&#9733;&#9733;&#9733;&#9733;&#9733;.
}}


=== <span id="Watched">Watched(&hellip;)</span> ===
=== <span id="Watched">Watched(&hellip;)</span> ===
: Outputs a formatted video bookmark.
: Outputs a formatted video bookmark.


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="Watched" valign="top"
| name=Watched
| arguments=mode
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>watched(</b><i>mode</i><b>)</b></span>
{{argument optional}}
The [[#Watched|Watched()]] function outputs a video's bookmark position in a human-readable format, using a specified <i>mode</i>.
The [[#Watched|Watched()]] function outputs a video's bookmark position in a human-readable format, using a specified <i>mode</i>.


{{argument table
Available <i>mode</i> values:
| name=mode

| contents=
<div style="margin-left: 20pt;"><table style="border-spacing:0px; border-collapse:collapse; background: #f9f9f9">
<tr><td style="text-align:left; padding-right:20pt"><b>0</b></td><td>Output a human-readable watched status.</td></tr>
{{argument table row|0|Output a human-readable watched status.}}
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Output a numeric watched value (see Watched Status Values below)</td></tr>
{{argument table row|1|Output a numeric watched value (see Watched Status Values below).}}
<tr><td style="text-align:left; padding-right:20pt"><b>2</b></td><td>Output a watched checkmark &#x2713; if watched</td></tr>
{{argument table row|2|Output a watched checkmark &#x2713; if watched.}}
}}
</table></div>
{{argument table

| name=numeric watched status
Watched Status Values
| contents=
<div style="margin-left: 20pt;"><table style="border-spacing:0px; border-collapse:collapse; background: #f9f9f9">
<tr><td style="text-align:left; padding-right:20pt">-1</td><td>File type is not Video</td></tr>
{{argument table row|-1|File type is not Video}}
{{argument table row|0|Not watched.}}
<tr><td style="text-align:left; padding-right:20pt">0</td><td>Not watched</td></tr>
<tr><td style="text-align:left; padding-right:20pt">1</td><td>Partially watched</td></tr>
{{argument table row|1|Partially watched.}}
<tr><td style="text-align:left; padding-right:20pt">2</td><td>Entirely watched</td></tr>
{{argument table row|2|Entirely watched.}}
}}
</table></div>
| examples=

'''{{monospace|<nowiki>watched()</nowiki>}}'''
Argument <i>mode</i> is optional (defaults to 0).
: Outputs formatted watched status, such as <span style="font-family: monospace,monospace; font-size:1em;">57% on Sep 25</span>, or <span style="font-family: monospace,monospace; font-size:1em;">Aug 21</span>, or nothing when the video has not been watched.

'''{{monospace|<nowiki>ifelse(compare(watched(1), =, 1), Finish Me, compare(watched(1), =, 2), I'm Done)</nowiki>}}'''
|- valign="top"
: Outputs <span style="font-family: monospace,monospace; font-size:1em;">Finish Me</span> if the video has been partially watched, and <span style="font-family: monospace,monospace; font-size:1em;">I'm Done</span> when completely watched.
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
}}
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>watched()</nowiki></b></span>
<p style="margin-left:20pt;">Outputs formatted watched status, such as <span style="font-family: monospace,monospace; font-size:1em;">57% on Sep 25</span>, or <span style="font-family: monospace,monospace; font-size:1em;">Aug 21</span>, or nothing when the video has not been watched.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>ifelse(compare(watched(1), =, 1), Finish Me, compare(watched(1), =, 2), I'm Done)</nowiki></b></span>
<p style="margin-left:20pt;">Outputs <span style="font-family: monospace,monospace; font-size:1em;">Finish Me</span> if the video has been partially watched, and <span style="font-family: monospace,monospace; font-size:1em;">I'm Done</span> when completely watched.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

Latest revision as of 12:40, 11 July 2020

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:

0Automatically choose between number / letter grouping
1Letter grouping
2Number 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:

(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:

PortraitWhen height > width.
SquareWhen height = width.
LandscapeWhen 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:

0Output a human-readable watched status.
1Output a numeric watched value (see Watched Status Values below).
2Output a watched checkmark ✓ if watched.

Available numeric watched status values:

-1File type is not Video
0Not watched.
1Partially watched.
2Entirely 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)