Test and Comparison Functions: Difference between revisions

From wiki.jriver.com
Jump to navigation Jump to search
No edit summary
 
(65 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Function Type Page}}
{{Function Type Page}}


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


Line 8: Line 8:


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

{{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=
| examples=
'''{{monospace|EXAMPLE1}}'''
'''{{monospace|compare([bitrate], &lt;, 320)}}'''
: Returns 1 when the bit rate is less than 320 (Kbps), and 0 otherwise.
: EXAMPLETEXT
'''{{monospace|if(compare(math(now() - [date modified, 0]), &gt;, 21), Expired, formatdate([date modified, 0], elapsed))}}'''
'''{{monospace|EXAMPLE2}}'''
: Outputs the age of files under 21 days old, or {{monospace|Expired}} for older files.
: EXAMPLETEXT
'''{{monospace|EXAMPLE3}}'''
: EXAMPLETEXT
'''{{monospace|EXAMPLE4}}'''
: EXAMPLETEXT
}}
}}


=== <span id="IsDigit">IsDigit(&hellip;)</span> ===
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
: Determines whether or not a given value is digits.
|- id="Compare" 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>compare(</b><i>value1</i><b>, </b><i>operator</i><b>, </b><i>value2</i><b>)</b></span>
The [[#Compare|Compare()]] function compares two numeric values <i>value1</i> and <i>value2</i> using the specified <i>operator</i>.


{{function description box
Available <i>operator</i> values:
| name=IsDigit
| arguments=value, characters
| description=
{{argument optional|Characters|<i>all</i>}}
The [[#IsDigit|IsDigit()]] function tests the given <i>value</i> to determine whether or not it is digits, returning "1" for a positive result, and "0" for a negative (not digits) result.


| examples=
<div style="margin-left: 20pt;"><table style="border-spacing:0px; border-collapse:collapse; background: #f9f9f9">
'''{{monospace|<nowiki>isdigit(1234)</nowiki>}}'''
<tr><td style="text-align:left; padding-right:20pt"><b>=</b></td><td>Equivalence</td></tr>
: Returns "1" as these are all digits.
<tr><td style="text-align:left; padding-right:20pt"><b><</b></td><td>Less than</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b><=</b></td><td>Less than or equal to</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>></b></td><td>Greater than</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>>=</b></td><td>Greater than or equal to</td></tr>
</table></div>


'''{{monospace|<nowiki>isdigit(Check1-2)</nowiki>}}'''
Outputs 1 if the comparison is true, and 0 otherwise.
: Returns "0" as these are not all digits.
|- 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>compare([bitrate], &lt;, 320)</nowiki></b></span>
=== <span id="IsDriveMissing">IsDriveMissing(&hellip;)</span> ===
<p style="margin-left:20pt;">Returns 1 when the bit rate is less than 320 (Kbps), and 0 otherwise.</p>
: Tests for the prescence of a specified drive.
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>if(compare(math(now() - [date modified, 0]), &gt;, 21), Expired, formatdate([date modified, 0], elapsed))</nowiki></b></span>

<p style="margin-left:20pt;">Outputs the age of files under 21 days old, or <span style="font-family: monospace,monospace; font-size:1em;">Expired</span> for older files.</p>
{{function description box
|}
| name=IsDriveMissing
<div style="text-align:right;">([[#top|Back to top)]]</div>
| arguments=Drive
| description=
The [[#IsDriveMissing|IsDriveMissing()]] function tests for the prescence of a specified drive, returning "1" for a positive (missing) result, and "0" for a negative (drive exists) result. Note that this function cannot work with drive names at all, <i>only</i> drive letters.

| examples=
'''{{monospace|<nowiki>isdrivemissing(C:\)</nowiki>}}'''
: Returns "0" as drive C: is available.

'''{{monospace|<nowiki>isdrivemissing(C:)</nowiki>}}'''
: Returns "0" as drive C: is available. Demonstrating the backslash is not essential for the function to operate correctly.

'''{{monospace|<nowiki>if(IsDriveMissing(V:),Please Connect Drive [volume name],Files are availble)</nowiki>}}'''
: Returns <nowiki>"Please Connect Drive V:"</nowiki> for all files residing on drive V: if it is missing, or, <nowiki>Files are availble</nowiki> if the drive is connected.
}}

=== <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="IsEqual">IsEqual(&hellip;)</span> ===
=== <span id="IsEqual">IsEqual(&hellip;)</span> ===
: Compares two values in one of nine specified modes.
: Compares two values in one of seventeen specified modes.


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="IsEqual" valign="top"
| name=IsEqual
| arguments=value1, value2, mode
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>isequal(</b><i>value1</i><b>, </b><i>value2</i><b>, </b><i>mode</i><b>)</b></span>
{{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.
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.
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>.
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
Available <i>mode</i> values:
| 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}}.


'''{{monospace|<nowiki>if(isequal([Genre], Pop;Rock, 9), Pop or some sort of Rock, Not Pop or Rock)</nowiki>}}'''
<div style="margin-left: 20pt;"><table style="border-spacing:0px; border-collapse:collapse; background: #f9f9f9">
: Because compare <i>mode</i> 9 has been specified, if '''<i>either</i>''' of the case sensitive sub-strings {{monospace|Rock}} or {{monospace|Pop}} appear anywhere in the Genre List Type field, the expression will return {{monospace|Pop or some sort of Rock}}, and if not it will return {{monospace|Not Pop or Rock}}.
<tr><td style="text-align:left; padding-right:20pt"><b>0</b></td><td>Case-sensitive string compare for equality</td></tr>
: Genres that match include "{{monospace|Pop}}" "{{monospace|Rock}}" "{{monospace|Pop;Rock}}" "{{monospace|Pop Rock}}" "{{monospace|Rock;Pop}}" "{{monospace|Popular;Rock}}" "{{monospace|Popular;Rock & Roll}}" "{{monospace|Rock & Roll}}" "{{monospace|Funk Rock}}" and "{{monospace|Alt. Rock}}", among others.
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Case-insensitive string compare for equality</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>2</b></td><td>Numeric compare for equality</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>3</b></td><td>Numeric less than</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>4</b></td><td>Numeric less than or equal to</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>5</b></td><td>Numeric greater than</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>6</b></td><td>Numeric greater than or equal to</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>7</b></td><td>Substring search (case sensitive)</td></tr>
<tr><td style="text-align:left; padding-right:20pt"><b>8</b></td><td>Substring search (case insensitive)</td></tr>
</table></div>


'''{{monospace|<nowiki>if(isequal([Genre], Pop;Rock, 11), Some sort of Pop Rock, Not Pop Rock)</nowiki>}}'''
Argument <i>mode</i> is optional (defaults to 0).
: Because compare <i>mode</i> 11 has been specified, if the case sensitive sub-strings {{monospace|Pop}} and {{monospace|Rock}} '''<i>both</i>''' appear anywhere in the Genre List Type field, the expression will return {{monospace|Some sort of Pop Rock}}, and if not it will return {{monospace|Not Pop Rock}}.
: Genres that match include "{{monospace|Pop;Rock}}" "{{monospace|Pop Rock}}" "{{monospace|Rock;Pop}}" "{{monospace|Popular;Rock}}" and "{{monospace|Popular;Rock & Roll}}", among others.
: Genres that do not match include "{{monospace|Pop}}" "{{monospace|Rock}}" "{{monospace|Rock & Roll}}" "{{monospace|Funk Rock}}" and "{{monospace|Alt. Rock}}", among others.


'''{{monospace|<nowiki>if(isequal([Genre], Pop;Rock, 13), Pop or some sort of Rock, Not Pop or Rock)</nowiki>}}'''
|- valign="top"
: Because compare <i>mode</i> 13 has been specified, if '''<i>either</i>''' of the case sensitive full strings {{monospace|Rock}} or {{monospace|Pop}} appear in the Genre List Type field, the expression will return {{monospace|Pop or some sort of Rock}}, and if not it will return {{monospace|Not Pop or Rock}}.
! 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
: Genres that match include "{{monospace|Pop;Rock}}" "{{monospace|Pop;Rock & Roll}}" "{{monospace|Popular;Rock}}", among others.
|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>isequal([artist], [album], 1)</nowiki></b></span>
: Genres that do not match include "{{monospace|Pop Rock}}" "{{monospace|Rock & Roll}}" "{{monospace|Rock, Popular}}" "{{monospace|Popular;Rock & Roll}}" "{{monospace|Funk Rock}}" and "{{monospace|Alt. Rock}}", among others.
<p style="margin-left:20pt;">If the artist and album values are the same, the output will be 1, otherwise, the output will be 0.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>if(isequal([artist], [album], 1), Eponymous, [album])</nowiki></b></span>
<p style="margin-left:20pt;">The [[#If|If()]] function basis its decision on the outcome of [[#IsEqual|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.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>if(isequal([artist], [album], 1), Eponymous/,, [album]/))</nowiki></b></span>
<p style="margin-left:20pt;">This example demonstrates the character escaping mentioned in the overview earlier.
Here, we want the output to be either <span style="font-family: monospace,monospace; font-size:1em;">Eponymous,</span> (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.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>if(isequal([filename (path)], classical, 8), Classical, Not Classical)</nowiki></b></span>
<p style="margin-left:20pt;">Because compare <i>mode</i> 8 has been specified, if the word <span style="font-family: monospace,monospace; font-size:1em;">classical</span> appears anywhere in the case-insensitive file path, the expression will return <span style="font-family: monospace,monospace; font-size:1em;">Classical</span>, and if not it will return <span style="font-family: monospace,monospace; font-size:1em;">Not Classical</span>.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>


'''{{monospace|<nowiki>if(isequal([Genre], Pop;Rock, 15), Some sort of Pop Rock, Not Pop Rock)</nowiki>}}'''
=== <span id="IsEmpty">IsEmpty(&hellip;)</span> ===
: Because compare <i>mode</i> 15 has been specified, if the case sensitive full strings {{monospace|Pop}} and {{monospace|Rock}} '''<i>both</i>''' appear in the Genre List Type field, the expression will return {{monospace|Some sort of Pop Rock}}, and if not it will return {{monospace|Not Pop Rock}}.
: Tests a value for emptiness.
: Genres that match include "{{monospace|Pop;Rock}}" "{{monospace|Pop;Electronic;Rock}}" "{{monospace|Rock;Pop,Alt.Rock}}" "{{monospace|Rock;Pop}}" and "{{monospace|Rock;Punk;Pop}}", among others.
: Genres that do not match include "{{monospace|Pop}}" "{{monospace|Rock}}" "{{monospace|Popular;Rock}}" and "{{monospace|Pop;Rockabilly}}", among others.


}}
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="IsEmpty" 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>isempty(</b><i>value</i><b>, </b><i>mode</i><b>)</b></span>
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.


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


{{function description box
<div style="margin-left: 20pt;"><table style="border-spacing:0px; border-collapse:collapse; background: #f9f9f9">
| name=IsInPlayingNow
<tr><td style="text-align:left; padding-right:20pt"><b>0</b></td><td>String test (field must be empty to get a positive result)</td></tr>
| arguments=filepath
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Numerical test (field must be empty, or contain 0 to get a positive result)</td></tr>
| description=
</table></div>
{{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="IsLowerCase">IsLowerCase(&hellip;)</span> ===
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.
: Tests to see if a value is lower case.
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.


{{function description box
Pay particular attention to the third example offered below, as it covers a caveat that comes with this particular function.
| name=IsLowerCase
| arguments=value, characters
| description=
{{argument optional|Characters|<i>all</i>}}
The [[#IsLowerCase|IsLowerCase()]] function tests the given <i>value</i> to determine whether or not it is lower case, returning "1" for a positive result, and "0" for a negative result.


| examples=
Argument <i>mode</i> is optional (defaults to 0).
'''{{monospace|<nowiki>IsLowerCase(tesT,1)</nowiki>}}'''
: Returns "1" as only one character is specified for the check, and the first character, is lower case.


'''{{monospace|<nowiki>IsLowerCase(tesT,3)</nowiki>}}'''
|- valign="top"
: Returns "1" as the first three characters are lower case.
! 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>isempty([comment], 0)</nowiki></b></span>
'''{{monospace|<nowiki>IsLowerCase(tesT)</nowiki>}}'''
<p style="margin-left:20pt;">If the comment field is empty, [[#IsEmpty|IsEmpty()]] returns 1, otherwise 0.</p>
: Returns "0" as here, all characters will be tested, and one of them is <i>not</i> lower case.
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>isempty([track #], 1)</nowiki></b></span>
}}
<p style="margin-left:20pt;">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.</p>

<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>ifelse(!isempty([disc #]), [disc #])</nowiki></b></span>
=== <span id="IsMissing">IsMissing(&hellip;)</span> ===
<p style="margin-left:20pt;">Outputs the <i>value</i> of the disc # field when it is not empty.</p>
: Tests to see if a file exists on the system.
|}

<div style="text-align:right;">([[#top|Back to top)]]</div>
{{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="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?]
}}


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


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="IsRange" valign="top"
| name=IsRange
| arguments=value, range
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>isrange(</b><i>value</i><b>, </b><i>range</i><b>)</b></span>
The [[#IsRange|IsRange()]] function tests if a <i>value</i> falls within a given <i>range</i> of values.
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.
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.
A <i>range</i> is specified in the form of low-high, where low and high are either letters or numbers.
Line 149: Line 257:
<div style="margin-left: 20pt">23-7542 </div>
<div style="margin-left: 20pt">23-7542 </div>
</div>
</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>isrange([artist], a-c)</nowiki></b></span>
<p style="margin-left:20pt;">Artist values of Abba or Blondie will result in a 1, but ZZ Top will return a 0.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>if(isrange([bitrate], 96-191), Poor Quality, High Quality)</nowiki></b></span>
<p style="margin-left:20pt;">Returns <span style="font-family: monospace,monospace; font-size:1em;">Poor Quality</span> for any file whose bit rate falls in the <i>range</i> of 96 to 191, and returns <span style="font-family: monospace,monospace; font-size:1em;">High Quality</span> for all other bit rates.</p>


''See also:'' [[DateInRange()|DateInRange(…)]]
Additional Examples


| 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.]
:[http://wiki.jriver.com/index.php/CD_Reference_Number#Answer_2 Using IsRange() in a Search List.]
|}
}}
<div style="text-align:right;">([[#top|Back to top)]]</div>

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

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="IsMissing" 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>ismissing(</b><i>filepath</i><b>)</b></span>
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.

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>ismissing()</nowiki></b></span>
<p style="margin-left:20pt;">If the referenced file was not found in the file system, 1 is returned; otherwise 0 is returned.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>ismissing(C:\Music\My Lost File.mp3)</nowiki></b></span>
<p style="margin-left:20pt;">Checks for <span style="font-family: monospace,monospace; font-size:1em;">My Lost File.mp3</span> and returns 1 (positive) if the file does not exist, and 0 (negative) if the file does exist.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>if(ismissing(), File is missing, File exists)</nowiki></b></span>
<p style="margin-left:20pt;">Outputs <span style="font-family: monospace,monospace; font-size:1em;">File is missing</span> or <span style="font-family: monospace,monospace; font-size:1em;">File Exists</span> depending on the result returned by IsMissing().</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>[=ismissing([filename])]=1</nowiki></b></span>
<p style="margin-left:20pt;">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 <span style="font-family: monospace,monospace; font-size:1em;">Set rules for file display</span> search to give you a view that you can visit periodically to check that your library is not missing any files.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>


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


{{function description box
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="IsRemovable" valign="top"
| name=IsRemovable
| arguments=filepath
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| description=
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>isremovable(</b><i>filepath</i><b>)</b></span>
{{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.
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="IsUpperCase">IsUpperCase(&hellip;)</span> ===
Argument <i>filepath</i> is optional (defaults to [filename]).
: Tests to see if a value is upper case.


{{function description box
|- valign="top"
| name=IsUpperCase
! 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
| arguments=value, characters
|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>isremovable()</nowiki></b></span>
| description=
<p style="margin-left:20pt;">Checks if the current file is on removable storage, and if so, returns 1, otherwise returns 0.</p>
{{argument optional|Characters|<i>all</i>}}
|}
The [[#IsUpperCase|IsUpperCase()]] function tests the given <i>value</i> to determine whether or not it is upper case, returning "1" for a positive result, and "0" for a negative result.
<div style="text-align:right;">([[#top|Back to top)]]</div>


| examples=
=== <span id="IsInPlayingNow">IsInPlayingNow(&hellip;)</span> ===
'''{{monospace|<nowiki>IsUpperCase(TESt,1)</nowiki>}}'''
: Tests to see if a file is in the Playing Now playlist.
: Returns "1" as only one character is specified for the check, and the first character, is upper case.


'''{{monospace|<nowiki>IsUpperCase(TESt,3)</nowiki>}}'''
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
: Returns "1" as the first three characters are upper case.
|- id="IsInPlayingNow" 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>isinplayingnow(</b><i>filepath</i><b>)</b></span>
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.


'''{{monospace|<nowiki>IsUpperCase(TESt)</nowiki>}}'''
Argument <i>filepath</i> is optional (defaults to [filename]).
: Returns "0" as here, all characters will be tested, and one of them is <i>not</i> upper case.
}}


=== <span id="SearchTags">SearchTags(&hellip;)</span> ===
|- valign="top"
: Finds all fields that contain a value
! 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>isinplayingnow()</nowiki></b></span>
<p style="margin-left:20pt;">If the file in the Playing Now list, returns 1, otherwise returns 0.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>if(isinplayingnow(), Queued, Not queued)</nowiki></b></span>
<p style="margin-left:20pt;">If the file in the Playing Now list, returns <span style="font-family: monospace,monospace; font-size:1em;">Queued</span>, otherwise <span style="font-family: monospace,monospace; font-size:1em;">Not queued</span>.</p>


{{function description box
Additional Examples
| name=SearchTags
| arguments=value, mode
| description=
{{argument optional}}


{{argument table
:[http://yabb.jriver.com/interact/index.php?topic=57461.0 How to use IsPlaying() and IsInPlayingNow()]
| contents=
|}
{{argument table row|0|Returns a semi-colon delimited list of fields}}
<div style="text-align:right;">([[#top|Back to top)]]</div>
{{argument table row|1|Returns 1 for a positive result and 0 for a negative result}}
}}


The [[#SearchTags|SearchTags()]] function tests for a value in any field and returns the list of fields it is in, or a binary for further processing. Note that this function tests the raw value in the field, and not the formatted value, so matches against numerical values such as date fields may give unexpected results.
=== <span id="IsPlaying">IsPlaying(&hellip;)</span> ===
: Tests to see if a file is in currently being played.


Also, this function searches every field for all files in the current View or Playlist, so it will not be fast in some uses.
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
| examples=
|- id="IsPlaying" valign="top"
'''{{monospace|<nowiki>SearchTags(Beatles, 0)</nowiki>}}'''
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
: If the file includes any tag that contains "Beatles", then the function returns the list of fields, such as "Artist; Filename".
| 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>isplaying(</b><i>filepath</i><b>)</b></span>
'''{{monospace|<nowiki>SearchTags(Beatles, 1)</nowiki>}}'''
The [[#IsPlaying|IsPlaying()]] function tests if a file is playing in any zone.
: If the file includes any tag that contains "Beatles", then the function returns 1, otherwise 0.
Used as an expression category, pane or file list column allows distinguishing files that are playing now.


'''{{monospace|<nowiki>[=SearchTags(Beatles, 1)]=1</nowiki>}}'''
Argument <i>filepath</i> is optional (defaults to [filename]).
: Used in a search, finds all files that contains "Beatles" in any field.

}}
|- 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(isplaying(), &lt;font color="ff0000"&gt;&#9834;&lt;//font&gt;, isinplayingnow(), &#9834;)</nowiki></b></span>
<p style="margin-left:20pt;">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.</p>

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?]
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

Latest revision as of 15:50, 5 June 2021

See also: Expression Language and Function Index

The majority of 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.

Compare(…)

Compares two numbers.
Description Compare(value1, operator, value2)

The Compare() function compares two numeric values value1 and value2 using the specified operator.

Available operator values:

=Equivalence
<Less than
<=Less than or equal to
>Greater than
>=Greater than or equal to

Outputs 1 if the comparison is true, and 0 otherwise.

Examples compare([bitrate], <, 320)
Returns 1 when the bit rate is less than 320 (Kbps), and 0 otherwise.

if(compare(math(now() - [date modified, 0]), >, 21), Expired, formatdate([date modified, 0], elapsed))

Outputs the age of files under 21 days old, or Expired for older files.
(Back to top)   (Function index)

IsDigit(…)

Determines whether or not a given value is digits.
Description IsDigit(value, characters)
  • Argument Characters is optional (defaults to all).

The IsDigit() function tests the given value to determine whether or not it is digits, returning "1" for a positive result, and "0" for a negative (not digits) result.

Examples isdigit(1234)
Returns "1" as these are all digits.

isdigit(Check1-2)

Returns "0" as these are not all digits.
(Back to top)   (Function index)

IsDriveMissing(…)

Tests for the prescence of a specified drive.
Description IsDriveMissing(Drive)

The IsDriveMissing() function tests for the prescence of a specified drive, returning "1" for a positive (missing) result, and "0" for a negative (drive exists) result. Note that this function cannot work with drive names at all, only drive letters.

Examples isdrivemissing(C:\)
Returns "0" as drive C: is available.

isdrivemissing(C:)

Returns "0" as drive C: is available. Demonstrating the backslash is not essential for the function to operate correctly.

if(IsDriveMissing(V:),Please Connect Drive [volume name],Files are availble)

Returns "Please Connect Drive V:" for all files residing on drive V: if it is missing, or, Files are availble if the drive is connected.
(Back to top)   (Function index)

IsEmpty(…)

Tests a value for emptiness.
Description IsEmpty(value, mode)
  • Argument mode is optional (defaults to 0).

The IsEmpty() function tests the given value for emptiness. The value 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 value is empty, otherwise 0.

Available mode values:

0String test (field must be empty to get a positive result).
1Numerical test (field must be empty, or contain 0 to get a positive result)

Note that Media Center does not discriminate between a 0 value and an empty value 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 value 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 isempty([comment], 0)
If the comment field is empty, IsEmpty() returns 1, otherwise 0.

isempty([track #], 1)

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.

ifelse(!isempty([disc #]), [disc #])

Outputs the value of the disc # field when it is not empty.
(Back to top)   (Function index)

IsEqual(…)

Compares two values in one of seventeen specified modes.
Description IsEqual(value1, value2, mode)
  • Argument mode is optional (defaults to 0).

The IsEqual() function compares value1 with value2 using any mode from the list of modes below. Outputs 1 when the comparison succeeds according to the mode, and 0 otherwise. Although the mode is specified as the last argument, the comparison should be mentally read as: value1 mode value2.

Available mode values:

0Case-sensitive string compare for equality
1Case-insensitive string compare for equality
2Numeric compare for equality
3Numeric less than
4Numeric less than or equal to
5Numeric greater than
6Numeric greater than or equal to
7Substring search (case sensitive)
8Substring search (case insensitive)
9List search ANY (case sensitive)
10List search ANY (case insensitive)
11List search ALL (case sensitive)
12List search ALL (case insensitive)
13List search ANY (case sensitive) (Full String Match)
14List search ANY (case insensitive) (Full String Match)
15List search ALL (case sensitive) (Full String Match)
16List search ALL (case insensitive) (Full String Match)
Examples isequal([artist], [album], 1)
If the artist and album values are the same, the output will be 1, otherwise, the output will be 0.

if(isequal([artist], [album], 1), Eponymous, [album])

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.

if(isequal([artist], [album], 1), Eponymous/,, [album]/))

This example demonstrates the character escaping mentioned in the overview earlier. Here, we want the output to be either 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.

if(isequal([filename (path)], classical, 8), Classical, Not Classical)

Because compare mode 8 has been specified, if the word classical appears anywhere in the case-insensitive file path, the expression will return Classical, and if not it will return Not Classical.

if(isequal([Genre], Pop;Rock, 9), Pop or some sort of Rock, Not Pop or Rock)

Because compare mode 9 has been specified, if either of the case sensitive sub-strings Rock or Pop appear anywhere in the Genre List Type field, the expression will return Pop or some sort of Rock, and if not it will return Not Pop or Rock.
Genres that match include "Pop" "Rock" "Pop;Rock" "Pop Rock" "Rock;Pop" "Popular;Rock" "Popular;Rock & Roll" "Rock & Roll" "Funk Rock" and "Alt. Rock", among others.

if(isequal([Genre], Pop;Rock, 11), Some sort of Pop Rock, Not Pop Rock)

Because compare mode 11 has been specified, if the case sensitive sub-strings Pop and Rock both appear anywhere in the Genre List Type field, the expression will return Some sort of Pop Rock, and if not it will return Not Pop Rock.
Genres that match include "Pop;Rock" "Pop Rock" "Rock;Pop" "Popular;Rock" and "Popular;Rock & Roll", among others.
Genres that do not match include "Pop" "Rock" "Rock & Roll" "Funk Rock" and "Alt. Rock", among others.

if(isequal([Genre], Pop;Rock, 13), Pop or some sort of Rock, Not Pop or Rock)

Because compare mode 13 has been specified, if either of the case sensitive full strings Rock or Pop appear in the Genre List Type field, the expression will return Pop or some sort of Rock, and if not it will return Not Pop or Rock.
Genres that match include "Pop;Rock" "Pop;Rock & Roll" "Popular;Rock", among others.
Genres that do not match include "Pop Rock" "Rock & Roll" "Rock, Popular" "Popular;Rock & Roll" "Funk Rock" and "Alt. Rock", among others.

if(isequal([Genre], Pop;Rock, 15), Some sort of Pop Rock, Not Pop Rock)

Because compare mode 15 has been specified, if the case sensitive full strings Pop and Rock both appear in the Genre List Type field, the expression will return Some sort of Pop Rock, and if not it will return Not Pop Rock.
Genres that match include "Pop;Rock" "Pop;Electronic;Rock" "Rock;Pop,Alt.Rock" "Rock;Pop" and "Rock;Punk;Pop", among others.
Genres that do not match include "Pop" "Rock" "Popular;Rock" and "Pop;Rockabilly", among others.
(Back to top)   (Function index)

IsInPlayingNow(…)

Tests to see if a file is in the Playing Now playlist.
Description IsInPlayingNow(filepath)
  • Argument filepath is optional (defaults to [filename]).

The 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 IsInPlayingNow()
If the file in the Playing Now list, returns 1, otherwise returns 0.

if(isinplayingnow(), Queued, Not queued)

If the file in the Playing Now list, returns Queued, otherwise Not queued.
(Back to top)   (Function index)

IsLowerCase(…)

Tests to see if a value is lower case.
Description IsLowerCase(value, characters)
  • Argument Characters is optional (defaults to all).

The IsLowerCase() function tests the given value to determine whether or not it is lower case, returning "1" for a positive result, and "0" for a negative result.

Examples IsLowerCase(tesT,1)
Returns "1" as only one character is specified for the check, and the first character, is lower case.

IsLowerCase(tesT,3)

Returns "1" as the first three characters are lower case.

IsLowerCase(tesT)

Returns "0" as here, all characters will be tested, and one of them is not lower case.
(Back to top)   (Function index)

IsMissing(…)

Tests to see if a file exists on the system.
Description IsMissing(filepath)
  • Argument filepath is optional (defaults to [filename]).

The 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() 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() 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() with care.

Examples ismissing()
If the referenced file was not found in the file system, 1 is returned; otherwise 0 is returned.

ismissing(C:\Music\My Lost File.mp3)

Checks for My Lost File.mp3 and returns 1 (positive) if the file does not exist, and 0 (negative) if the file does exist.

if(ismissing(), File is missing, File exists)

Outputs File is missing or File Exists depending on the result returned by IsMissing().

[=ismissing([filename])]=1

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 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.
(Back to top)   (Function index)

IsPlaying(…)

Tests to see if a file is in currently being played.
Description IsPlaying(filepath)
  • Argument filepath is optional (defaults to [filename]).

The 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 ifelse(isplaying(), <font color="ff0000">♪<//font>, isinplayingnow(), ♪)
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

How to use IsPlaying() and IsInPlayingNow()
How to play an artist's full work when a genre is shuffling?
(Back to top)   (Function index)

IsRange(…)

Tests a value for inclusion within a given range.
Description IsRange(value, range)

The IsRange() function tests if a value falls within a given range of values. If the value falls within the given range, 1 is returned, otherwise 0 is returned.

A range is specified in the form of low-high, where low and high are either letters or numbers. The lowest value 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:

1-100
a-z
c-d
23-7542

See also: DateInRange(…)

Examples isrange([artist], a-c)
Artist values of Abba or Blondie will result in a 1, but ZZ Top will return a 0.

if(isrange([bitrate], 96-191), Poor Quality, High Quality)

Returns Poor Quality for any file whose bit rate falls in the range of 96 to 191, and returns High Quality for all other bit rates.

Additional Examples

Using IsRange() in a Search List.
(Back to top)   (Function index)

IsRemovable(…)

Tests to see if a file is stored on removable media.
Description IsRemovable(filepath)
  • Argument filepath is optional (defaults to [filename]).

The 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 IsRemovable()
Checks if the current file is on removable storage, and if so, returns 1, otherwise returns 0.
(Back to top)   (Function index)

IsUpperCase(…)

Tests to see if a value is upper case.
Description IsUpperCase(value, characters)
  • Argument Characters is optional (defaults to all).

The IsUpperCase() function tests the given value to determine whether or not it is upper case, returning "1" for a positive result, and "0" for a negative result.

Examples IsUpperCase(TESt,1)
Returns "1" as only one character is specified for the check, and the first character, is upper case.

IsUpperCase(TESt,3)

Returns "1" as the first three characters are upper case.

IsUpperCase(TESt)

Returns "0" as here, all characters will be tested, and one of them is not upper case.
(Back to top)   (Function index)

SearchTags(…)

Finds all fields that contain a value
Description SearchTags(value, mode)
  • Argument mode is optional (defaults to 0).

Available mode values:

0Returns a semi-colon delimited list of fields
1Returns 1 for a positive result and 0 for a negative result

The SearchTags() function tests for a value in any field and returns the list of fields it is in, or a binary for further processing. Note that this function tests the raw value in the field, and not the formatted value, so matches against numerical values such as date fields may give unexpected results.

Also, this function searches every field for all files in the current View or Playlist, so it will not be fast in some uses.

Examples SearchTags(Beatles, 0)
If the file includes any tag that contains "Beatles", then the function returns the list of fields, such as "Artist; Filename".

SearchTags(Beatles, 1)

If the file includes any tag that contains "Beatles", then the function returns 1, otherwise 0.

[=SearchTags(Beatles, 1)]=1

Used in a search, finds all files that contains "Beatles" in any field.
(Back to top)   (Function index)
Retrieved from "https://wiki.jriver.com/index.php?title=Test_and_Comparison_Functions&oldid=16608"