View source for Number Functions

The functions detailed on this page deal primarily with numbers and number manipulation.

=== <span id="Avg">Avg(&hellip;)</span> ===
: Returns the average from a given set of numbers.

{{function description box
| name=Avg
| arguments=value1, value2, value3, --> valueN
| description=
:* There is no limit to the number of values that can be presented.
:* The given numbers can be negative as well as positive, and can also be decimals.
:* Each number must be separated from the others by a comma.
:* Non-numeric characters are evaluated as zero.

| examples=
'''{{monospace|Avg(1,2,3,4,5,6,7,8,9)}}'''
: Returns 5 ''(45/9)''

'''{{monospace|Avg(1,2,3,4,5,6,7,8,9,x)}}'''
: Returns 4.5 ''(45/10), x evaluates as zero.''
}}

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

{{function description box
| name=Counter
| arguments=Start Value, Increment, Reset Value
| description=
{{argument optional|Start Value|1}}
{{argument optional|Increment|1}}
{{argument optional|Reset Value|Infinity}}
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.
| examples=
'''{{monospace|counter()}}'''
: Outputs values starting at 1, and incrementing by one, it will return 1, 2, 3, ... until no longer called. This might be used, for example, to assign to the [Track #] field of several tracks using the field assignment expression =counter()
'''{{monospace|padnumber(counter(370, 2), 4)}}'''
: Outputs numbers beginning from 370, incremented by two, and padded to four digits.  For example, 0370, 0372, 0374, etc.
'''{{monospace|counter(1,1,10)}}'''
: Outputs numbers beginning from 1, incrementing to 9, then resetting to one and starting over. Note that the ''Reset Value'' specified is never output, if a repeating 1 to 10 were required, the reset value would need to be 11.
}}

=== <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,y) || Returns a random value ranging between x and y.
|-
| 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="Max">Max(&hellip;)</span> ===
: Returns the smallest number from a given set of numbers.

{{function description box
| name=Max
| arguments=value1, value2, value3, --> valueN
| description=
:* There is no limit to the number of values that can be presented.
:* The given numbers can be negative as well as positive, and can also be decimals.
:* Each number must be separated from the others by a comma.
:* Non-numeric characters are evaluated as zero.

| examples=
'''{{monospace|Max(1,2,3,4,5,x,y)}}'''
: This will return 5. Both x and y will be evaluated as zero.

'''{{monospace|Max(1,2,3,4,-5)}}'''
: This will return 4
}}

=== <span id="Min">Min(&hellip;)</span> ===
: Returns the smallest number from a given set of numbers.

{{function description box
| name=Min
| arguments=value1, value2, value3, --> valueN
| description=
:* There is no limit to the number of values that can be presented.
:* The given numbers can be negative as well as positive, and can also be decimals.
:* Each number must be separated from the others by a comma.
:* Non-numeric characters are evaluated as zero.

| examples=
'''{{monospace|Min(1,2,3,4,5,x,y)}}'''
: This will return zero, as both x and y will be evaluated so, making that the smallest value

'''{{monospace|Min(1,2,3,4,5)}}'''
: This will return 1
}}

=== <span id="Number">Number(&hellip;)</span> ===
: Returns the first number , including decimals, from a given string

{{function description box
| name=Number
| arguments=String
| description=
Returns the first number , including decimals, from a given string. If there are other numbers along the string, these will not be returned as the function stops once it encounters and returns the first number. <i>String</i> can be given literally, as a library field, or combined with other expression functions.

| examples=
'''{{monospace|Number(The number12 will be returned, but 13 will not)}}'''
: This expression will return 12 and stop. It will not see the number 13.
}}

=== <span id="Rand">Rand(&hellip;)</span> ===
: Returns a random number anywhere between two given numbers

