Function Index: Difference between revisions

From wiki.jriver.com
Jump to navigation Jump to search
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
#redirect [[Expression_Language#Function_Index]]
{{Function Type Page}}


[[Category:Expression Language]]
The functions in this section access field values, store and load global variables,
access file tags, and access note fields.

=== <span id="Field">Field(&hellip;)</span> ===
:Returns a field's value.

{{function description box
| name=Field
| arguments=name, mode
| description=
{{argument optional|mode|1}}
The [[#Field|Field()]] function returns the value stored in field <i>name</i>.
The format of return is selected by <i>mode</i>.

{{argument table
| name=mode
| contents=
{{argument table row|0|Raw, unformatted data}}
{{argument table row|1|Formatted data}}
}}
| examples=
'''{{monospace|field(album)}}'''
: Returns the formatted value of field <i>name</i> {{monospace|album}}. Note that this is equivalent to {{Monospace|[album]}}.
'''{{monospace|field(date, 0)}}'''
: Returns the raw, unformatted value stored in the {{monospace|date}} field. Note that this is equivalent to {{monospace|[date,0]}}.
}}

=== <span id="Load">Load(&hellip;)</span> ===
:Outputs the value of a global variable.

{{function description box
| name=Load
| arguments=varname
| description=
Loads and outputs the value of the specified global variable <i>varname</i> that has been previously stored with [[#Save|Save()]].
| examples=
'''{{monospace|load(var1)}}'''
: Loads and outputs the previous stored value of the global variable named {{monospace|var1}}.
'''{{monospace|save(math(1 + 2), sum)load(sum)}}'''
: Saves the output of the [[#Math|Math()]] function into {{monospace|sum}}, and then loads and outputs the value of {{monospace|sum}}, which is {{monospace|3}}.
}}

=== <span id="Note">Note(&hellip;)</span> ===
:Retrieve note fields.

{{function description box
| name=Note
| arguments=field label, field type, occurrence
| description=
{{argument optional|field type|FIRST AVAILABLE}}
{{argument optional|occurrence|0}}
The [[#Note|Note()]] function retrieves information from a Media Center Note.
Specifically, it returns the contents associated with a <i>field label</i>, of a given <i>field type</i>.
The Nth <i>occurrence</i> may be requested.
Notes data may be simple text, or associated with defined a <i>field label</i>.
Currently the only type of <i>field label</i> is contact information.
The first line of a Note is associated with the omnipresent <i>field label</i> <span style="font-family: monospace,monospace; font-size:1em;">Name</span>.

The <i>field type</i> selects the specific sub-type for a given <i>field label</i>, and <i>occurrence</i> selects which instance of
several <i>field label</i> / <i>field type</i> pairs is returned. The <i>occurrence</i> value is zero-based.
| examples=
'''{{monospace|note(phone)}}'''
: Returns the value found in the first {{monospace|Phone}} <i>field label</i>. If no {{monospace|Phone}} label exists, nothing is returned.
'''{{monospace|note(phone, home)}}'''
: Returns the value found in the first {{monospace|Home}} <i>field type</i> from the {{monospace|Phone}} <i>field label</i>. If the {{monospace|Phone}} label, {{monospace|Home}} type does not exists, nothing is returned.
'''{{monospace|note(phone, home)}}'''
: Returns the value found in the first {{monospace|Home}} <i>field type</i> from the {{monospace|Phone}} <i>field label</i>. If the {{monospace|Phone}} label, {{monospace|Home}} type does not exists, nothing is returned.
'''{{monospace|note(phone, home, 1))}}'''
: Same as the previous example, but the second instance of the <i>field type</i> is selected instead of the first, since <i>occurrence</i> is zero-based.
}}

=== <span id="Save">Save(&hellip;)</span> ===
:Saves a value to a global variable.

{{function description box
| name=Save
| arguments=value, variable, mode
| description=
{{argument optional|mode|0}}
This [[#Save|Save()]] function saves the <i>value</i> into the specified global <i>variable</i>, and optionally will return that <i>value</i> if <i>mode</i> is set.
Once a global <i>variable</i> has been created using [[#Save|Save()]], that <i>variable</i>'s <i>value</i> is available for use with either [[#Load|Load()]] or the pseudo-field "[<i>variable</i>]".

{{argument table
| name=mode
| contents=
{{argument table row|0|Suppress output}}
{{argument table row|1|Output variables <i>value</i>}}
}}
| examples=
'''{{monospace|save(Much Money, local_bank)}}'''
: Saves the <i>value</i> {{monospace|Much Money}} into the global <i>variable</i> {{monospace|local_bank}}.
'''{{monospace|save(More Money, My Bank, 1)}}'''
: Saves {{monospace|More Money}} into {{monospace|My Bank}} and outputs the variables <i>value</i> {{monospace|More Money}}.
'''{{monospace|save(math([duration,0] / 60), durmins)if(compare([durmins], &gt;, 5.0), Long Track, Short Track)}}'''
: Saves the calculated duration in minutes into the <i>variable</i> {{monospace|durmins}}. Notice that subsequent expressions fragments such as the {{monospace|if(compare()...)}} may now use the pseudo-field {{monospace|[durmins]}} as shorthand for {{monospace|load(durmins)}}.
Additional Examples
:[http://yabb.jriver.com/interact/index.php?topic=77826.0 Generating statistics]
:[http://yabb.jriver.com/interact/index.php?topic=76581.msg518902#msg518902 Generating album track count]
:[http://yabb.jriver.com/interact/index.php?topic=72049.0 Generating album ratings]
:[http://yabb.jriver.com/interact/index.php?topic=74116.0 Highlighting playing album]
:[http://yabb.jriver.com/interact/index.php?topic=90504.0 Expand a sublist into a superset]
}}

=== <span id="SaveAdd">SaveAdd(&hellip;)</span> ===
: Adds to a global variable.

{{function description box
| name=SaveAdd
| arguments=variable, value, mode
| description=
{{argument optional}}
The [[#SaveAdd|SaveAdd()]] function adds <i>value</i> to a global <i>variable</i> either numerically or as a list item.
The <i>mode</i> argument indicates how <i>variable</i> is modified.

{{argument table
| name=mode
| contents=
{{argument table row|0|Add numeric <i>value</i> (integer or decimal) to <i>variable</i>}}
{{argument table row|1|Append string <i>value</i> as a list item to <i>variable</i>}}
{{argument table row|2|Prepend string <i>value</i> as a list item to <i>variable</i>}}
}}
| examples=
'''{{monospace|saveadd(v, 1)}}'''
: Numerically increments the global <i>variable</i> {{monospace|v}} by {{monospace|1}}.
'''{{monospace|saveadd(v, math(2 - 6))}}'''
: Numerically increments the global <i>variable</i> {{monospace|v}} by the outcome of the [[#Math|Math()]], which is {{monospace|-4}}.
'''{{monospace|load(foo, v)saveadd(v, bar, 1)load(v)}}'''
: Loads <i>value</i> {{monospace|foo}} into <i>variable</i> {{monospace|v}}, then appends the <i>value</i> {{monospace|bar}} as a list item, and the final {{monospace|load(v)}} expression outputs the result of {{monospace|foo; bar}}.
'''{{monospace|load(That, v)saveadd(v, This, 2)load(v)}}'''
: Similar to the previous example, but using the prepend <i>mode</i>, resulting in the output {{monospace|This; That}}.
}}

=== <span id="Tag">Tag(&hellip;)</span> ===
: Returns a file's physical tag.

{{function description box
| name=Tag
| arguments=tag name
| description=
The [[#Tag|Tag()]] function reads and returns the value of <i>tag name</i> directly from a file. The Media Center Library database is not used with [[#Tag|Tag()]], and instead the specified file is read for the requested tag. The spelling and letter case of the <i>tag name</i> must match exactly those stored in the file. ''Performance note'': This function must open and read the actual file, so its performance is significantly slower than other functions which operate on database fields.
| examples=
'''{{monospace|tag(My Personal Tag)}}'''
: This will return the value from the tag named {{monospace|My Personal Tag}} from file referenced by the {{monospace|[filename]}} field.
'''{{monospace|tag(Gapless Header)}}'''
: Returns the {{monospace|Gapless Header}} tag value, often contained in an mp3 file.
'''{{monospace|tag(exif: Date)}}'''
: Returns the raw date data from the EXIF data saved inside a jpg file.
}}


{{Function Type Page}}

The functions in this section test one or more arguments to produce either a true or false outcome, and execute specific actions depending upon that result.

The expression language does not directly support AND, OR, and XOR operations.
However, these can be easily emulated using any of several techniques. See: [[Boolean Operations]].

The NOT operator {{monospace|<b>!</b>}} (exclamation point) may be used in a conditional to invert the sense of the conditional test. Inverting the sense of a test can make reading expressions easier, or support better [[#IfElse|IfElse()]] sequences.

=== <span id="If">If(&hellip;)</span> ===
: Conditional if-else evaluator.

{{function description box
| name=If
| arguments=test expression, true expression, false expression
| description=
The [[#If|If()]] function is used to evaluate a <i>test expression</i>, and will output the result of the <i>true expression</i> or <i>false expression</i>, depending upon the evaluation result. The <i>test expression</i> is expected to return a 0 (false value) or a non-zero (true value). Nesting is allowed. If the <i>test expression</i> is preceded by the NOT operator (!, an exclamation point), the sense of the test is inverted. Non-zero values are inverted to 0, and 0 is inverted to 1.
| examples=
'''{{monospace|if(isequal([artist], bob dylan, 1), Genius, Mediocre)}}'''
: Outputs {{monospace|Genius}} when artist is (case insensitive) Bob Dylan and {{monospace|Mediocre}} otherwise.
'''{{monospace|if(isequal([artist], bob dylan, 1), Genius, if(isequal([album], Joshua Tree, 8), Great Album, Mediocre))}}'''
: This nested [[#If|If()]] expression expands on the previous example, by first evaluating if the artist is Bob Dylan, and outputs {{monospace|Genius}} if true. When the artist is not Bob Dylan, the album is then tested to see if it is {{monospace|Joshua Tree}}, and if so outputs {{monospace|Great Album}}, otherwise outputs {{monospace|Mediocre}}.
'''{{monospace|if(!isempty([comment]), regex([comment], /#^(\\S+\\s+\\S+\\s+\\S+)#/, 1), *No Comment)}}'''
: Outputs the first three words of the comment field; otherwise, outputs *No Comment. By using the NOT operator, the sense of the conditional is inverted so that the more interesting case is moved ahead of the more mundane case.
}}

=== <span id="IfElse">IfElse(&hellip;)</span> ===
: Conditional if-elseif evaluator.

{{function description box
| name=IfElse
| arguments=test1, action1, test2, action2, test3, action3, &hellip;
| description=
The [[#IfElse|IfElse()]] conditional provides a convenient mechanism for shortening and more clearly expressing nested conditionals into an alternating sequence of tests and actions. One or more test/action pairs may be specified.

For example, consider a nested sequence of [[#If|If()]] tests such as the following pseudo-code:
<code>
:: if (test1)
::: action1
:: else if (test2)
::: action2
:: else if (test3)
::: action3
</code>

The [[#IfElse|IfElse()]] statement may be used to more cleanly express the flow of expression by removing the superfluous internal [[#If|If()]] statements, converting the clumsy expression:

: {{monospace|if(<i>test1</i>, <i>action1</i>, if(<i>test2</i>, <i>action2</i>, if(<i>test3</i>, <i>action3</i>)))}}

into the more elegant:

: {{monospace|ifelse(<i>test1</i>, <i>action1</i>, <i>test2</i>, <i>action2</i>, <i>test3</i>, <i>action3</i>)}}

If any of the test expressions <i>test1</i>, etc. are preceded by the NOT operator (!, an exclamation point), the sense of that test is inverted. Non-zero values are inverted to 0, and 0 is inverted to 1.
| examples=
'''{{monospace|ifelse(isequal([media type], Audio), Le Tunes, isequal([media type], Video), Flix)}}'''
: If media type is audio, outputs {{monospace|Le Tunes}}, else if media type is video, outputs {{monospace|Flix}}.
'''{{monospace|ifelse(isequal([artist], Bob Dylan), Genius, isequal([album], Joshua Tree, 8), Great Album, 1, Mediocre)}}'''
: This example, implements the nested if statements from the If() section above, first testing if the artist is Bob Dylan, and if true, outputs {{monospace|Genius}}, otherwise evaluates the second test to determine if the album is {{monospace|Joshua Tree}}, and if true, outputs {{monospace|Great Album}}, otherwise, performs a final test, in this case a degenerate test of 1 (and 1 is always true), thus outputting the value {{monospace|Mediocre}}.
}}

=== <span id="FirstNotEmpty">FirstNotEmpty(&hellip;)</span> ===
: Returns the first non-empty argument.

{{function description box
| name=FirstNotEmpty
| arguments=value1, value2, &hellip;
| description=
The [[#FirstNotEmpty|FirstNotEmpty()]] function acts as a conditional by returning the first argument from <i>value1</i>, <i>value2</i>, ... that is not empty.
Two or more arguments may be used, and the first non-empty argument is returned. With two arguments, is is functionally equivalent to the sequence such as {{monospace|if(!isempty(<i>value1</i>), <i>value1</i>, <i>value2</i>)}}. With more than two arguments, [[#FirstNotEmpty|FirstNotEmpty()]] avoids long nested [[#If|If()]] sequences that simply test for emptiness.
| examples=
'''{{monospace|firstnotempty([media sub type], Misc Video)}}'''
: Returns the value in {{monospace|media sub type}} if it is not empty, otherwise returns {{monospace|Music Video}}.
'''{{monospace|firstnotempty([series], [name], Tag your Videos!)}}'''
: Returns the first non-empty value from the fields {{monospace|series}} or {{monospace|name}}, and if both are empty, returns the reminder to {{monospace|Tag your Videos!}}.
}}

=== <span id="IfCase">IfCase(&hellip;)</span> ===
: Functions as a switch or select case statement.

{{function description box
| name=IfCase
| arguments=primary, mode, secondary1, action1, secondary2, action2, secondary3, action3..... etc &hellip;
| description=
The [[#IfCase|IfCase()]] function performs an [[#IsEqual|IsEqual()]] operation against one primary operand and several secondary operands, with an action for each secondary operand. [[#IfCase|IfCase()]] honors the same modes as IsEqual. [[#IfCase|IfCase()]] acts on the first match, and if no match occurs returns null. This saves a lot of typing of nested Compare() or IsEqual() statements when matching things against a possible list of values, and makes for much more readable expressions. ''When constructing the tests, always test from longest/largest to shortest/smallest.''
| examples=
'''{{monospace|IfCase([bitrate], 2, 320, High, 256, Medium, 128, Standard, 64, Low)}}'''
: Converts a numerical {{monospace|bitrate}} to a descriptive word.
'''{{monospace|IfCase(Length([Name]), 5, 50, Wow this is super long, 30, This is a very long track name, 20, This is not so long)}}'''
: Takes various actions based on the length of a field, {{monospace|Name}} in this example.
'''{{monospace|IfCase([Oscar Awarded to], 8, Matt, Matt wins on his first acting job, meryl, The Oscar went to Meryl again, carrey, Unbelievable result)}}'''
: Multiple actions based on the contents of one string, {{monospace|Oscar Awarded To}} in this example.
}}


{{Function Type Page}}

The functions in this section return a Boolean value of either 1 (true) or 0 (false).
They are generally used to drive an action specified in one of the [[Conditional Functions|Conditional Functions]].

=== <span id="Compare">Compare(&hellip;)</span> ===
: Compares two numbers.

{{function description box
| name=Compare
| arguments=value1, operator, value2
| description=
The [[#Compare|Compare()]] function compares two numeric values <i>value1</i> and <i>value2</i> using the specified <i>operator</i>.

{{argument table
| name=operator
| contents=
{{argument table row|<nowiki>=</nowiki>|Equivalence}}
{{argument table row|<nowiki><</nowiki>|Less than}}
{{argument table row|<nowiki><=</nowiki>|Less than or equal to}}
{{argument table row|<nowiki>></nowiki>|Greater than}}
{{argument table row|<nowiki>>=</nowiki>|Greater than or equal to}}
}}
Outputs 1 if the comparison is true, and 0 otherwise.
| examples=
'''{{monospace|compare([bitrate], &lt;, 320)}}'''
: Returns 1 when the bit rate is less than 320 (Kbps), and 0 otherwise.
'''{{monospace|if(compare(math(now() - [date modified, 0]), &gt;, 21), Expired, formatdate([date modified, 0], elapsed))}}'''
: Outputs the age of files under 21 days old, or {{monospace|Expired}} for older files.
}}

=== <span id="IsEqual">IsEqual(&hellip;)</span> ===
: Compares two values in one of seventeen specified modes.

{{function description box
| name=IsEqual
| arguments=value1, value2, mode
| description=
{{argument optional}}
The [[#IsEqual|IsEqual()]] function compares <i>value1</i> with <i>value2</i> using any <i>mode</i> from the list of modes below.
Outputs 1 when the comparison succeeds according to the <i>mode</i>, and 0 otherwise.
Although the <i>mode</i> is specified as the last argument, the comparison should be mentally read as: <i>value1</i> <i>mode</i> <i>value2</i>.

{{argument table
| contents=
{{argument table row|0|Case-sensitive string compare for equality}}
{{argument table row|1|Case-insensitive string compare for equality}}
{{argument table row|2|Numeric compare for equality}}
{{argument table row|3|Numeric less than}}
{{argument table row|4|Numeric less than or equal to}}
{{argument table row|5|Numeric greater than}}
{{argument table row|6|Numeric greater than or equal to}}
{{argument table row|7|Substring search (case sensitive)}}
{{argument table row|8|Substring search (case insensitive)}}
{{argument table row|9|List search ANY (case sensitive)}}
{{argument table row|10|List search ANY (case insensitive)}}
{{argument table row|11|List search ALL (case sensitive)}}
{{argument table row|12|List search ALL (case insensitive)}}
{{argument table row|13|List search ANY (case sensitive) (Full String Match)}}
{{argument table row|14|List search ANY (case insensitive) (Full String Match)}}
{{argument table row|15|List search ALL (case sensitive) (Full String Match)}}
{{argument table row|16|List search ALL (case insensitive) (Full String Match)}}
}}
| examples=
'''{{monospace|<nowiki>isequal([artist], [album], 1)</nowiki>}}'''
: If the artist and album values are the same, the output will be 1, otherwise, the output will be 0.
'''{{monospace|<nowiki>if(isequal([artist], [album], 1), Eponymous, [album])</nowiki>}}'''
: The [[If()]] function bases its decision on the outcome of [[IsEqual()]], so if the artist and album values are the same, the output will be Eponymous, otherwise, the output will be the value of album.
'''{{monospace|<nowiki>if(isequal([artist], [album], 1), Eponymous/,, [album]/))</nowiki>}}'''
: This example demonstrates the character escaping mentioned in the overview earlier. Here, we want the output to be either {{monospace|Eponymous,}} (note the inclusion of the comma) or the album value with a closing parenthesis. In order to achieve this, the comma, and the closing parenthesis, are escaped using a forward-slash character. This informs the expression evaluator that these characters are not part of the expression syntax and are to be treated literally.
'''{{monospace|<nowiki>if(isequal([filename (path)], classical, 8), Classical, Not Classical)</nowiki>}}'''
: Because compare <i>mode</i> 8 has been specified, if the word {{monospace|classical}} appears anywhere in the case-insensitive file path, the expression will return {{monospace|Classical}}, and if not it will return {{monospace|Not Classical}}.
}}

=== <span id="IsEmpty">IsEmpty(&hellip;)</span> ===
: Tests a value for emptiness.

{{function description box
| name=IsEmpty
| arguments=value, mode
| description=
{{argument optional}}
The [[#IsEmpty|IsEmpty()]] function tests the given <i>value</i> for emptiness. The <i>value</i> passed is typically an Media Center field, so that some action may be taken when the field is or is not empty. Returns 1 when the <i>value</i> is empty, otherwise 0.

{{argument table
| contents=
{{argument table row|0|String test (field must be empty to get a positive result).}}
{{argument table row|1|Numerical test (field must be empty, or contain 0 to get a positive result)}}
}}

Note that Media Center does not discriminate between a 0 <i>value</i> and an empty <i>value</i> for fields of type Integer and Decimal - both 0 and empty are considered equivalent for these field types. This is useful for fields such as the integer field Disc #, where an empty or 0 <i>value</i> implies that Disc # contains no useful data, and should be generally ignored or absent in display output.

Pay particular attention to the third example offered below, as it covers a caveat that comes with this particular function.
| examples=
'''{{monospace|<nowiki>isempty([comment], 0)</nowiki>}}'''
: If the comment field is empty, [[#IsEmpty|IsEmpty()]] returns 1, otherwise 0.
'''{{monospace|<nowiki>isempty([track #], 1)</nowiki>}}'''
: Performs a numerical test for data in the [track #] field. If the field is empty or 0, a 1 is returned, otherwise 0 is returned.
'''{{monospace|<nowiki>ifelse(!isempty([disc #]), [disc #])</nowiki>}}'''
: Outputs the <i>value</i> of the disc # field when it is not empty.
}}

=== <span id="IsRange">IsRange(&hellip;)</span> ===
: Tests a value for inclusion within a given range.

{{function description box
| name=IsRange
| arguments=value, range
| description=
The [[#IsRange|IsRange()]] function tests if a <i>value</i> falls within a given <i>range</i> of values. If the <i>value</i> falls within the given <i>range</i>, 1 is returned, otherwise 0 is returned.

A <i>range</i> is specified in the form of low-high, where low and high are either letters or numbers.
The lowest <i>value</i> comes first, the highest second. Both low and high must be the same kind (letters or numbers).
The low and high values are inclusive.

Some Example Ranges:

<div style="font-family: monospace,monospace; font-size:1em;">
<div style="margin-left: 20pt">1-100</div>
<div style="margin-left: 20pt">a-z</div>
<div style="margin-left: 20pt">c-d</div>
<div style="margin-left: 20pt">23-7542 </div>
</div>
| examples=
'''{{monospace|<nowiki>isrange([artist], a-c)</nowiki>}}'''
: Artist values of Abba or Blondie will result in a 1, but ZZ Top will return a 0.
'''{{monospace|<nowiki>if(isrange([bitrate], 96-191), Poor Quality, High Quality)</nowiki>}}'''
: Returns {{monospace|Poor Quality}} for any file whose bit rate falls in the <i>range</i> of 96 to 191, and returns {{monospace|High Quality}} for all other bit rates.
'''Additional Examples'''
:[http://wiki.jriver.com/index.php/CD_Reference_Number#Answer_2 Using IsRange() in a Search List.]
}}

=== <span id="IsMissing">IsMissing(&hellip;)</span> ===
: Tests to see if a file exists on the system.

{{function description box
| name=IsMissing
| arguments=filepath
| description=
{{argument optional|filepath|[filename]}}
The [[#IsMissing|IsMissing()]] function tests for the existence of a file in the file system. If the file is missing, the function returns 1, otherwise 0 is returned if the file exists. This function is useful for checking for missing files in a Library. [[#IsMissing|IsMissing()]] treats special entries such as ripped Blu-ray or DVDs as single files, even though they physically exist in the file system as several files and directories.

''Note'': Any view or list that uses [[#IsMissing|IsMissing()]] will be slow, is Media Center must interrogate each referenced file in the file system. The larger the number of files being queried, the longer it will take to produce results. Use [[#IsMissing|IsMissing()]] with care.
| examples=
'''{{monospace|<nowiki>ismissing()</nowiki>}}'''
: If the referenced file was not found in the file system, 1 is returned; otherwise 0 is returned.
'''{{monospace|<nowiki>ismissing(C:\Music\My Lost File.mp3)</nowiki>}}'''
: Checks for {{monospace|My Lost File.mp3}} and returns 1 (positive) if the file does not exist, and 0 (negative) if the file does exist.
'''{{monospace|if(ismissing(), File is missing, File exists)}}'''
: Outputs {{monospace|File is missing}} or {{monospace|File Exists}} depending on the result returned by IsMissing().
'''{{monospace|<nowiki>[=ismissing([filename])]=1</nowiki>}}'''
: This example demonstrates how to construct an expression for use as a Media Center search query. If you place this in the search field in the top right corner of the program while viewing all of your library, it will filter the list, leaving only the missing files on view. If all files in library exist, this list will be empty. You could also create a view scheme and use this string in the {{monospace|Set rules for file display}} search to give you a view that you can visit periodically to check that your library is not missing any files.
}}

=== <span id="IsRemovable">IsRemovable(&hellip;)</span> ===
: Tests to see if a file is stored on removable media.

{{function description box
| name=IsRemovable
| arguments=filepath
| description=
{{argument optional|filepath|[filename]}}
The [[#IsRemovable|IsRemovable()]] function tests if a file resides on removable media and if so, returns 1, and if not, returns 0. The Media Center field [Removable] also provides the same value for a given file.
| examples=
'''{{monospace|IsRemovable()}}'''
: Checks if the current file is on removable storage, and if so, returns 1, otherwise returns 0.
}}

=== <span id="IsInPlayingNow">IsInPlayingNow(&hellip;)</span> ===
: Tests to see if a file is in the Playing Now playlist.

{{function description box
| name=IsInPlayingNow
| arguments=filepath
| description=
{{argument optional|filepath|[filename]}}
The [[#IsInPlayingNow|IsInPlayingNow()]] function tests if a file is in any zone's Playing Now list. Used as an expression category, pane or file list column allows distinguishing files that are in the Playing Now list.
| examples=
'''{{monospace|IsInPlayingNow()}}'''
: If the file in the Playing Now list, returns 1, otherwise returns 0.
'''{{monospace|<nowiki>if(isinplayingnow(), Queued, Not queued)</nowiki>}}'''
: If the file in the Playing Now list, returns {{monospace|Queued}}, otherwise {{monospace|Not queued}}.
}}

=== <span id="IsPlaying">IsPlaying(&hellip;)</span> ===
: Tests to see if a file is in currently being played.

{{function description box
| name=IsPlaying
| arguments=filepath
| description=
{{argument optional|filepath|[filename]}}
The [[#IsPlaying|IsPlaying()]] function tests if a file is playing in any zone.
Used as an expression category, pane or file list column allows distinguishing files that are playing now.
| examples=
'''{{monospace|<nowiki>ifelse(isplaying(), &lt;font color="ff0000"&gt;&#9834;&lt;//font&gt;, isinplayingnow(), &#9834;)</nowiki>}}'''
: This expression in a file list expression column shows which files are in the Playing Now list and which are currently playing by outputting a musical note in the column. The musical note will be displayed in red for any currently playing file.
'''Additional Examples'''
: [http://yabb.jriver.com/interact/index.php?topic=57461.0 How to use IsPlaying() and IsInPlayingNow()]
: [http://yabb.jriver.com/interact/index.php?topic=58137.msg393905#msg393905 How to play an artist's full work when a genre is shuffling?]
}}


{{Function Type Page}}

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 <span style="font-family: monospace,monospace; font-size:1em;"><b>,0</b></span> to the field's name inside the brackets, for example <span style="font-family: monospace,monospace; font-size:1em;">[Date Imported,0]</span>.

=== <span id="Delimit">Delimit(&hellip;)</span> ===
: Outputs a value with head/tail strings when value is non-empty.

{{function description box
| name=Delimit
| arguments=expression, tail, head
| description=
{{argument optional|tail|SPACE}}
{{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=
'''{{monospace|<nowiki>delimit([Track #], .)</nowiki>}}'''
: Appends a period after a track number if [Track #] is not empty, such as {{monospace|12}}.
'''{{monospace|<nowiki>delimit([Date (year)], {, })</nowiki>}}'''
: Outputs the year surrounded by curly braces, for example {{monospace|2012}}.
}}

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

{{function description box
| name=FormatBoolean
| arguments=conditional, true string, false string
| description=
{{argument optional|true string|true}}
{{argument optional|false string|false}}
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=
'''{{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.
'''{{monospace|<nowiki>formatboolean(math([track #] % 2)</nowiki>}}'''
: Outputs the default True label for odd track numbers, and the default False label for even ones.
}}

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

{{function description box
| name=FormatDuration
| arguments=duration value
| description=
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=
'''{{monospace|<nowiki>formatduration([duration,0])</nowiki>}}'''
: Outputs a friendly display of the duration field. This is the same output shown using the Duration field in a file list.
'''{{monospace|<nowiki>formatduration(600)</nowiki>}}'''
: This will output ten minutes in the format <span style="font-family: monospace,monospace; font-size:1em;">10:00</span>.
}}

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

{{function description box
| name=FormatFileSize
| arguments=bytes value
| description=
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=
'''{{monospace|<nowiki>formatfilesize([file size,0])</nowiki>}}'''
: Outputs a friendly format of the file size field. This is the same output shown using the File Size field in a file list.
'''{{monospace|<nowiki>formatfilesize(56123456)</nowiki>}}'''
: Outputs the <i>bytes value</i> 56,123,456 as <span style="font-family: monospace,monospace; font-size:1em;">53.5 MB</span>.
}}

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

{{function description box
| name=FormatNumber
| arguments=value, decimal places, label zero, label plural, label singular
| description=
{{argument optional|decimal places|0}}
{{argument optional|label zero|''label plural''}}
{{argument optional|label plural|''omitted''}}
{{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 <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.

'''''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>}}'''
: 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>}}'''
: 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>}}'''
: 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>}}'''
: 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>).
}}

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

{{function description box
| name=FormatRange
| arguments=value, range size, mode
| description=
{{argument optional|range size|1}}
{{argument optional}}
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.

{{argument table
| name=mode
| contents=
{{argument table row|0|Automatically choose between number / letter grouping}}
{{argument table row|1|Letter grouping}}
{{argument table row|2|Number grouping}}
}}
| examples=
'''{{monospace|<nowiki>formatrange([artist], 3, 1)</nowiki>}}'''
: 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.
'''{{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.
'''{{monospace|<nowiki>formatrange([bitrate], 100, 2)</nowiki>}}'''
: 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:'''
* [http://wiki.jriver.com/index.php/CD_Reference_Number How to produce 1-based range values.]
}}

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

{{function description box
| name=Orientation
| arguments=
| description=
The [[#Orientation|Orientation()]] function outputs a term indicating the orientation of an image file. {{argument table
| name=output
| contents=
{{argument table row|Portrait|When height > width.}}
{{argument table row|Square|<nowiki>When height = width.</nowiki>}}
{{argument table row|Landscape|When width > height}}
}}
| examples=
'''{{monospace|<nowiki>if(isequal(orientation(), Square), Square, Rectangle)</nowiki>}}'''
: 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.
}}

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

{{function description box
| name=PadNumber
| arguments=value, number digits
| description=
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=
'''{{monospace|<nowiki>padnumber([track #], 2)</nowiki>}}'''
: This will pad the track number with leading zeros sufficient to ensure the output is minimally two digits in length.
'''{{monospace|<nowiki>padnumber(counter(), 4)</nowiki>}}'''
: 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)}}'''
: Removes extra padding and outputs {{monospace|5}}.
}}

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

{{function description box
| name=RatingStars
| arguments=
| description=
The [[#RatingStars|RatingStars()]] function outputs the Rating field's value as the equivalent number of black star characters.
| examples=
'''{{monospace|<nowiki>ratingstars()</nowiki>}}'''
: For a file that has a Rating of 4, outputs &#9733;&#9733;&#9733;&#9733;.
}}

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

{{function description box
| name=Watched
| arguments=mode
| description=
{{argument optional}}
The [[#Watched|Watched()]] function outputs a video's bookmark position in a human-readable format, using a specified <i>mode</i>.

{{argument table
| name=mode
| contents=
{{argument table row|0|Output a human-readable watched status.}}
{{argument table row|1|Output a numeric watched value (see Watched Status Values below).}}
{{argument table row|2|Output a watched checkmark &#x2713; if watched.}}
}}
{{argument table
| name=numeric watched status
| contents=
{{argument table row|-1|File type is not Video}}
{{argument table row|0|Not watched.}}
{{argument table row|1|Partially watched.}}
{{argument table row|2|Entirely watched.}}
}}
| examples=
'''{{monospace|<nowiki>watched()</nowiki>}}'''
: 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>}}'''
: 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.
}}


{{Function Type Page}}

The functions in this section are used primarily to manipulate strings. Since the Media Center expression language is primarily string-oriented, these functions provide a means to manipulate field values or the output from other expressions.

=== <span id="Clean">Clean(&hellip;)</span> ===
: Clean a string to be used for various operations.

{{function description box
| name=Clean
| arguments=string, mode
| description=
{{argument optional}}
The [[#Clean|Clean()]] function is generally used to sanitize a <i>string</i> by stripping empty brackets, remove superfluous dash characters, eliminate leading or trailing articles, or replace filesystem-illegal characters. It is typically employed before some operation such as Rename to clean the product of joining various fields, some of which may be empty, or to produce filesystem-safe filenames. It may be used for a variety of purposes, however.
{{argument table
| name=mode
| contents=
{{argument table row|0|Removes empty () and [], superfluous dash (-) and whitespace characters and sometimes comma (be careful).}}
{{argument table row|1|Removes the article 'the' from the beginning and ', the' from the end.}}
{{argument table row|2|Removes any article (a, an, the, etc.) from the beginning and end.}}
{{argument table row|3|Replaces each filesystem-illegal character {{monospace|\ / : * ? " < > |}} with an underscore {{monospace|<nowiki>_</nowiki>}}, and replaces each unprintable character with a space.}}
}}
| examples=
'''{{monospace|<nowiki>clean([album] - [date])</nowiki>}}'''
: The concatenation of [Album] - [Date] may leave a dangling <span style="font-family: monospace,monospace; font-size:1em;"> - </span> <i>string</i> when date is empty. [[#Clean|Clean()]] in the default <i>mode</i> removes this dangling <i>string</i>.
'''{{monospace|<nowiki>clean(The Beatles, 1)</nowiki>}}'''
: For sorting or grouping purposes, it is often desirable to remove the leading article <span style="font-family: monospace,monospace; font-size:1em;">The</span> from a <i>string</i>. [[#Clean|Clean()]] in <i>mode</i> 1 provides a convenient solution, and in this example produces <span style="font-family: monospace,monospace; font-size:1em;">Beatles</span>.
'''{{monospace|<nowiki>clean(AC//DC: Back In Black, 3)</nowiki>}}'''
: When an expression is to be used to produce a filename, filesystem-illegal characters must be removed or converted to legal characters. [[#Clean|Clean()]] in <i>mode</i> 3 will convert such characters into safe underscores. This example would produce the filesystem-safe value of <span style="font-family: monospace,monospace; font-size:1em;">AC_DC_ Back In Black</span>.
'''{{monospace|<nowiki>clean(\//:*?"&lt;&gt;|, 3)</nowiki>}}'''
: This trivial example demonstrates how all filesystem-illegal characters are converted to underscores, producing the nine-character output <span style="font-family: monospace,monospace; font-size:1em;">_________</span> which consists entirely of underscores.
}}

=== <span id="FixCase">FixCase(&hellip;)</span> ===
: Changes the case of a given string.

{{function description box
| name=FixCase
| arguments=string, mode
| description=
{{argument optional}}
The [[#FixCase|FixCase()]] function will convert the supplied text <i>string</i> according to the specified <i>mode</i>.
{{argument table
| name=mode
| contents=
{{argument table row|0|Title Case}}
{{argument table row|1|All words}}
{{argument table row|2|First word}}
{{argument table row|3|All uppercase}}
{{argument table row|4|All lowercase}}
{{argument table row|5|All words (preserve existing capitalization)}}
}}
| examples=
'''{{monospace|<nowiki>fixcase(enjoy the silence)</nowiki>}}'''
: The default <i>mode</i> 0 is used, so the output is: <span style="font-family: monospace,monospace; font-size:1em;">Enjoy the Silence</span>.
'''{{monospace|<nowiki>fixcase(enjoy the silence, 1)</nowiki>}}'''
: Using <i>mode</i> 1, all words are uppercased, so the output is: <span style="font-family: monospace,monospace; font-size:1em;">Enjoy The Silence</span>.
'''{{monospace|<nowiki>fixcase(MY ALbUm IS cAlLeD: adam, 4)</nowiki>}}'''
: Outputs: <span style="font-family: monospace,monospace; font-size:1em;">my album is called: adam</span>.
'''{{monospace|<nowiki>fixcase(MY ALbUm IS cAlLeD: adam, 5)</nowiki>}}'''
: Using ''mode'' 5, the initial character of each word is uppercased, but other existing capitalization is preserved, so the output is: {{monospace|MY ALbUm IS CAlLeD: Adam}}.
}}

=== <span id="FixSpacing">FixSpacing(&hellip;)</span> ===
: Intelligently splits adjacent camel-cased words.

{{function description box
| name=FixSpacing
| arguments=string, mode
| description=
{{argument optional|mode|1}}
The [[#FixSpacing|FixSpacing()]] function inserts spaces between adjacent camel-cased words in <i>string</i>. It is useful for helping to clean and convert metadata that favors compactness over standard sentence structure.
{{argument table
| name=mode
| contents=
{{argument table row|0|Disables conversion}}
{{argument table row|1|Enables camel-case conversion}}
}}
| examples=
'''{{monospace|<nowiki>fixspacing(OneWorld)</nowiki>}}'''
: Outputs <span style="font-family: monospace,monospace; font-size:1em;">One World</span>.
'''{{monospace|<nowiki>fixspacing([name], 1)</nowiki>}}'''
: Outputs the name field with any camel-case converted into standard sentence structure. If the value of name was, <span style="font-family: monospace,monospace; font-size:1em;">MiracleOn34thStreet</span>, the output would be <span style="font-family: monospace,monospace; font-size:1em;">Miracle On 34th Street</span>.
'''{{monospace|<nowiki>fixspacing(Another [name])</nowiki>}}'''
: Assuming the same [name] as above, this would return <span style="font-family: monospace,monospace; font-size:1em;">Another Miracle On 34th Street</span>.
}}

=== <span id="Hexify">Hexify(&hellip;)</span> ===
: Hexifies a string to make it suitable for web usage.

{{function description box
| name=Hexify
| arguments=string
| description=
The [[#Hexify|Hexify()]] function URI encodes a <i>string</i> to make it useable by a browser or search engine. [[#Hexify|Hexify()]] is typically used by expressions generating or working on URLs in Media Center's [[Link Manager]].
| examples=
'''{{monospace|<nowiki>hexify(Oasis - /(What's The Story/) Morning Glory?)</nowiki>}}'''
: The result is <span style="font-family: monospace,monospace; font-size:1em;">Oasis%20-%20%28What%27s%20The%20Story%29%20Morning%20Glory%3F</span>.
}}

=== <span id="Left">Left(&hellip;)</span> ===
: Retrieves a specified number of characters from the left of a string.

{{function description box
| name=Left
| arguments=string, quantity
| description=
The [[#Left|Left()]] function retrieves no more than <i>quantity</i> characters from the left of the <i>string</i>.
| examples=
'''{{monospace|<nowiki>left([filename], 3)</nowiki>}}'''
: Return the Windows drive letter, colon and first back-slash from the filename (for filenames beginning with a windows drive letter).
}}

=== <span id="Length">Length(&hellip;)</span> ===
: Returns the number of characters in a string.

{{function description box
| name=Length
| arguments=string
| description=
The [[#Length|Length()]] function returns the number of characters contained in <i>string</i>.
| examples=
'''{{monospace|<nowiki>length(A Simple Plan)</nowiki>}}'''
: Returns 13.
'''{{monospace|<nowiki>if(compare(length([filename]), &gt;=, 68), Long, Short)</nowiki>}}'''
: The length of the filename is calculated, and compared against 68, outputting <span style="font-family: monospace,monospace; font-size:1em;">Long</span> when the length is greater than or equal to 68, and <span style="font-family: monospace,monospace; font-size:1em;">Short</span> otherwise.
}}

=== <span id="Letter">Letter(&hellip;)</span> ===
: Returns the starting letter or letters of a given string.

{{function description box
| name=Letter
| arguments=string, number, mode
| description=
{{argument optional|number|1}}
{{argument optional|mode|0}}
The [[#Letter|Letter()]] function returns the starting letter or letters of a given <i>string</i>, which can be given literally or as a library field. The function's ''mode'' defaults to "Ignore Articles", and for this, it uses the existing, user managed articles list. It also defaults to "number grouping", meaning that if the first character is a number, regardless of that number, a hash (#) is returned. ''Number'' specifies the number of starting characters to return, and defaults to one.
{{argument table
| name=mode
| contents=
{{argument table row|0|Ignore articles and group numbers}}
{{argument table row|1|Do not group numbers, return the actual number. Articles are ignored.}}
{{argument table row|2|Do not ignore articles, but perform number grouping}}
{{argument table row|3|Do not ignore articles and do not group numbers}}

These modes are useful when working with a selection of multiple files that may have a mix of articles and numbers and allow you to achieve whichever combination of results you require.
}}
| examples=
'''{{monospace|<nowiki>letter(10CC)</nowiki>}}'''
: Returns #.
'''{{monospace|<nowiki>letter(10CC,2)</nowiki>}}'''
: Returns ##.
'''{{monospace|<nowiki>letter(10CC,2,1)</nowiki>}}'''
: Returns 10.
'''{{monospace|<nowiki>letter(The Band,2)</nowiki>}}'''
: Returns Ba.
'''{{monospace|<nowiki>letter(The Band,2,3)</nowiki>}}'''
: Returns Th.
}}

=== <span id="Mid">Mid(&hellip;)</span> ===
: Retrieves specified characters from a string.

{{function description box
| name=Mid
| arguments=string, start position, quantity
| description=
{{argument optional|start position|0}}
{{argument optional|quantity|1}}
The [[#Mid|Mid()]] function returns a specified <i>quantity</i> of characters from the <i>start position</i> in <i>string</i>.

The <i>start position</i> is 0-based (i.e. the first character is considered position 0). A quantify of -1 returns all characters from the start positionning to the end of <i>string</i>.
| examples=
'''{{monospace|<nowiki>mid(12345)</nowiki>}}'''
: Returns <span style="font-family: monospace,monospace; font-size:1em;">1</span>, using is the default <i>quantity</i> (1) of characters from the default <i>start position</i> of (0 - the beginning of the <i>string</i>).
'''{{monospace|<nowiki>mid(12345, 1, 2)</nowiki>}}'''
: Returns 2 characters beginning at <i>start position</i> 1, which is <span style="font-family: monospace,monospace; font-size:1em;">23</span>.
'''Additional Examples:'''
* [http://yabb.jriver.com/interact/index.php?topic=52809.0 An example that uses Mid() to re-order a date field.]
* [http://yabb.jriver.com/interact/index.php?topic=75891.0 An example that uses Mid() to output a number of stars based on an arbitrary rating value.]
}}

=== <span id="Regex">Regex(&hellip;)</span> ===
: Regular expression pattern matching and capture.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="Regex" 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>regex(</b><i>string</i><b>, </b><i>regexp</i><b>, </b><i>run mode</i><b>, </b><i>case sensitivity</i><b>)</b></span>
The [[#Regex|Regex()]] function performs regular expression (RE) pattern matching on a <i>string</i>.
The <i>string</i> is evaluated against the regular expression <i>regexp</i>, and <i>run mode</i> dictates the values output by [[#Regex|Regex()]].
The three modes allow for match testing, capture output, or silent operation.

All match captures are placed into special variables referenced as [R1], [R2], ... [R9], which can be used in later in the expression.
The contents of the captures [R1] ... [R9] are available until the end of the expression, or [[#Regex|Regex()]] is run again, whereby they are replaced.
The regular expression implementation used prior to Media Center 19 is the Microsoft 2010 TR1 engine, and in Media Center 19 it is the Boost engine.
[[Regular expression syntax|Additional information]] is available regarding the full syntax and other implementation details.

Available <i>run mode</i> values:

<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>Runs in Boolean test mode, returning either a 1 or 0, indicating whether the <i>string</i> matched (1) or did not match (0) the <i>regexp</i>. This <i>run mode</i> is useful within an [[#If|If()]] test, so that different true or false actions may be taken.</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>1 to 9</b></td><td>Outputs the specified Nth capture group's contents, where N ranges from 1 to 9. Only a single capture is output in this mode, but all captures are available in the [R1] ... [R9] capture variables. This <i>run mode</i> is used to easily output a single matching sub-<i>string</i>.</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>-1</b></td><td>Runs in silent mode, with no output being produced. This <i>run mode</i> is useful as a means to capture portions of the <i>string</i> to be later used in subsequent portions of an expression.</td></tr>
</table></div>

The <i>case sensitivity</i> argument toggles the case-sensitivity of regular expression matching.
Note that case insensitivity does not apply to characters inside a character class <span style="font-family: monospace,monospace; font-size:1em;">[ ]</span>.
Use both uppercase and lowercase characters when necessary to match either case (e.g. <span style="font-family: monospace,monospace; font-size:1em;">[aAbB]</span> to match either uppercase or lowercase <span style="font-family: monospace,monospace; font-size:1em;">A</span> or <span style="font-family: monospace,monospace; font-size:1em;">B</span>).

Available <i>case sensitivity</i> values:

<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>Ignore case when matching (e.g. the letters E and e are identical)</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Consider case when matching (e.g. the letters E and e are considered different)</td></tr>
</table></div>

The regular expression language assigns special meaning to many characters.
A few of these meta-characters, such as forward slash <span style="font-family: monospace,monospace; font-size:1em;">/</span>, comma <span style="font-family: monospace,monospace; font-size:1em;">,</span> and both <span style="font-family: monospace,monospace; font-size:1em;">(</span> and <span style="font-family: monospace,monospace; font-size:1em;">)</span> are also reserved and used by the Media Center expression language.
To force the Media Center expression engine to ignore the meta-characters in <i>regexp</i>, surround the entire regular expression with <span style="font-family: monospace,monospace; font-size:1em;">/#</span> <span style="font-family: monospace,monospace; font-size:1em;">#/</span>.
This is one of Media Center's escapements, which tells the expression engine to ignore everything inside, so that the entire, uninterpreted <i>regexp</i> can be provided to the [[#Regex|Regex()]] regular expression evaluator.
Although surrounding <i>regexp</i> by <span style="font-family: monospace,monospace; font-size:1em;">/#</span> <span style="font-family: monospace,monospace; font-size:1em;">#/</span> is not necessary or required when no conflicting characters are in use, and you may manually escape the expression languages meta-characters with a forward slash <span style="font-family: monospace,monospace; font-size:1em;">/</span>, it is probably a safe practice to always encase every <i>regexp</i> within <span style="font-family: monospace,monospace; font-size:1em;">/#</span> <span style="font-family: monospace,monospace; font-size:1em;">#/</span>.

Argument <i>run mode</i> is optional (defaults to 0).

Argument <i>case sensitivity</i> is optional (defaults to 0).

|- 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>ifelse(regex([name], /#^(the|an|a)\b#/, 0, 1), Fix your case!)</nowiki></b></span>
<p style="margin-left:20pt;">Searches the name field for any of the lowercase articles <span style="font-family: monospace,monospace; font-size:1em;">the</span>, <span style="font-family: monospace,monospace; font-size:1em;">and</span> and <span style="font-family: monospace,monospace; font-size:1em;">a</span> at the beginning of name, and outputs <span style="font-family: monospace,monospace; font-size:1em;">Fix your case!</span> when the match succeeds.
The <i>run mode</i> is 0 which is a test and capture mode, and <i>case sensitivity</i> is enabled.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>if(regex([artist], /#([[:punct:]])#/, 0), [R1] --&gt; [Artist], No Punctuation)</nowiki></b></span>
<p style="margin-left:20pt;">Using the default mode 0, [[#Regex|Regex()]] will output a Boolean for use inside a conditional to cause some action to occur based on the match success or failure.
This example matches against the artist field looking for any punctuation character.
If the match succeeds (a punctuation character was found), that character is output followed by the <i>string</i> <span style="font-family: monospace,monospace; font-size:1em;"> --> </span> and the artist. In there was no match, the <i>string</i> <span style="font-family: monospace,monospace; font-size:1em;">No Punctuation</span> is output.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>regex(D03T02 some track.mp3, /#^D(\d+)T(\d+)#/, 1)Disc: [R1], Track: [R2]</nowiki></b></span>
<p style="margin-left:20pt;">The <i>string</i> is matched against the <i>regexp</i> that is looking for a <span style="font-family: monospace,monospace; font-size:1em;">D</span> followed by any number of digits, followed by a <span style="font-family: monospace,monospace; font-size:1em;">T</span> and then more digits.
Those digits were captured, and later used to output the value <span style="font-family: monospace,monospace; font-size:1em;">Disc: 03, Track: 02</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>regex([filename (name)], /#^(\d+)-#/, -1)Track number is [R1]</nowiki></b></span>
<p style="margin-left:20pt;">Using <i>run mode</i> -1, the file's name is pattern tested against the <i>regexp</i> which is looking for leading digits followed by a dash.
Those digits are captured in buffer [R1] which is used later in the expression. If the file name was <span style="font-family: monospace,monospace; font-size:1em;">2-foo.mp3</span>, the output would be <span style="font-family: monospace,monospace; font-size:1em;">Track number is 2</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>regex([filename], /#(\d{1,2})\.(\d{1,2}).(\d{4})#/, -1)[R3]//[R1]//[R2]</nowiki></b></span>
<p style="margin-left:20pt;">Matches and captures a date formatted as dd.mm.yyyy anywhere within the filename, and rearranges it in a standard format of yyyy/mm/dd.
Since <i>run mode</i> is -1, no output occurs.
However, captured match segments are made available for subsequent use.
The three captures, [R1], [R2] and [R3] are arranged in the textual output so that we get the desired year/month/day ordering, such as <span style="font-family: monospace,monospace; font-size:1em;">2011/08/19</span>.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="RemoveCharacters">RemoveCharacters(&hellip;)</span> ===
: Removes a list of characters from a string.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="RemoveCharacters" 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>removecharacters(</b><i>string</i><b>, </b><i>character list</i><b>, </b><i>mode</i><b>)</b></span>
The [[#RemoveCharacters|RemoveCharacters()]] function will remove from <i>string</i> any characters in the <i>character list</i>. The characters removed depend upon the <i>mode</i> specified.
The function operates in a case-sensitive manner.

Available <i>mode</i> values:

<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>Remove all instances</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Remove from the beginning only</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>2</b></td><td>Remove from the end only</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>3</b></td><td>Remove from each end</td></tr>
</table></div>

Argument <i>mode</i> is optional (defaults to 0).

|- 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>removecharacters(Paper, Ppr)</nowiki></b></span>
<p style="margin-left:20pt;">Removes <span style="font-family: monospace,monospace; font-size:1em;">P</span>, <span style="font-family: monospace,monospace; font-size:1em;">p</span>, and <span style="font-family: monospace,monospace; font-size:1em;">r</span> from <span style="font-family: monospace,monospace; font-size:1em;">Paper</span>, resulting in <span style="font-family: monospace,monospace; font-size:1em;">ae</span>.
The default <i>mode</i> 0 is in effect, removing all instances of the characters specified in the <i>character list</i>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>removecharacters(Paper, Ppr, 1)</nowiki></b></span>
<p style="margin-left:20pt;">With <i>mode</i> 1 set, only the initial character <span style="font-family: monospace,monospace; font-size:1em;">P</span> is removed, resulting in <span style="font-family: monospace,monospace; font-size:1em;">aper</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>removecharacters(Paper, Ppr, 2)</nowiki></b></span>
<p style="margin-left:20pt;">In <i>mode</i> 2, only one character from the end of the <i>string</i> are removed, leaving "Pape.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>removecharacters(Paper, Ppr, 3)</nowiki></b></span>
<p style="margin-left:20pt;">Both the front and back are affected in <i>mode</i> 3, causing the removal of the leading <span style="font-family: monospace,monospace; font-size:1em;">P</span> and trailing <span style="font-family: monospace,monospace; font-size:1em;">r</span> resulting in <span style="font-family: monospace,monospace; font-size:1em;">ape</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>removecharacters([artist], /(/))</nowiki></b></span>
<p style="margin-left:20pt;">Removes any <span style="font-family: monospace,monospace; font-size:1em;">(</span> and <span style="font-family: monospace,monospace; font-size:1em;">)</span> characters from anywhere within the [artist] field.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="RemoveLeft">RemoveLeft(&hellip;)</span> ===
: Trims characters from the beginning of a string.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="RemoveLeft" 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>removeleft(</b><i>string</i><b>, </b><i>quantity</i><b>)</b></span>
The [[#RemoveLeft|RemoveLeft()]] function removes a specified <i>quantity</i> of characters from the left side of a <i>string</i>.
If the <i>quantity</i> is larger than the length of the <i>string</i>, the output will be 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>removeleft(Good Deeds, 5)</nowiki></b></span>
<p style="margin-left:20pt;">Removes the first 5 characters from resulting in <span style="font-family: monospace,monospace; font-size:1em;">Deeds</span> being output.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="RemoveRight">RemoveRight(&hellip;)</span> ===
: Trims characters from the end of a string

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="RemoveRight" 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>removeright(</b><i>string</i><b>, </b><i>quantity</i><b>)</b></span>
The [[#RemoveRight|RemoveRight()]] function removes a specified <i>quantity</i> of characters from the right side of a <i>string</i>.
If the <i>quantity</i> is larger than the length of the <i>string</i>, the output will be 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>removeright(03-02-1959,5)</nowiki></b></span>
<p style="margin-left:20pt;">Removes the last 5 characters from the given date, leaving only the month and year <span style="font-family: monospace,monospace; font-size:1em;">03-02</span>.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="Replace">Replace(&hellip;)</span> ===
: Replace or remove a string segment

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="Replace" 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>replace(</b><i>string</i><b>, </b><i>old</i><b>, </b><i>new</i><b>)</b></span>
The [[#Replace|Replace()]] function replaces all instances of <i>old</i> within <i>string</i> with <i>new</i>.
If <i>new</i> is unspecified, it defaults to an empty value, causing <i>old</i> to be removed.
[[#Replace|Replace()]] operates in a case-sensitive manner.

Argument <i>new</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>replace(The Daily Show with John Oliver, hn Oliver, n Stewart)</nowiki></b></span>
<p style="margin-left:20pt;">Now that John Oliver has completed his summer stand-in for Jon Stewart, it is time for a replacement.
The <i>old</i> sequence <span style="font-family: monospace,monospace; font-size:1em;">hn Oliver</span> will be replaced with the <i>new</i> sequence <span style="font-family: monospace,monospace; font-size:1em;">n Stewart</span>, resulting in
<span style="font-family: monospace,monospace; font-size:1em;">The Daily Show with Jon Stewart</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>replace(Sample String, s, Replaced)</nowiki></b></span>
<p style="margin-left:20pt;">In this example, the original <i>string</i> does not contain the <i>old</i> value <span style="font-family: monospace,monospace; font-size:1em;">s</span> anywhere,
so no replacement occurs and the original <i>string</i> is returned.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>replace(Led Zeppelin.[remastered], .[remastered])</nowiki></b></span>
<p style="margin-left:20pt;">Removes the trailing <i>old</i> value <span style="font-family: monospace,monospace; font-size:1em;">.[remastered]</span> from the original <i>string</i>, resulting in <span style="font-family: monospace,monospace; font-size:1em;">Led Zeppelin</span>.
Because no <i>new</i> <i>string</i> is specified, the default empty value is used as a replacement,
effectively stripping the <i>old</i> value.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="Right">Right(&hellip;)</span> ===
: Retrieves a specified number of characters from the right of a string.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="Right" 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>right(</b><i>string</i><b>, </b><i>quantity</i><b>)</b></span>
The [[#Right|Right()]] function retrieves the specified <i>quantity</i> of characters from the right of the <i>string</i>.
If <i>quantity</i> is larger than the length of <i>string</i>, the original <i>string</i> is returned.
|- 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>right([filename], 3)</nowiki></b></span>
<p style="margin-left:20pt;">Returns the last three characters from the filename (typically this is the file's suffix).</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="Swap">Swap(&hellip;)</span> ===
: Takes Firstname Lastname and swaps to Lastname, Firstname.

{{function description box
| name=Swap
| arguments=string
| description=
The [[#Swap|Swap()]] function is used to reverse the order of a personal name in a string (converting Firstname Lastname into Lastname, Firstname). The function has special handling for strings that end with Jr., Sr., I, II, III, IV, V (so that these common suffixes are handled properly), and it can also handle semicolon-delimited string lists (such as {{monospace|[Artist]}}, {{monospace|[Actors]}}, and {{monospace|[Director]}}).
| examples=
'''{{monospace|<nowiki>swap(Paul Simon)</nowiki>}}'''
: Reverses the lexical order of the name to {{monospace|Simon, Paul}}.
'''{{monospace|<nowiki>swap(Sammy Davis Jr.)</nowiki>}}'''
: Handles most common name suffixes and results in {{monospace|Davis, Sammy Jr}}.
'''{{monospace|<nowiki>swap(Paul Simon; Art Garfunkel)</nowiki>}}'''
: Reverses the lexical order of the list of names to {{monospace|Simon, Paul; Garfunkel, Art}}.
}}

=== <span id="Unswap">Unswap(&hellip;)</span> ===
: Takes Lastname, Firstname and reverses it to Firstname Lastname.

{{function description box
| name=Unswap
| arguments=string
| description=
The [[#Unswap|Unswap()]] function is the opposite of the Swap() function. It is used to restore the normal western-style order of a personal name in a string (converting Lastname, Firstname into Firstname Lastname). This command also works properly with semicolon-delimited list data (such as the {{monospace|[Artist]}} field), and like the [[#Swap|Swap()]] command, it handles common name suffixes such as Jr., Sr., I, II, III, IV, V, etc.
| examples=
'''{{monospace|<nowiki>Unswap(Simon, Paul)</nowiki>}}'''
: Reverses the lexical order of the name to <span style="font-family: monospace,monospace; font-size:1em;">Paul Simon</span>.
'''{{monospace|<nowiki>Unswap(Simon, Paul; Garfunkel, Art)</nowiki>}}'''
: Reverses the lexical order of the name list to <span style="font-family: monospace,monospace; font-size:1em;">Paul Simon; Art Garfunkel</span>.
'''Please Note''': These examples were simplified and ignore the commas in the string arguments. For these expressions to work properly (when entered directly), you would need to escape the comma in the string literal: {{monospace|Unswap(Simon/, Paul; Garfunkel/, Art)}}. However, this function is typically used with a field value (or the output of another function), and would therefore be treated as a single argument even if the resulting string contains a comma. See [[Expression Language#Function Arguments|Function Arguments]] for further details.
}}


{{Function Type Page}}

Media Center supports several different types of fields, one of them being the List type.
A List type is a library field of type List, or an expression coerced into a list type.

The functions in this section provide the ability to manipulate lists and list items.
A list is a sequence of strings, each separated from one another by an arbitrary delimiter.
The default delimiter is a semicolon.
Media Center does not make a strict distinction between a string and a list of strings.
In fact, a list is just a string, and it is safe to think of a string as a list with zero or more
arbitrary delimiter sequences.
For example, the string "2013-08-17" can be thought of as a dash-delimited list with the three items "2013", "08" and "17".

This weak typing is very useful since a list,
for example, "John; Sally" that contains the two items "John" and "Sally" can be manipulated not only using the
list functions in this section, but because it is just a string, it can also be manipulated with string functions.
For example, taking the same list above and combining it with the string "; Joe" adds a new item
to the list "John; Sally; Joe", and removing the first 6 characters with [[#RemoveLeft|RemoveLeft()]] would
produce a now shortened string/list "Sally; Joe".
The list manipulation functions make this job easier, especially when using the default semicolon delimiter.
Furthermore, since any character or sequence of characters can be considered as a list delimiter,
any string can be treated as a list, and the functions in this section can be used on any string as needed.

In some areas such as a panes column, or a category view, Media Center gives special treatment to List types.
For example, using semicolon as the delimiter, a List will be automatically split apart into its individual items.

=== <span id="ListBuild">ListBuild(&hellip;)</span> ===
: Constructs a list from a series of items.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="ListBuild" 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>listbuild(</b><i>mode</i><b>, </b><i>delimiter</i><b>, </b><i>item1</i><b>, </b><i>item2</i><b>, </b><i>&hellip;</i><b>)</b></span>
The [[#ListBuild|ListBuild()]] function constructs a list from <i>item1</i>, <i>item2</i>, ... using a supplied <i>delimiter</i> to separate the individual items in the resulting list.
The construction <i>mode</i> affects how empty items are handled - they can be included or excluded.
The <i>mode</i> typically used exclude empty items, so that lists do not contain empty slots.
However, there are occasions when retaining empty slots is useful, such as when using a list to act like an array where data is stored in particular slots so that the [[#ListItem|ListItem()]] function may later retrieve values at a given index.
It can also be useful when calculating several expressions and combining the results into a single list for presentation; by including all items, items can be made to line-up for visual inspection in a column.

Available <i>mode</i> values:

<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>Include empty values</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Exclude empty values</td></tr>
</table></div>

The <i>delimiter</i> argument specifies the character or character sequence to be inserted in between items in the list.
An unspecified <i>delimiter</i> will result in a <i>delimiter</i>-less concatenation of the supplied arguments <i>item1</i>, <i>item2</i>, etc.

Argument <i>delimiter</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>listbuild(1, ;, Bennie, June)</nowiki></b></span>
<p style="margin-left:20pt;">Returns a standard semicolon-separated list containing two items <span style="font-family: monospace,monospace; font-size:1em;">Bennie; June</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>listbuild(1, \, [album artist (auto)], [album])</nowiki></b></span>
<p style="margin-left:20pt;">Builds a backslash-separated list combining the two fields album artist (auto) and album.
This is useful for building panes column or categories hierarchies in a view.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="ListClean">ListClean(&hellip;)</span> ===
: Various list operations.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="ListClean" 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>listclean(</b><i>list</i><b>, </b><i>mode</i><b>, </b><i>delimiter</i><b>)</b></span>
The [[#ListClean|ListClean()]] function performs one of the operations specified by <i>mode</i> on the given <i>list</i>.
The specified <i>delimiter</i> separates <i>list</i> items.

<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>1</b></td><td>Remove duplicates</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>2</b></td><td>Reverse the order of items</td></tr>
</table></div>

Argument <i>delimiter</i> is optional (defaults to SEMICOLON).

|- 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>listclean(c;b;c;a, 1)</nowiki></b></span>
<p style="margin-left:20pt;">Removes duplicates from the <i>list</i>, returning <span style="font-family: monospace,monospace; font-size:1em;">c;b;a</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>listclean(d;c;b;a, 2) </nowiki></b></span>
<p style="margin-left:20pt;">Reverses the <i>list</i> items, returning <span style="font-family: monospace,monospace; font-size:1em;">a;b;c;d</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>listclean(\a\x\x\x\z, 1, \) </nowiki></b></span>
<p style="margin-left:20pt;">Removes duplicates from a backslash-separated <i>list</i>, returning <span style="font-family: monospace,monospace; font-size:1em;">\a\x\z</span>.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="ListCombine">ListCombine(&hellip;)</span> ===
: Combines two delimited lists into a single delimited list.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="ListCombine" 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>listcombine(</b><i>list1</i><b>, </b><i>list2</i><b>, </b><i>input delimiter</i><b>, </b><i>output delimiter</i><b>, </b><i>mode</i><b>)</b></span>
The [[#ListCombine|ListCombine()]] function returns a single list after performing the operation specified by <i>mode</i> on the two lists <i>list1</i> and <i>list2</i>.
An <i>input delimiter</i> and an <i>output delimiter</i> may be specified.
The <i>input delimiter</i> is effective for both <i>list1</i> and <i>list2</i>, and the <i>output delimiter</i> will be used in the returned list, replacing the
<i>input delimiter</i> from both <i>list1</i> and <i>list2</i>.

Available <i>mode</i> values:

<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>Combine lists removing duplicates (order is preserved).</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Output only items contained in both lists (order is preserved).</td></tr>
</table></div>

Argument <i>input delimiter</i> is optional (defaults to SEMICOLON).

Argument <i>output delimiter</i> is optional (defaults to SEMICOLON).

Argument <i>mode</i> is optional (defaults to 0).

|- 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>listcombine(a;b;e, a;b;c;d)</nowiki></b></span>
<p style="margin-left:20pt;">Returns <span style="font-family: monospace,monospace; font-size:1em;">a;b;e;c;d</span>.
This example uses the default <i>mode</i> 0 to combine <i>list1</i> with <i>list2</i>, preserving the order of items.
The default <span style="font-family: monospace,monospace; font-size:1em;">;</span> <i>input delimiter</i> and <i>output delimiter</i> is used.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>listcombine(a;b;e, a;b;c;d, ;, ;, 1)</nowiki></b></span>
<p style="margin-left:20pt;">Returns <span style="font-family: monospace,monospace; font-size:1em;">a;b</span>.
The <i>input delimiter</i> and <i>output delimiter</i> are both specified as <span style="font-family: monospace,monospace; font-size:1em;">;</span>,
and <i>mode</i> 1 is used to produce a list of only items that exist in both <i>list1</i> and <i>list2</i>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>listcombine(a-c, c-f, -, ..., 0)</nowiki></b></span>
<p style="margin-left:20pt;">Returns <span style="font-family: monospace,monospace; font-size:1em;">a...c...f</span>. The <i>input delimiter</i> is <span style="font-family: monospace,monospace; font-size:1em;">-</span>, while the <i>output delimiter</i> is <span style="font-family: monospace,monospace; font-size:1em;">...</span>, and <i>mode</i> 0 combines both lists.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>listcombine(a#@#c, c#@#f, #@#, ., 0)</nowiki></b></span>
<p style="margin-left:20pt;">Returns <span style="font-family: monospace,monospace; font-size:1em;">a.c.f</span>. This example demonstrates how to combine two lists with duplicates removed while replacing a multi-character <i>input delimiter</i> <span style="font-family: monospace,monospace; font-size:1em;">#@#</span> with a single-character <i>output delimiter</i> <span style="font-family: monospace,monospace; font-size:1em;">.</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>listcombine([people], [places])&amp;datatype=[list]</nowiki></b></span>
<p style="margin-left:20pt;">The result here would be a single, semicolon delimited list containing all the list items from the [people] and [places] fields.
For example, if [people] contains <span style="font-family: monospace,monospace; font-size:1em;">Family\Mum; Family\Dad; Family\Gran</span>, and [places] contains <span style="font-family: monospace,monospace; font-size:1em;">UK\Scotland\Edinburgh; UK\Scotland\Edinburgh\Edinburgh Castle</span>,
the output list would be <span style="font-family: monospace,monospace; font-size:1em;">Family\Mum; Family\Dad; Family\Gran; UK\Scotland\Edinburgh; UK\Scotland\Edinburgh\Edinburgh Castle</span>.
Using the <span style="font-family: monospace,monospace; font-size:1em;">&datatype=[list]</span> cast makes the expression split individual list items in a panes or categories view.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="ListCount">ListCount(&hellip;)</span> ===
: Returns the number of items in a list.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="ListCount" 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>listcount(</b><i>list</i><b>, </b><i>delimiter</i><b>)</b></span>
The [[#ListCount|ListCount()]] function returns the number of items that exist in a <i>list</i> delimited by <i>delimiter</i>.

Argument <i>delimiter</i> is optional (defaults to SEMICOLON).

|- 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>listcount([keywords])</nowiki></b></span>
<p style="margin-left:20pt;">Returns the number of keywords for the file.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>listcount([filename (path)], \)</nowiki></b></span>
<p style="margin-left:20pt;">Returns the number of the directories in a Windows drive-based file path.
The example demonstrates that non-List type fields can be used with the functions in this section.
While the <i>delimiter</i> specified here is <span style="font-family: monospace,monospace; font-size:1em;">\</span>, an escaped forward slash <span style="font-family: monospace,monospace; font-size:1em;">//</span> could be used when applicable.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="ListItem">ListItem(&hellip;)</span> ===
: Returns an item from a location in a list.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="ListItem" 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>listitem(</b><i>list</i><b>, </b><i>position</i><b>, </b><i>delimiter</i><b>)</b></span>
The [[#ListItem|ListItem()]] function returns the item from the specified <i>position</i> in the <i>list</i>.
Items in a <i>list</i> are zero-based, so the first item in the <i>list</i> is located at <i>position</i> 0.
Nothing is returned with the <i>position</i> is outside the bounds of the <i>list</i>.

Argument <i>delimiter</i> is optional (defaults to SEMICOLON).

|- 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>listitem(a;b;c, 1)</nowiki></b></span>
<p style="margin-left:20pt;">Returns <span style="font-family: monospace,monospace; font-size:1em;">b</span>, since <i>position</i> 1 is the second item in the <i>list</i> <span style="font-family: monospace,monospace; font-size:1em;">a;b;c</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>listitem(1:04:47, 2, :)</nowiki></b></span>
<p style="margin-left:20pt;">Using the <i>delimiter</i> <span style="font-family: monospace,monospace; font-size:1em;">:</span>, returns item at <i>position</i> 2, which is the seconds value <span style="font-family: monospace,monospace; font-size:1em;">47</span> from the time <span style="font-family: monospace,monospace; font-size:1em;">1:04:47</span>.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="ListMix">ListMix(&hellip;)</span> ===
: Combine corresponding values from multiple lists into a new list, using a template to process each item.

{{function description box
| name=ListMix
| arguments=template, mode, list1, [list2, ... listN]
| description=
{{argument optional|mode|0}}
The [[#ListMix|ListMix()]] function processes the elements of one or more lists, returning a new list where each element is similar to the provided template modified with the elements of the list argument(s).
The number of list arguments to be mixed is variable, but at least one must be provided. The lists can have different lengths, with mode controlling the length of the returned list.
The first element of the returned list is generated by applying the first element of each provided list to the template; the second element is generated using the second element(s) of the list(s), and so on until all elements are processed, according to mode.

The <i>'''template'''</i> is a text string with placeholders like [L1], [L2], etc, indicating where the elements of the provided lists should be inserted. [L1] refers to elements of list1, [L2] refers to list2, and so on. The special placeholder [N] refers to the item number within the resulting list.

A <i>'''template'''</i> is also itself an Expression, so it can contain other functions/expressions. A template can be escaped using the escape sequence /#template#/. This is usually not required but may be useful to enter templates containing functions, commas, or other special symbols.

The default semi-colon list delimiter is used for both input and output lists.

{{argument table
| name=mode
| contents=
{{argument table row|0|Return as many elements as the '''longest''' provided list}}
{{argument table row|1|Return as many elements as the '''shortest''' provided list}}
{{argument table row|2|Return as many elements as the '''first''' provided list}}

}}
| examples=
'''{{monospace|<nowiki>ListMix(Actor #[N] is [L1],, a;b;c)</nowiki>}}'''
: Returns Actor #1 is a; Actor #2 is b; Actor #3 is c
This example uses mode 0 and demonstrates the usage of [N] and [L1] on a single list.

'''{{monospace|<nowiki>ListMix([L1][L2]=[L3], 0, a;b;c;d, 1;2;3;4;5, blue;red;green)</nowiki>}}'''
: Returns a1=blue; b2=red; c3=green; d4=; =5
Mode 0 returns 5 elements which is the length of the longest list. Note that on the last two the missing values on the template are also missing on the output.

'''{{monospace|<nowiki>ListMix([L1][L2]=[L3], 1, a;b;c;d, 1;2;3;4;5, blue;red;green)</nowiki>}}'''
: Returns a1=blue; b2=red; c3=green
: Mode 1 returns only 3 elements, the length of the shortest list.

'''{{monospace|<nowiki>ListMix([L1][L2]=[L3], 2, a;b;c;d, 1;2;3;4;5, blue;red;green)</nowiki>}}'''
: Returns : a1=blue; b2=red; c3=green; d4=
: Mode 2 returns only 4 elements, the length of the first list.

'''{{monospace|<nowiki>ListMix(FixCase([L1],3)=Math([L2]*[L3]),, aa;bb;cc, 10;20;30, 5;4;3)</nowiki>}}'''
: Returns : AA=50; BB=80; CC=90
: This example uses two different functions on the template to further transform each element of the lists before inserting it into the output.


'''{{monospace|<nowiki>ListMix(<img src=tooltip:actors\\[L1]> \ , 1, [Actors], 1;2;3;4;5)</nowiki>}}'''
: Returns (example): <img src=tooltip:actors\Daisy Ridley> ;<img src=tooltip:actors\Adam Driver> ;<img src=tooltip:actors\John Boyega> ;<img src=tooltip:actors\Oscar Isaac> ;<img src=tooltip:actors\Mark Hamill>
: This example transforms the [Actors] field into a list of <img> tags ready to load the actor thumbnails into the Theather View or Movie Tooltip. It uses mode 1 (shortest list) with a dummy [L2] list of 5 elements to make sure the resulting list is at most 5 items long. An alternative way to accomplish the same would be to use ListLimit([Actors],5) as [L1].

}}

=== <span id="ListSort">ListSort(&hellip;)</span> ===
: Sort a list of values.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="ListSort" 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>listsort(</b><i>list</i><b>, </b><i>mode</i><b>, </b><i>delimiter</i><b>)</b></span>
The [[#ListSort|ListSort()]] function sorts a <i>list</i> in the order according to <i>mode</i>, using the specified <i>delimiter</i>.

Available <i>mode</i> values:

<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>Ascending sort</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Descending sort</td></tr>
</table></div>

Argument <i>mode</i> is optional (defaults to 0).

Argument <i>delimiter</i> is optional (defaults to SEMICOLON).

|- 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>listsort(c;a;b)</nowiki></b></span>
<p style="margin-left:20pt;">Returns <span style="font-family: monospace,monospace; font-size:1em;">a;b;c</span>, using the default ascending <i>mode</i> and (<span style="font-family: monospace,monospace; font-size:1em;">:</span>) <i>delimiter</i>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>listsort(Joe Baxter/, Sally Henson/, Sue Smith, 1, /,)</nowiki></b></span>
<p style="margin-left:20pt;">Returns <span style="font-family: monospace,monospace; font-size:1em;">Sue Smith,Sally Henson,Joe Baxter</span>.
Note the requirement to escape the <span style="font-family: monospace,monospace; font-size:1em;">,</span> characters within the <i>list</i> string and in the specified <i>delimiter</i> itself.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>listsort([artist];[composer])</nowiki></b></span>
<p style="margin-left:20pt;">Sorts the combined artist and composer lists in ascending order.
Note the simple manual construction of a single List by combining the two List type fields, and forcing a <span style="font-family: monospace,monospace; font-size:1em;">;</span> between the two.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>


{{Function Type Page}}

Media Center provides several functions for the conversion, formatting and generation of dates and times.
Date and time for a Date-type field is stored internally as a single floating-point number,
where the integer portion represents the number of days since the Epoch, and the decimal portion represents the fraction of a day in seconds.
The Epoch is defined as December 30th, 1899 at 00:00:01.
Certain fractional values and whole numbers are used to encode Time-only and Year-only values.
For example, the internal Date value of "2" is considered as 1900, without a time when converted using the DateTime conversion format of [[#FormatDate|FormatDate()]], whereas adding a small fraction and using "2.001" instead produces a value of "1/1/1900 12:01 am".
These details are only relevant if you are doing conversions.

The Windows locale setting will affect the interpretation and formatting of date and time information.
=== <span id="ConvertDate">ConvertDate(&hellip;)</span> ===
: Converts a human-readable date to the internal format required for use in date fields.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="ConvertDate" 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>convertdate(</b><i>date_time string</i><b>)</b></span>
Converts a human-readable <i>date_time string</i> into the internal floating-point representation used by Media Center to store a date and time.
|- 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>convertdate(3//6//2012)</nowiki></b></span>
<p style="margin-left:20pt;">Returns the value <span style="font-family: monospace,monospace; font-size:1em;">40974</span>, which is the internal floating-point representation of the date string <span style="font-family: monospace,monospace; font-size:1em;">3/6/2012</span>.
This value can used by any field of type Date, or in any function that requires as input a Date type value.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatdate(convertdate(12//2//1985), decade))</nowiki></b></span>
<p style="margin-left:20pt;">Converts the date string <span style="font-family: monospace,monospace; font-size:1em;">12/2/1985</span> (note: December 2nd, not February 12th) into a Date type value,
and then formats the result as a decades grouping, returning <span style="font-family: monospace,monospace; font-size:1em;">1980's</span>.
This might be used for creating decade groupings.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="FormatDate">FormatDate(&hellip;)</span> ===
: Formats a date value in a specified manner.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="FormatDate" 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>formatdate(</b><i>date value</i><b>, </b><i>format specifier</i><b>, </b><i>empty label</i><b>)</b></span>
The [[#FormatDate|FormatDate()]] function provides custom formatting of date and time values through the use of a <i>format specifier</i>.
Output will be formatted according to <i>format specifier</i>.

The <i>date value</i> is a Media Center internal floating-point date/time representation, stored in Date fields,
and output from various functions such as [[#Now|Now()]] and [[#ConvertDate|ConvertDate()]].
To pass a field of type Date to [[#FormatDate|FormatDate()]], use the raw (unformatted) field specification, such as "[Date Imported,0]".

The <i>format specifier</i> provides a recipe for converting the internal value into a human-readable string.
Supported are a variety of Windows style, strftime() style, and Media Center-specific formats specifiers.
Construct the <i>format specifier</i> from any number or combination of those defined in the following table.
Additionally, any non-format characters will be output without interpretation.
This allows creating rich date/time output strings.
To output a word that is a reserved <i>format specifier</i>, surround the word with double-quotes.

The <i>empty label</i> argument will be output if the <i>date value</i> is empty.

<blockquote>
{| style="background: #f9f9f9;" border="1" cellpadding="1" cellspacing="0"
| style="background: #ecedf3;" | || colspan="3" align="center" style="background: #ecedf3;" | '''Specifier''' || style="background: #ecedf3;" | '''Description'''
|-
| rowspan="7" width="100" | '''Day'''
| align="center" width="65" | d || || Day || Day of the month as digits without leading zeros for single-digit days.
|-
| align="center" | dd || %d || || Day of the month as digits with leading zeros for single-digit days.
|-
| align="center" | ddd || %a || || Day of the week, abbreviated to three letters.
|-
| align="center" | dddd || %A || Dayname || Day of the week.
|-
| align="center" | || %w || || Day of the week as a decimal number, Sunday as 0 (0-6).
|-
| align="center" | || %j || || Day of the year (001-366)
|-
| align="center" | || %j ||Dayordinal|| Ordinal day of the month (e.g. 1st, 2nd, etc.).
|-
| rowspan="4" | '''Month'''
| align="center" | M || || || Month as digits without leading zeros for single-digit months.
|-
| align="center" | MM || %m || || Month as digits with leading zeros for single-digit months.
|-
| align="center" | MMM || %b || || Abbreviated month name, three letters (e.g. Apr, Nov).
|-
| align="center" | MMMM || %B || Month || Full Month name (e.g. April, November).
|-
| rowspan="4" | '''Year'''
| align="center" | y || || || Year represented only by the last digit.
|-
| align="center" | yy || %y || || Year represented only by the last two digits. A leading zero is added for single-digit years.
|-
| align="center" | yyyy || %Y || Year || Year represented by a full four or five digits.
|-
| align="center" | || || Decade || Year expressed as a decade (e.g. 1970's, 2010's)
|-
| rowspan="4" | '''Hour'''
| align="center" | h || || Hour || Hours with no leading zero for single-digit hours; 12-hour clock.
|-
| align="center" | hh || %I || || Hours with leading zero for single-digit hours; 12-hour clock.
|-
| align="center" | H || || || Hours with no leading zero for single-digit hours; 24-hour clock.
|-
| align="center" | HH || %H || || Hours with leading zero for single-digit hours; 24-hour clock.
|-
| rowspan="2" | '''Minute'''
| align="center" | m || || Minute || Minutes with no leading zero for single-digit minutes.
|-
| align="center" | mm || %M || || Minutes with leading zero for single-digit minutes.
|-
| rowspan="2" | '''Second'''
| align="center" | s || || Second || Seconds with no leading zero for single-digit seconds.
|-
| align="center" | ss || %S || || Seconds with leading zero for single-digit seconds.
|-
| rowspan="2" | '''AM/PM'''
| align="center" | t || || || One character time marker string, such as A or P.
|-
| align="center" | tt || %p || || Multi-character time marker string, such as AM or PM.
|-
| rowspan="5" | '''Combined'''
| align="center" | || %x || Date || Date expressed in the system's format.
|-
| align="center" | || %X || Time || Time expressed in the system's format.
|-
| align="center" | || %c || DateTime|| Date and time expressed in the system's format.
|-
| align="center" | || || ShortDate|| Age-conditional date formatted as one of "Year", "MMM d", or "MMM d Year".
|-
| align="center" | || || ShortDateTime || Date in ShortDate format plus Time.
|-
| rowspan="2" | '''Week Number'''
| align="center" | || %U || || Week number with the first Sunday as the first day of week one (00-53).
|-
| align="center" | || %W || || Week number with the first Monday as the first day of week one (00-53).
|-
| rowspan="4" | '''Miscellaneous'''
| align="center" | || || Elapsed || Time expressed as elapsed time (e.g. 2.5 hours).
|-
| align="center" | || ||ElapsedAgo|| Time expressed as elapsed time ago (e.g. 2.5 hours ago).
|-
| align="center" | || || Filename|| Date and time expressed in filename-friendly format, includes seconds to avoid filename collisions (e.g. 20040521-032221).
|-
| align="center" | || %% || || A percent (%) character.
|-
|}
</blockquote>

Argument <i>date value</i> is optional (defaults to [date,0]).

Argument <i>empty label</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>formatdate(year-month)</nowiki></b></span>
<p style="margin-left:20pt;">Outputs the file's date formatted as Year-Month, such as <span style="font-family: monospace,monospace; font-size:1em;">2012-April</span>. The default <i>date value</i> of <span style="font-family: monospace,monospace; font-size:1em;">[Date,0]</span> is used.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatdate([last played,0], yyyy//MM//dd, Not Yet)</nowiki></b></span>
<p style="margin-left:20pt;">Returns the file's last played date as year/month/day without the time, ignoring the system locale setting.
If a file has no last played value, the expression will output <span style="font-family: monospace,monospace; font-size:1em;">Not Yet</span> instead.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatdate([date modified,0], month %Y)</nowiki></b></span>
<p style="margin-left:20pt;">Returns the file's modification date/time in the form of a long month name and a four-digit year, such as <span style="font-family: monospace,monospace; font-size:1em;">December 2010</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatdate([date imported,0], The "year" is year)</nowiki></b></span>
<p style="margin-left:20pt;">Outputs the <span style="font-family: monospace,monospace; font-size:1em;">The year is ####</span>, where #### is the year the file was imported into the Library.
Note that the word <span style="font-family: monospace,monospace; font-size:1em;">year</span> must be surrounded in double-quotes to have it considered as literal text,
and not the <span style="font-family: monospace,monospace; font-size:1em;"><b>Year</b></span> <i>format specifier</i>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatdate([date imported,0], month)&amp;datatype=[month]</nowiki></b></span>
<p style="margin-left:20pt;">This examples is the same as the previous example, but includes a cast to the Month type <span style="font-family: monospace,monospace; font-size:1em;">&datatype=[month]</span>.
This cast can be used to cause chronological month-sorting, rather than month name alphabetic-sorting, in a panes or category view.
Data-type coercion is discussed [[#Specify_data_types_for_expression_based_fields|above]].</p>

Additional Examples

:[http://yabb.jriver.com/interact/index.php?topic=71000.msg479314#msg479314 Date formatting development discussion, usage tips and examples.]
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="Now">Now(&hellip;)</span> ===
: Retrieve and display the system date.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="Now" 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>now(</b><b>)</b></span>
The [[#Now|Now()]] function returns a floating-point value representing the current system date and time.
It is generally useful for performing date arithmatic in expressions that desire to figure out elapsed time.
Any raw date field or value representing a date can be subtracted from [[#Now|Now()]] to realize an elapsed time delta.
|- 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>now()</nowiki></b></span>
<p style="margin-left:20pt;">When run on Aug 17, 2013 at 19:28:00, returns approximately <span style="font-family: monospace,monospace; font-size:1em;">41503.811115995</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatdate(now(), date)</nowiki></b></span>
<p style="margin-left:20pt;">Returns the current date, without a time component, formatted according to the system's locale settings.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>formatdate(math(now() - 3, dddd dd MMMM yyyy H:mm)</nowiki></b></span>
<p style="margin-left:20pt;">The date from three days ago is formatted as something like <span style="font-family: monospace,monospace; font-size:1em;">Wednesday 14 August 2013 19:35</span>.
This is accomplished by subtracting the value <span style="font-family: monospace,monospace; font-size:1em;">3</span>, which would be days, from [[#Now|Now()]], and its output formatted by [[#FormatDate|FormatDate()]].</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>


{{Function Type Page}}

The functions in this section provide specific file-related information such as
a file's name, path, volume, and other Media Center internal information.

=== <span id="FileDBLocation">FileDBLocation(&hellip;)</span> ===
: Identifies a file's databases.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="FileDBLocation" 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>filedblocation(</b><i>format</i><b>)</b></span>
The [[#FileDBLocation|FileDBLocation()]] function returns identifiers in the specified <i>format</i> specified that indicate to which internal database(s) a file belongs.
Media Center maintains several internal databases to track a file's disposition.
This function is primarily for technical use only, and will have little utility for most users.

Available <i>format</i> values:

<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>Semicolon-separated list of formatted database names</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Numeric value of OR'd database bit flags</td></tr>
</table></div>

The table below provides common values output from [[#FileDBLocation|FileDBLocation()]]:
<div style="margin-left: 20pt;"><table style="border-spacing:0px; border-collapse:collapse; background: #f9f9f9" border="1">
<tr><td style="text-align:left; padding-right:20pt">Database name</td><td>Bit position</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Main</td><td>0</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Playing Now</td><td>1</td></tr>
<tr><td style="text-align:left; padding-right:20pt">CD</td><td>2</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Explorer</td><td>3</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Other (16)</td><td>5</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Other (6)</td><td>6</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Grouping</td><td>7</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Removed</td><td>8</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Podcast</td><td>10</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Other (4096)</td><td>12</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Stacks</td><td>14</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Category Images</td><td>18</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Bad</td><td>19</td></tr>
</table></div>

Argument <i>format</i> is optional (defaults to 0).

|- 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>filedblocation()</nowiki></b></span>
<p style="margin-left:20pt;">For a file in the <span style="font-family: monospace,monospace; font-size:1em;">Main</span> and <span style="font-family: monospace,monospace; font-size:1em;">Other (4096)</span> databases, the result would be <span style="font-family: monospace,monospace; font-size:1em;">Main; Other (4096)</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>filedblocation(1)</nowiki></b></span>
<p style="margin-left:20pt;">The result from the same file would be <span style="font-family: monospace,monospace; font-size:1em;">4096</span> (bit 0 and bit 12 set).</p>

Additional Examples

:[http://yabb.jriver.com/interact/index.php?topic=77896.msg539271#msg539271 Sample expression that uses FileDBLocation() to show a file's databases.]
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="FileFolder">FileFolder(&hellip;)</span> ===
: Returns the name of a file's parent.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="FileFolder" 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>filefolder(</b><i>filepath</i><b>, </b><i>level</i><b>)</b></span>
The [[#FileFolder|FileFolder()]] function returns parent sub-folder name for <i>filepath</i>.
The <i>level</i> argument specifies which parent sub-folder name to return,
working the <i>filepath</i> from right-to-left (i.e. bottom of the folder tree upwards to the top).
A value of 0 specifies a file's immediate parent, 1 its grandparent, etc., up to the root of the <i>filepath</i>.
A value of <span style="font-family: monospace,monospace; font-size:1em;">Unassigned</span> will be returned when the specified <i>level</i> exceeds the root of the <i>filepath</i>.

Argument <i>filepath</i> is optional (defaults to [filename]).

Argument <i>level</i> is optional (defaults to 0).

|- 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>filefolder()</nowiki></b></span>
<p style="margin-left:20pt;">Returns the name of the file's parent folder.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>filefolder([filename,0], 0)</nowiki></b></span>
<p style="margin-left:20pt;">Same as the previous example.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>filefolder(c:\some\folder\for\a\file.ape, 2)</nowiki></b></span>
<p style="margin-left:20pt;">Returns the great grandparent sub-folder named <span style="font-family: monospace,monospace; font-size:1em;">folder</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>filefolder(c:\some\other\folder\a\, 2)</nowiki></b></span>
<p style="margin-left:20pt;">Returns the folder named <span style="font-family: monospace,monospace; font-size:1em;">other</span>.
Notice the file name is not required in the <i>filepath</i>.
[[#FileFolder|FileFolder()]] works by looking from the end of the <i>filepath</i> until it finds a backslash <span style="font-family: monospace,monospace; font-size:1em;">\</span>.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="FileKey">FileKey(&hellip;)</span> ===
: Returns a file's unique internal identifier.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="FileKey" 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>filekey()(</b><b>)</b></span>
The [[#FileKey|FileKey()()]] function returns the unique identifier associated with a file.
Media Center assigns a unique identifier to each file in the Library.
It is useful in expressions when referring to individual files is necessary.
Services such as MCWS use this value to reference a file.
|- 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>filekey()</nowiki></b></span>
<p style="margin-left:20pt;">Returns a integer value, such as <span style="font-family: monospace,monospace; font-size:1em;">22029495</span>, unique for each file in the Library.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="FileName">FileName(&hellip;)</span> ===
: Returns a file's name component.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="FileName" 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>filename(</b><i>filepath</i><b>, </b><i>include suffix</i><b>)</b></span>
The [[#FileName|FileName()]] function returns the file name part of <i>filepath</i>. Inclusion of the file's suffix depends on the <i>include suffix</i> argument.

<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>Suppress file suffix</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Include file suffix</td></tr>
</table></div>

Argument <i>filepath</i> is optional (defaults to [filename]).

Argument <i>include suffix</i> is optional (defaults to 1).

|- 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>filename(C:\Music\File.mp3)</nowiki></b></span>
<p style="margin-left:20pt;">The output is <span style="font-family: monospace,monospace; font-size:1em;">File.mp3</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>filename(C:\Music\File 2.wav, 0)</nowiki></b></span>
<p style="margin-left:20pt;">The output does not include the file suffix, and is <span style="font-family: monospace,monospace; font-size:1em;">File 2</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>filename()</nowiki></b></span>
<p style="margin-left:20pt;">Returns the value contained in the field [filename (name)].</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="FilePath">FilePath(&hellip;)</span> ===
: Returns a file's path component.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="FilePath" 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>filepath(</b><i>filepath</i><b>)</b></span>
The [[#FilePath|FilePath()]] function will return the path portion of the specified file path.

The <i>filepath</i> should be a rooted path. For Windows, this includes the drive letter or leading <span style="font-family: monospace,monospace; font-size:1em;">\\</span> for UNC paths.
For *nix-based systems, this includes the root <span style="font-family: monospace,monospace; font-size:1em;">/</span>.
The field [filename (path)] is equivalent to [[#FilePath|FilePath()]], and is generally preferred.

Argument <i>filepath</i> is optional (defaults to [filename]).

|- 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>filepath(C:\Music\File.mp3)</nowiki></b></span>
<p style="margin-left:20pt;">Returns <span style="font-family: monospace,monospace; font-size:1em;">C:\Music</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>filepath()</nowiki></b></span>
<p style="margin-left:20pt;">Returns the value contained in the field [filename (path)].</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="FileVolume">FileVolume(&hellip;)</span> ===
: Returns a file's volume name component.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="FileVolume" 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>filevolume(</b><i>filepath</i><b>)</b></span>
The [[#FileVolume|FileVolume()]] function returns the volume name component of the specified file path.
The path should be a rooted path (see the same comment above for [[#FilePath|FilePath()]]. For *nix-based systems, the output is empty.
The field [volume name] is equivalent to [[#FileVolume|FileVolume()]], and is generally preferred.

Argument <i>filepath</i> is optional (defaults to [filename]).

|- 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>filevolume(C:\Music\File.mp3)</nowiki></b></span>
<p style="margin-left:20pt;">Outputs <span style="font-family: monospace,monospace; font-size:1em;">C:</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>filevolume()</nowiki></b></span>
<p style="margin-left:20pt;">Returns the value contained in the field [volume name].</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>


{{incomplete}}
{{function type page}}

The [[expression language]] is largely used to evaluate one file at a time. The grammar implies that something like {{monospace|Field(Artist)}} should get the Artist value for the current file being evaluated. Grouping Functions are a special class of functions that operate on a group of files, instead of on individual files. A simple example would be a function to count the number of artists in the current group.

Grouping Functions may only be used in relevant areas where Media Center displays groups of files (most notably in [[Categories]] and the [[Tag Action Window]]), and not to individual file listings (such as an expression column in a File Details View).

=== <span id="GroupCount">GroupCount(&hellip;)</span> ===
: Counts the members of a specified group (in a category or field).

{{function description box
| name=GroupCount
| arguments=field
| description=
{{argument optional|field|current grouping}}

GroupCount() can be used to count the members of a group of files.

| examples=
'''Example Threads:'''
* [http://yabb.jriver.com/interact/index.php?topic=81766.msg564453#msg564453 Matt introduces Grouping Functions]
* [http://yabb.jriver.com/interact/index.php?topic=94848.msg663421#msg663421 Use field names, not field values (square bracket notation)]
}}

=== <span id="GroupCount">GroupCount(&hellip;)</span> ===
: Counts the members of a specified group (in a category or field).

{{function description box
| name=GroupSummary
| arguments=field
| description=
{{argument optional|field|current grouping}}

Smartly summarizes the members of a specified group (mode, mean, min, max, etc as is most logical for that grouping).
| examples=
'''Example Threads:'''
: [http://yabb.jriver.com/interact/index.php?topic=81766.msg564453#msg564453 Matt introduces Grouping Functions]
: [http://yabb.jriver.com/interact/index.php?topic=94848.msg663421#msg663421 Use field names, not field values (square bracket notation)]
}}


{{Function Type Page}}

The functions in this section are varied and have specialized applicability.
Some are primarily used internally by MC to generate values available in various Library fields.

=== <span id="AlbumArtist">AlbumArtist(&hellip;)</span> ===
: Returns a file's calculated album artist.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="AlbumArtist" 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>albumartist(</b><b>)</b></span>
The [[#AlbumArtist|AlbumArtist()]] function calculates the album artist value used in various views and fields.
It is used to populate the Library field <span style="font-family: monospace,monospace; font-size:1em;">album artist (auto)</span> with its value.
Either the field or [[#AlbumArtist|AlbumArtist()]] can be used.
|- 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>albumartist()</nowiki></b></span>
<p style="margin-left:20pt;">Returns the value present in the <span style="font-family: monospace,monospace; font-size:1em;">album artist (auto)</span> field.</p>

Additional Examples

:[http://wiki.jriver.com/index.php/Album_Artist_and_Album_Artist_%28Auto%29 Describes the algorithm used by AlbumArtist() to calculate the "album artist (auto)" field's value.]
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="AlbumKey">AlbumKey(&hellip;)</span> ===
: Returns a unique album key for a file.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="AlbumKey" 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>albumkey(</b><b>)</b></span>
The [[#AlbumKey|AlbumKey()]] function returns "[album artist (auto)] - [album]".
It is a convenience function, used to return the generally unique album / artist combination string used to distinguish
between two like-named albums such as "Greatest Hits".
|- 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>albumkey()</nowiki></b></span>
<p style="margin-left:20pt;">For an album named <span style="font-family: monospace,monospace; font-size:1em;">Greatest Hits</span> and an album artist (auto) of <span style="font-family: monospace,monospace; font-size:1em;">The Eagles</span>, returns <span style="font-family: monospace,monospace; font-size:1em;">The Eagles - Greatest Hits</span>.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="AlbumType">AlbumType(&hellip;)</span> ===
: Returns the album type for a file.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="AlbumType" 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>albumtype(</b><b>)</b></span>
The [[#AlbumType|AlbumType()]] function returns a description regarding an album's completeness and its quantity of artists.
It is used to populate the Library field <span style="font-family: monospace,monospace; font-size:1em;">album type</span> with its value.
Either the field or [[#AlbumType|AlbumType()]] can be used.
|- 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>albumtype()</nowiki></b></span>
<p style="margin-left:20pt;">Returns, for example, <span style="font-family: monospace,monospace; font-size:1em;">Single artist (complete)</span>, or <span style="font-family: monospace,monospace; font-size:1em;">Multiple artists (incomplete)</span>.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="AudioAnalysisState">AudioAnalysisState(&hellip;)</span> ===
: Returns the state of audio analysis for a file.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="AudioAnalysisState" 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>audioanalysisstate(</b><b>)</b></span>
The [[#AudioAnalysisState|AudioAnalysisState()]] function returns a file's state of audio analysis.
It can be used to determine if audio analysis (Library Tools > Analyze Audio...) should be performed on a media file.
The [[#AudioAnalysisState|AudioAnalysisState()]] function will return a string indicating the state of analysis.
Possible values are currently:

<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>Needed</b></td><td>Audio analysis is needed</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>Done</b></td><td>Audio analysis is complete</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>N/A</b></td><td>The file type does not support audio analysis</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>Excluded (No Audio)</b></td><td>The file type supports analysis, but contains no audio</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>Failed on <date></b></td><td>Audio analysis failed on the <i><date></i> specified</td></tr>
</table></div>
|- 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>audioanalysisstate()</nowiki></b></span>
<p style="margin-left:20pt;">Returns, for example, <span style="font-family: monospace,monospace; font-size:1em;">Needed</span> for files that require audio analysis, or <span style="font-family: monospace,monospace; font-size:1em;">N/A</span> if the file type does not support audio analysis.</p>

Additional Examples

:[http://yabb.jriver.com/interact/index.php?topic=82025.0 Describes the improved audio analysis and R128 volume leveling feature.]
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="Counter">Counter(&hellip;)</span> ===
: Counts upwards in specified increments.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="Counter" 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>counter(</b><i>start value</i><b>, </b><i>increment</i><b>)</b></span>
The [[#Counter|Counter()]] function outputs a monotonically increasing number (more simply stated, it counts) from a <i>start value</i>,
and each time called, increases by the <i>increment</i> value.
It is useful for sequentially numbering fields.
The [[#Counter|Counter()]] function maintains an internal counter, and it resets itself to zero after five seconds of inactivity.

Because [[#Counter|Counter()]] continues to count, it should only be used in single-use situations such as assigning its output to some field through field value assignment, for example, <span style="font-family: monospace,monospace; font-size:1em;">=counter()</span>.
With proper care, it can be used as part of an expression in the Rename, Move & Copy tool, but see also [[#CustomData|CustomData()]].

It is not recommended for use in any context that continually refreshes its content, such as in a panes column, file list, or expression-based custom query.
Probably the best way to understand the results is to test the first example below as an expression column in a file list, and move the mouse around over that column.

Argument <i>start value</i> is optional (defaults to 1).

Argument <i>increment</i> is optional (defaults to 1).

|- 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>counter()</nowiki></b></span>
<p style="margin-left:20pt;">Outputs values starting at <span style="font-family: monospace,monospace; font-size:1em;">1</span>, and incrementing by one, it will return <span style="font-family: monospace,monospace; font-size:1em;">1</span>, <span style="font-family: monospace,monospace; font-size:1em;">2</span>, <span style="font-family: monospace,monospace; font-size:1em;">3</span>, ... until no longer called.
This might be used, for example, to assign to the [Track #] field of several tracks using the field assignment expression <span style="font-family: monospace,monospace; font-size:1em;">=counter()</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>padnumber(counter(370, 2), 4)</nowiki></b></span>
<p style="margin-left:20pt;">Outputs numbers beginning from 370, incremented by two each, and padded to four digits. For example, <span style="font-family: monospace,monospace; font-size:1em;">0370</span>, <span style="font-family: monospace,monospace; font-size:1em;">0372</span>, <span style="font-family: monospace,monospace; font-size:1em;">0374</span>, etc.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="CustomData">CustomData(&hellip;)</span> ===
: Returns internal data to the expression language.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="CustomData" 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>customdata(</b><i>mode</i><b>)</b></span>
The [[#CustomData|CustomData()]] function supports returning Media Center internal data to the expression language.
Currently the only supported <i>mode</i> provides a file's row number in a file list, which is useful in the Rename, Move & Copy tool to assist in numbering files.
It can also be used in expressions in a playlist to obtain the file's sequence number.

Available <i>mode</i> values:

<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>#</b></td><td>Returns a file's row number in a file list</td></tr>
</table></div>
|- 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>Spring_Break_Bash_padnumber(customdata(#), 4)</nowiki></b></span>
<p style="margin-left:20pt;">In the Rename, Move & Copy tool, each consecutive file would be named <span style="font-family: monospace,monospace; font-size:1em;">Spring_Break_Bash_</span> followed by a four digit, zero-padded number starting at <span style="font-family: monospace,monospace; font-size:1em;">0001</span>.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="Math">Math(&hellip;)</span> ===
: Evaluates a given mathematical formula.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="Math" 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>math(</b><i>expression</i><b>)</b></span>
The [[#Math|Math()]] function performs mathematical calculations.
Standard arithmetic operators are supported, as are various numerical, trigonometric, and comparative functions.
Simple variables are supported, as are multiple statements.

<blockquote>
{| style="background: #f9f9f9;" border="1" cellpadding="1" cellspacing="0"
| rowspan="6" width="100" valign="top" | '''Arithmetic Operators'''
| align="center" width="65" | + || Addition
|-
| align="center" | - || Subtraction
|-
| align="center" | * || Multiplication
|-
| align="center" | / || Division
|-
| align="center" | ^ || Power
|-
| align="center" | % || Modulo
|-
| rowspan="3" | '''Boolean Operators'''
| align="center" | ! || NOT
|-
| align="center" | & || AND
|-
| align="center" | <nowiki>|</nowiki> || OR
|-
| rowspan="1" | '''Grouping Operators'''
| align="center" | ( ) || Precedence grouping
|-
| rowspan="4" | '''Comparison Operators'''
| align="center" | } || Absolute value maximum (i.e. x or y that is maximum distance from 0).
|-
| align="center" | { || Absolute value minimum (i.e. x or y that is minimum distance from 0).
|-
| align="center" | > || Distance between x and y, positive when x greater than y, negative otherwise.
|-
| align="center" | < || Distance between x and y, positive when x less than y, negative otherwise.
|-
| rowspan="7" | '''Functions'''
| align="center" | abs(x) || Returns the absolute value of x.
|-
| align="center" | sign(x) || Returns the sign of x (1 when x >= 0, -1 when x < 0).
|-
| align="center" | log(x) || Returns the natural logarithm (base e) of x.
|-
| align="center" | log10(x) || Returns the common logarithm (base 10) of x.
|-
| align="center" | pow(x,y) || Returns x raised to the y-th power.
|-
| align="center" | rand(x) || Returns a random value ranging between 0 to x.
|-
| align="center" | randn(x) || Returns a random value ranging between -x and x.
|-
| rowspan="5" | '''Comparison Functions'''
| align="center" | min(x,y) || Returns the minimum value of x and y.
|-
| align="center" | max(x,y) || Returns the maximum value of x and y.
|-
| align="center" | equal(x,y) || Returns 1 when x = y, 0 otherwise.
|-
| align="center" | below(x,y) || Returns 1 when x < y, 0 otherwise.
|-
| align="center" | above(x,y) || Returns 1 when x > y, 0 otherwise.
|-
| rowspan="4" | '''Formatting Functions'''
| align="center" | int(x) || Returns the integer portion of x.
|-
| align="center" | frac(x) || Returns the fractional portion of x.
|-
| align="center" | round(x) || Returns x rounded to the nearest whole number.
|-
| align="center" | trunc(x,n) || Returns x truncated to n decimal places.
|-
| rowspan="6" | '''Trigonometric Functions'''
| align="center" | atan(x) || Returns the arctangent of x.
|-
| align="center" | cos(x) || Returns the cosine of x.
|-
| align="center" | sin(x) || Returns the sine of x.
|-
| align="center" | tan(x) || Returns the tangent of x.
|-
| align="center" | abscos(x) || Returns the absolute value of cosine(x).
|-
| align="center" | abssin(x) || Returns the absolute value of sin(x).
|}
</blockquote>

The order of operator precedence is summarized as follows, from top to bottom:

<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>(&nbsp;&nbsp;&nbsp;)</b></td><td>&nbsp;</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>&nbsp;&nbsp;!</b></td><td>&nbsp;</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>&nbsp;&nbsp;^</b></td><td>&nbsp;</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>*&nbsp;&nbsp;&nbsp;/</b></td><td>Left to right</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>+&nbsp;&nbsp;&nbsp;-</b></td><td>Left to right</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b><nowiki>|</nowiki>&nbsp;&nbsp;&nbsp;&amp;</b></td><td>Left to right</td></tr>
</table></div>

Variables may be assigned and used by specifying a simple string of letters. Examples: <span style="font-family: monospace,monospace; font-size:1em;">math(val=2)</span> or <span style="font-family: monospace,monospace; font-size:1em;">math(x=pow(2,3))</span>.

Multiple equations may be specified, each separated by a semicolon.
Expressions are evaluated left to right.
The final value of the [[#Math|Math()]] function will be the result of the right-most equation. For example, the equation <span style="font-family: monospace,monospace; font-size:1em;">math(x=4; pow(2^x))</span> will output 16.

<b>Note</b>: Empty fields

Fields used inside of [[#Math|Math()]] are expanded (interpolated) directly.
Fields with empty values may produce incomplete [[#Math|Math()]] statements.
For example, if the field [number plays] is empty, an <i>expression</i> such as <span style="font-family: monospace,monospace; font-size:1em;">math([number plays] + 2)</span> would be seen
by [[#Math|Math()]] as <span style="font-family: monospace,monospace; font-size:1em;"> + 2</span>.
This incomplete <i>expression</i> would produce a syntax error. See the Additional Examples for more information.

<b>Note</b>: Locales and Commas

Special care must be taken with the [[#Math|Math()]] function and locales that use <span style="font-family: monospace,monospace; font-size:1em;">,</span> (comma) as a decimal separator.
Many Media Center fields and the return values from functions may contain comma as the decimal point.
Your expressions will need to [[#Replace|Replace()]] these before passing the values to [[#Math|Math()]],
which always uses dot <span style="font-family: monospace,monospace; font-size:1em;">.</span> as the numeric decimal point.

For example, the <i>expression</i> <span style="font-family: monospace,monospace; font-size:1em;">math(1,5 + 1,5)</span> will fail since [[#Math|Math()]] does not consider <span style="font-family: monospace,monospace; font-size:1em;">1,5</span> to be a valid number.

Fields that cause problems are any fields that produce floating-point values, such as any Date type field in raw format
(e.g. <span style="font-family: monospace,monospace; font-size:1em;">[date,0]</span>, <span style="font-family: monospace,monospace; font-size:1em;">[last played,0]</span>, <span style="font-family: monospace,monospace; font-size:1em;">[date modified,0]</span>, and <span style="font-family: monospace,monospace; font-size:1em;">[date imported,0]</span>), or any textual field that contains
floating-point values that will be used for various calculations (e.g. any of the Dynamic Range variants).
Certain functions such as [[#Now|Now()]] and [[#ConvertTime|ConvertTime()]] also return localized floating-point values.

Handling this problem is not difficult.
Before passing any floating point number to [[#Math|Math()]], use [[#Replace|Replace()]] first. See the examples below.
|- 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>math(10 + 4)</nowiki></b></span>
<p style="margin-left:20pt;">Returns 14.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>math(10 + 2 * 25)</nowiki></b></span>
<p style="margin-left:20pt;">Returns 60, demonstrating that multiplication has higher precedence than addition.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>math((10 + 2) * 25)</nowiki></b></span>
<p style="margin-left:20pt;">Returns 300, demonstrating that parenthesis grouping has higher precedence than multiplication.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>math(replace(now(), /,, .) - replace([last played,0], /,, .))</nowiki></b></span>
<p style="margin-left:20pt;">The <span style="font-family: monospace,monospace; font-size:1em;">,</span> is replaced by a <span style="font-family: monospace,monospace; font-size:1em;">.</span> in the output of both [[#Now|Now()]] and in the raw field value <span style="font-family: monospace,monospace; font-size:1em;">[last played,0]</span>.
Note that the comma must be escaped so that it is seen as an argument and not as an argument separator.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>math(replace(now() - [last layed,0], /,, .))</nowiki></b></span>
<p style="margin-left:20pt;">The same as the previous example, but is more efficient and simpler since it calls [[#Replace|Replace()]] just once on the entire string to be passed to [[#Math|Math()]].</p>

Additional Examples

:[http://yabb.jriver.com/interact/index.php?topic=58110.0 An explanation and some solutions for fields that evaluate to empty within Math().]
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="Size">Size(&hellip;)</span> ===
: Returns a file's size in a format specific to the media type.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="Size" 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>size(</b><b>)</b></span>
The [[#Size|Size()]] function returns media size information specific to the particular media type.
It is used to populate the Library fields <span style="font-family: monospace,monospace; font-size:1em;">duration</span> and <span style="font-family: monospace,monospace; font-size:1em;">dimensions</span> with their values.
Either the field or [[#Size|Size()]] can be used.

Type of information reported by size for the file's media type:

<div style="margin-left: 20pt;"><table style="border-spacing:0px; border-collapse:collapse; background: #f9f9f9">
<tr><td style="text-align:left; padding-right:20pt">Audio</td><td>Duration</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Video</td><td>Duration</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Image</td><td>Dimensions</td></tr>
<tr><td style="text-align:left; padding-right:20pt">Data</td><td>No information returned.</td></tr>
</table></div>
|- 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>size()</nowiki></b></span>
<p style="margin-left:20pt;">Returns values such as <span style="font-family: monospace,monospace; font-size:1em;">400x225</span> for images, or <span style="font-family: monospace,monospace; font-size:1em;">3:09</span> for audio files.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="TrackNumber">TrackNumber(&hellip;)</span> ===
: Returns a file's track # value.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="TrackNumber" 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>tracknumber(</b><b>)</b></span>
The [[#TrackNumber|TrackNumber()]] function returns a file's track #, or 0 if the no value exists.
It is used to populate the Library field <span style="font-family: monospace,monospace; font-size:1em;">track #</span> with its value.
Either the field or [[#TrackNumber|TrackNumber()]] can be used.
|- 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>tracknumber()</nowiki></b></span>
<p style="margin-left:20pt;">Returns the value present in the <span style="font-family: monospace,monospace; font-size:1em;">track #</span> field.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="TVInfo">TVInfo(&hellip;)</span> ===
: Miscellaneous television and other pre-formatted information.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="TVInfo" 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>tvinfo(</b><i>type</i><b>)</b></span>
The [[#TVInfo|TVInfo()]] function is multi-purpose, and returns a specific <i>type</i> of information about television recordings, programs,
and pre-formatted informational strings for use in captions, thumbnails, grouping, etc.

Available <i>type</i> values:

<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>IsProgram</b></td><td>Returns 1 if the file is a program, 0 otherwise</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>IsGuideProgram</b></td><td>Returns 1 if the file is a guide program, 0 otherwise</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>IsRecordedProgram</b></td><td>Returns 1 if the file is a recorded program, 0 otherwise</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>IsTVChannel</b></td><td>Returns 1 if the selection is a TV Channel program</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>Channel</b></td><td>Returns the channel name associated with a given program</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>ChannelKeywords</b></td><td>Returns channel keywords</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>ChannelProgramNow</b></td><td>Returns the name of a playing TV program on a given channel, empty otherwise</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>Date</b></td><td>Returns a program's date</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>DateNoTime</b></td><td>Same as Date, but without the time.</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>NameDisplay</b></td><td>Returns [name]: [series] or just [name]</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>NameDisplayWithDate</b></td><td>NameDisplay + ([year])</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>Record</b></td><td>Returns 1 if the program is scheduled to be recorded, 0 otherwise</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>RecordMark</b></td><td>Returns a red dot if the program is schedule to be recorded.</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>RecordStatus</b></td><td>Returns a string describing the record status, blank if not to be recorded.</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>SeriesDisplay</b></td><td>Returns [series] or [name]</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>SeasonDisplay</b></td><td>Returns [season]</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>SeasonEpisode</b></td><td>Returns [season].[episode]</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>TimeDisplay</b></td><td>Returns program start time (system time format), or "Showing" if program on now</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>TimeDisplayNoOnNow</b></td><td>TimeDisplay without on now handling</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>SizeDisplay</b></td><td>Returns [duration] ([file size]) or [dimensions] ([file size])</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>WatchedDisplay</b></td><td>Returns Watched() information, such as No, Yes, 80%, etc.</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>IsOnNonTopGroupedChannel</b></td><td>Returns 1 if an EPG program is on a channel that is grouped as a non-top member, 0 otherwise.</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>ProgramChannelNumber</b></td><td>Returns channel number of the television channel the program is on.</td></tr>
</table></div>
|- 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>tvinfo(namedisplay)</nowiki></b></span>
<p style="margin-left:20pt;">Returns formatted name and series output. If the file has no <span style="font-family: monospace,monospace; font-size:1em;">[series]</span> value, only <span style="font-family: monospace,monospace; font-size:1em;">[name]</span> is output.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

Latest revision as of 02:27, 24 May 2020

Redirect to:

Retrieved from "https://wiki.jriver.com/index.php?title=Function_Index&oldid=16126"