Difference between revisions of "Number Functions"

From JRiverWiki
Jump to: navigation, search
(One intermediate revision by the same user not shown)
Line 2: Line 2:
  
 
The functions detailed on this page deal primarily with numbers and number manipulation.
 
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> ===
 
=== <span id="Counter">Counter(&hellip;)</span> ===
Line 190: Line 210:
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<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> ===
 
=== <span id="Min">Min(&hellip;)</span> ===
Line 304: Line 344:
 
'''<u>Important Note</u>'''<br>
 
'''<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.
 
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.)''
 
}}
 
}}
  

Revision as of 06:27, 21 March 2021

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

Avg(…)

Returns the average from a given set of numbers.
Description Avg(value1, value2, value3, --> valueN)
  • 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 Avg(1,2,3,4,5,6,7,8,9)
Returns 5 (45/9)

Avg(1,2,3,4,5,6,7,8,9,x)

Returns 4.5 (45/10), x evaluates as zero.

Counter(…)

Counts upwards in specified increments.
Description counter(start value, increment)

The Counter() function outputs a monotonically increasing number (more simply stated, it counts) from a start value, and each time called, increases by the increment value. It is useful for sequentially numbering fields. The Counter() function maintains an internal counter, and it resets itself to zero after five seconds of inactivity.

Because 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, =counter(). With proper care, it can be used as part of an expression in the Rename, Move & Copy tool, but see also 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 start value is optional (defaults to 1).

Argument increment is optional (defaults to 1).

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

padnumber(counter(370, 2), 4)

Outputs numbers beginning from 370, incremented by two each, and padded to four digits. For example, 0370, 0372, 0374, etc.

Math(…)

Evaluates a given mathematical formula.
Description math(expression)

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

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

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

(   ) 
  ! 
  ^ 
*   /Left to right
+   -Left to right
|   &Left to right

Variables may be assigned and used by specifying a simple string of letters. Examples: math(val=2) or math(x=pow(2,3)).

Multiple equations may be specified, each separated by a semicolon. Expressions are evaluated left to right. The final value of the Math() function will be the result of the right-most equation. For example, the equation math(x=4; pow(2^x)) will output 16.

Note: Empty fields

Fields used inside of Math() are expanded (interpolated) directly. Fields with empty values may produce incomplete Math() statements. For example, if the field [number plays] is empty, an expression such as math([number plays] + 2) would be seen by Math() as + 2. This incomplete expression would produce a syntax error. See the Additional Examples for more information.

Note: Locales and Commas

Special care must be taken with the Math() function and locales that use , (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() these before passing the values to Math(), which always uses dot . as the numeric decimal point.

For example, the expression math(1,5 + 1,5) will fail since Math() does not consider 1,5 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. [date,0], [last played,0], [date modified,0], and [date imported,0]), 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() and ConvertTime() also return localized floating-point values.

Handling this problem is not difficult. Before passing any floating point number to Math(), use Replace() first. See the examples below.

Examples math(10 + 4)

Returns 14.

math(10 + 2 * 25)

Returns 60, demonstrating that multiplication has higher precedence than addition.

math((10 + 2) * 25)

Returns 300, demonstrating that parenthesis grouping has higher precedence than multiplication.

math(replace(now(), /,, .) - replace([last played,0], /,, .))

The , is replaced by a . in the output of both Now() and in the raw field value [last played,0]. Note that the comma must be escaped so that it is seen as an argument and not as an argument separator.

math(replace(now() - [last layed,0], /,, .))

The same as the previous example, but is more efficient and simpler since it calls Replace() just once on the entire string to be passed to Math().

Additional Examples

An explanation and some solutions for fields that evaluate to empty within Math().

Max(…)

Returns the smallest number from a given set of numbers.
Description Max(value1, value2, value3, --> valueN)
  • 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 Max(1,2,3,4,5,x,y)
This will return 5. Both x and y will be evaluated as zero.

Max(1,2,3,4,-5)

This will return 4

Min(…)

Returns the smallest number from a given set of numbers.
Description Min(value1, value2, value3, --> valueN)
  • 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 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

Min(1,2,3,4,5)

This will return 1

Number(…)

Returns the first number , including decimals, from a given string
Description Number(String)

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. String can be given literally, as a library field, or combined with other expression functions.

Examples Number(The number12 will be returned, but 13 will not)
This expression will return 12 and stop. It will not see the number 13.

Rand(…)

Returns a random number anywhere between two given numbers
Description Rand(x, y, mode)
  • Argument Mode is optional (defaults to 0).
x = start number (can be a negative value)
y = end number (can be a negative value)

Available mode values:

0Returns a random value between x and y to 15 decimal places (Default mode)
1Returns 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 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.

Rand(-10,10,1)

Mode 1 has been specified, so this will return a random, whole number value between -10 and 10.

Range(…)

Creates a semi-colon delimited list of numbers in a field.
Description Range(Start, Step, Count)

The Range() function returns a list of semi-colon separated numbers into one field, starting at the Start number, incrementing by the Step number, producing Count numbers.

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

Argument Count is required and must be positive.

Examples Range(1, 1, 10)

Returns 1;2;3;4;5;6;7;8;9;10.

Range(5, -1, 6)

Returns 5;4;3;2;1;0.

Roman(…)

Converts any given number to, or from, roman numerals.
Description Roman(Value)

Converts "Value" to or from roman numerals.

Examples Roman(4)
Returns IV

Roman(IV)

Returns 4

StackCount(…)

Returns the number of files in a stack
Description StackCount()

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

Important Note
This should be considered an advanced user approach, where it is very important that you understand the differences in how Media Center behaves when stacks are either collapsed or expanded. This forum post should help in that regard.

Sum(…)

Returns the sum of a given set of numbers.
Description Sum(value1, value2, value3, --> valueN)
  • 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 Sum(1,2,3,4,5,6,7,8,9)
Returns 45

Sum(1,2,3,4,5,6,7,8,9,x)

Returns 45 (x evaluates as zero.)

TrackNumber(…)

Returns a file's track # value.
Description tracknumber()

The TrackNumber() function returns a file's track #, or 0 if the no value exists. It is used to populate the Library field track # with its value. Either the field or TrackNumber() can be used.

Examples tracknumber()

Returns the value present in the track # field.