{{function description box
| name=Rand
| arguments=x, y, mode
| description=
{{argument optional|Mode|0|}}
: '''x''' = start number (can be a negative value)
: '''y''' = end number (can be a negative value)
{{argument table
| contents=
{{argument table row|0|Returns a random value between x and y to 15 decimal places ''(Default mode)''}}
{{argument table row|1|Returns a random value between x and y, whole numbers only.}}
}}
Rand() returns a random value between x and y. x and y must be numbers and can have negative values.

Rand() 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. 

| examples=
'''{{monospace|Rand(0,1)}}'''
: This will return a random value between 0 and 1, to fifteen decimal places. ''Mode'' has not been specified, and so defaults to zero.

'''{{monospace|Rand(-10,10,1)}}'''
:  ''Mode'' 1 has been specified, so this will return a random, whole number value between -10 and 10.
}}

=== <span id="Range">Range(&hellip;)</span> ===
: Creates a semi-colon delimited list of numbers in a field.

{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
|- id="Range" 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>Range(</b><i>Start</i><b>, </b><i>Step</i><b>, </b><i>Count</i><b>)</b></span>
The [[#Range|Range()]] function returns a list of semi-colon separated numbers into one field, starting at the <i>Start</i> number, incrementing by the <i>Step</i> number, producing <i>Count</i> numbers.

Arguments <i>Start</i> and <i>Step</i> are optional (default to 0 Zero), and can be negative. 

Argument <i>Count</i> is required and must be positive.

|- 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>Range(1, 1, 10)</nowiki></b></span>
<p style="margin-left:20pt;">Returns <span style="font-family: monospace,monospace; font-size:1em;">1;2;3;4;5;6;7;8;9;10</span>.</p>
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>Range(5, -1, 6)</nowiki></b></span>
<p style="margin-left:20pt;">Returns <span style="font-family: monospace,monospace; font-size:1em;">5;4;3;2;1;0</span>.</p>
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="Roman">Roman(&hellip;)</span> ===
: Converts any given number to, or from, roman numerals.

{{function description box
| name=Roman
| arguments=Value
| description=
Converts {{monospace|"Value"}} to or from roman numerals.
| examples=
'''{{monospace|<nowiki>Roman(4)</nowiki>}}'''
: Returns IV

'''{{monospace|<nowiki>Roman(IV)</nowiki>}}'''
: Returns 4
}}

=== <span id="StackCount">StackCount(&hellip;)</span> ===
: Returns the number of files in a stack

{{function description box
| name=StackCount
| arguments=
| description=
StackCount() does not require any arguments and is used to return the number files in a stack. This is useful, for example, if you are creating custom tooltips and want that information in there or for inclusion in a view you could create to view and manage your stacks, something you might use heavily if you stack a lot of photos or regularly sync files to a handheld device using the ''convert format'' options available there. Note that some files can appear in multiple databases.

| examples=
'''{{monospace|<nowiki>StackCount()</nowiki>}}'''
: Create a panes view where the "Set rules for file display" contains only ''-[Stack Top]=-1 ~d=mk'' and nothing else. Add categories to this view as suits, but, make the first one an expression category using the given example, and the second one, a simple expression ''=[stack top], which makes it possible to filter the file list by individual stacks selection.
'''<u>Important Note</u>'''<br>
This should be considered an advanced user approach, where it is <u>''very''</u> important that you understand the differences in how Media Center behaves when stacks are either collapsed or expanded. [https://yabb.jriver.com/interact/index.php/topic,105662.0.html This forum post] should help in that regard.
}}

=== <span id="Sum">Sum(&hellip;)</span> ===
: Returns the sum of a given set of numbers.

{{function description box
| name=Sum
| arguments=value1, value2, value3, --> valueN
| description=
:* There is no limit to the number of values that can be presented.
:* The given numbers can be negative as well as positive, and can also be decimals.
:* Each number must be separated from the others by a comma.
:* Non-numeric characters are evaluated as zero.

| examples=
'''{{monospace|Sum(1,2,3,4,5,6,7,8,9)}}'''
: Returns 45

'''{{monospace|Sum(1,2,3,4,5,6,7,8,9,x)}}'''
: Returns 45 ''(x evaluates as zero.)''
}}

=== <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>