Conditional Functions: Difference between revisions
RoderickGI (talk | contribs) |
No edit summary |
||
(12 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
{{Function Type Page}} |
|||
The functions in this section test one or more arguments to produce either a true or false outcome, and execute specific actions depending upon that result. |
The functions in this section test one or more arguments to produce either a true or false outcome, and execute specific actions depending upon that result. |
||
The expression language does not directly support AND, OR, and XOR operations. |
|||
However, these can be easily emulated using any of several techniques. See: [[Boolean Operations]]. |
|||
The NOT operator {{monospace|<b>!</b>}} (exclamation point) may be used in a conditional to invert the sense of the conditional test. Inverting the sense of a test can make reading expressions easier, or support better [[#IfElse|IfElse()]] sequences. |
The NOT operator {{monospace|<b>!</b>}} (exclamation point) may be used in a conditional to invert the sense of the conditional test. Inverting the sense of a test can make reading expressions easier, or support better [[#IfElse|IfElse()]] sequences. |
||
=== <span id="And">And(…)</span> === |
|||
: Tests a given set of values and returns 1 if ''all'' of them are true. |
|||
{{function description box |
|||
| name=And |
|||
| arguments=value1, value2, value''N'' … |
|||
| description= |
|||
The [[#And|And()]] function tests <i>value1</i>, <i>value2</i> through to value''N'', and returns ''1'' if all of them are true, otherwise, returns zero. |
|||
Two or more arguments may be used, separated by commas. Each ''Value'' will typically be a [[Expression Language#Conditional Functions|Conditional Function]] or a [[Expression Language#Test and Comparison Functions|Test and Comparison Function]] thus avoiding long nested sequences. |
|||
| examples= |
|||
'''{{monospace|And(IsEqual([artist],Mark W,8),IsEqual([People],Vada))}}''' |
|||
: Returns ''1'' for all files that satisfy both IsEqual expressions, and ''zero'' for all other files. |
|||
'''{{monospace|<nowiki>[=And(IsEqual([artist],Mark W,8),IsEqual([People],Vada))]=1</nowiki>}}''' |
|||
: Here, the first example has been formatted for use in the search bar. It will return all files (''think photos'') that show Vada on her own, taken by Mark W |
|||
'''{{monospace|If(And(IsEqual([artist],Mark W,8),IsEqual([People],Vada),IsEqual([Places],France)),Photos of Vada in France Taken by Mark W,Other Photos)}}''' |
|||
: If, and only if, artist contains "Mark W", people is only Vada, and places is only France, the result will be {{monospace|Photos of Vada in France Taken by Mark W}}. For all other photos, the result will be {{monospace|Other Photos}} |
|||
}} |
|||
=== <span id="FirstNotEmpty">FirstNotEmpty(…)</span> === |
|||
: Returns the first non-empty argument. |
|||
{{function description box |
|||
| name=FirstNotEmpty |
|||
| arguments=value1, value2, … |
|||
| description= |
|||
The [[#FirstNotEmpty|FirstNotEmpty()]] function acts as a conditional by returning the first argument from <i>value1</i>, <i>value2</i>, ... that is not empty. |
|||
Two or more arguments may be used, and the first non-empty argument is returned. With two arguments, is is functionally equivalent to the sequence such as {{monospace|if(!isempty(<i>value1</i>), <i>value1</i>, <i>value2</i>)}}. With more than two arguments, [[#FirstNotEmpty|FirstNotEmpty()]] avoids long nested [[#If|If()]] sequences that simply test for emptiness. |
|||
| examples= |
|||
'''{{monospace|firstnotempty([media sub type], Music Video)}}''' |
|||
: Returns the value in {{monospace|media sub type}} if it is not empty, otherwise returns {{monospace|Music Video}}. |
|||
'''{{monospace|firstnotempty([series], [name], Tag your Videos!)}}''' |
|||
: Returns the first non-empty value from the fields {{monospace|series}} or {{monospace|name}}, and if both are empty, returns the reminder to {{monospace|Tag your Videos!}}. |
|||
}} |
|||
=== <span id="If">If(…)</span> === |
=== <span id="If">If(…)</span> === |
||
Line 23: | Line 54: | ||
'''{{monospace|if(!isempty([comment]), regex([comment], /#^(\\S+\\s+\\S+\\s+\\S+)#/, 1), *No Comment)}}''' |
'''{{monospace|if(!isempty([comment]), regex([comment], /#^(\\S+\\s+\\S+\\s+\\S+)#/, 1), *No Comment)}}''' |
||
: Outputs the first three words of the comment field; otherwise, outputs *No Comment. By using the NOT operator, the sense of the conditional is inverted so that the more interesting case is moved ahead of the more mundane case. |
: Outputs the first three words of the comment field; otherwise, outputs *No Comment. By using the NOT operator, the sense of the conditional is inverted so that the more interesting case is moved ahead of the more mundane case. |
||
}} |
|||
=== <span id="IfCase">IfCase(…)</span> === |
|||
: Functions as a switch or select case statement. |
|||
{{function description box |
|||
| name=IfCase |
|||
| arguments=primary, mode, secondary1, action1, secondary2, action2, secondary3, action3..... etc … |
|||
| description= |
|||
{{argument optional}} |
|||
The [[#IfCase|IfCase()]] function performs an [[Test and Comparison Functions#IsEqual|IsEqual()]] operation against one primary operand and several secondary operands, with an action for each secondary operand. [[#IfCase|IfCase()]] honors the same modes as IsEqual. [[#IfCase|IfCase()]] acts on the first match, and if no match occurs returns null. This saves a lot of typing of nested Compare() or IsEqual() statements when matching things against a possible list of values, and makes for much more readable expressions. ''When constructing the tests, always test from longest/largest to shortest/smallest.'' |
|||
{{argument table |
|||
| contents= |
|||
{{argument table row|0|Case-sensitive string compare for equality}} |
|||
{{argument table row|1|Case-insensitive string compare for equality}} |
|||
{{argument table row|2|Numeric compare for equality}} |
|||
{{argument table row|3|Numeric less than}} |
|||
{{argument table row|4|Numeric less than or equal to}} |
|||
{{argument table row|5|Numeric greater than}} |
|||
{{argument table row|6|Numeric greater than or equal to}} |
|||
{{argument table row|7|Substring search (case sensitive)}} |
|||
{{argument table row|8|Substring search (case insensitive)}} |
|||
{{argument table row|9|List search ANY (case sensitive)}} |
|||
{{argument table row|10|List search ANY (case insensitive)}} |
|||
{{argument table row|11|List search ALL (case sensitive)}} |
|||
{{argument table row|12|List search ALL (case insensitive)}} |
|||
{{argument table row|13|List search ANY (case sensitive) (Full String Match)}} |
|||
{{argument table row|14|List search ANY (case insensitive) (Full String Match)}} |
|||
{{argument table row|15|List search ALL (case sensitive) (Full String Match)}} |
|||
{{argument table row|16|List search ALL (case insensitive) (Full String Match)}} |
|||
}} |
|||
| examples= |
|||
'''{{monospace|IfCase([bitrate], 2, 320, High, 256, Medium, 128, Standard, 64, Low)}}''' |
|||
: Converts a numerical {{monospace|bitrate}} to a descriptive word. |
|||
'''{{monospace|IfCase(Length([Name]), 5, 50, Wow this is super long, 30, This is a very long track name, 20, This is not so long)}}''' |
|||
: Takes various actions based on the length of a field, {{monospace|Name}} in this example. |
|||
'''{{monospace|IfCase([Oscar Awarded to], 8, Matt, Matt wins on his first acting job, meryl, The Oscar went to Meryl again, carrey, Unbelievable result)}}''' |
|||
: Multiple actions based on the contents of one string, {{monospace|Oscar Awarded To}} in this example. |
|||
}} |
}} |
||
Line 60: | Line 131: | ||
}} |
}} |
||
=== <span id=" |
=== <span id="Not">Not(…)</span> === |
||
: Negates the results of other (bool) functions. |
|||
: Returns the first non-empty argument. |
|||
{{function description box |
{{function description box |
||
| name= |
| name=Not |
||
| arguments= |
| arguments= |
||
| description= |
| description= |
||
The [[# |
The [[#Not|Not()]] function is useful to negate, for example, Regex mode 0 which returns 0 or 1, and other bool functions. |
||
Two or more arguments may be used, and the first non-empty argument is returned. With two arguments, is is functionally equivalent to the sequence such as {{monospace|if(!isempty(<i>value1</i>), <i>value1</i>, <i>value2</i>)}}. With more than two arguments, [[#FirstNotEmpty|FirstNotEmpty()]] avoids long nested [[#If|If()]] sequences that simply test for emptiness. |
|||
| examples= |
| examples= |
||
'''{{monospace| |
'''{{monospace|Not(IsEmpty())}}''' |
||
: Alone, the simple expression function, "IsEmpty()" will return "1", a positive result, confirming that "()" is indeed, empty. By wrapping this inside a "Not()" function, the result is negated, and a zero is returned. |
|||
: Returns the value in {{monospace|media sub type}} if it is not empty, otherwise returns {{monospace|Music Video}}. |
|||
'''{{monospace|firstnotempty([series], [name], Tag your Videos!)}}''' |
|||
Use <u>[https://yabb.jriver.com/interact/index.php/topic,128028.0.html this Interact thread]</u> for further help and understanding of the use of the Not() funtion. |
|||
: Returns the first non-empty value from the fields {{monospace|series}} or {{monospace|name}}, and if both are empty, returns the reminder to {{monospace|Tag your Videos!}}. |
|||
}} |
}} |
||
=== <span id=" |
=== <span id="Or">Or(…)</span> === |
||
: Tests a given set of values and returns 1 if ''any'' of them are true. |
|||
: Functions as a switch or select case statement. |
|||
{{function description box |
{{function description box |
||
| name= |
| name=Or |
||
| arguments= |
| arguments=value1, value2, value''N'' … |
||
| description= |
| description= |
||
The [[#Or|Or()]] function tests <i>value1</i>, <i>value2</i> through to value''N'', and returns ''1'' if any of them are true, otherwise, returns zero. |
|||
The [[#IfCase|IfCase()]] function performs an rgi operation against one primary operand and several secondary operands, with an action for each secondary operand. [[#IfCase|IfCase()]] honors the same modes as IsEqual. [[#IfCase|IfCase()]] acts on the first match, and if no match occurs returns null. This saves a lot of typing of nested Compare() or IsEqual() statements when matching things against a possible list of values, and makes for much more readable expressions. ''When constructing the tests, always test from longest/largest to shortest/smallest.'' |
|||
Two or more arguments may be used, separated by commas. Each ''Value'' will typically be a [[Expression Language#Conditional Functions|Conditional Function]] or a [[Expression Language#Test and Comparison Functions|Test and Comparison Function]] thus avoiding long nested sequences. |
|||
| examples= |
| examples= |
||
'''{{monospace| |
'''{{monospace|Or(IsEqual([artist],Mark W,8),IsEqual([People],Vada))}}''' |
||
: Returns ''1'' for all files that satisfy either of the given IsEqual expressions, and ''zero'' for all other files. |
|||
: Converts a numerical {{monospace|bitrate}} to a descriptive word. |
|||
'''{{monospace|IfCase(Length([Name]), 5, 50, Wow this is super long, 30, This is a very long track name, 20, This is not so long)}}''' |
|||
'''{{monospace|<nowiki>[=Or(IsEqual([artist],Mark W,8),IsEqual([People],Vada))]=1</nowiki>}}''' |
|||
: Takes various actions based on the length of a field, {{monospace|Name}} in this example. |
|||
: Here, the first example has been formatted for use in the search bar. It will return all files (''think photos'') that show Vada on her own, as well as all photos taken by Mark W |
|||
'''{{monospace|IfCase([Oscar Awarded to], 8, Matt, Matt wins on his first acting job, meryl, The Oscar went to Meryl again, carrey, Unbelievable result)}}''' |
|||
: Multiple actions based on the contents of one string, {{monospace|Oscar Awarded To}} in this example. |
|||
'''{{monospace|If(Or(IsEqual([artist],Mark W,8),IsEqual([People],Vada),IsEqual([Places],France)),Mish-Mash,Other Photos)}}''' |
|||
: Here, all photos taken by Mark W, all photos of Just Vada, and all photos taken in France will return {{monospace|Mish-Mash}}. For any other photos, the result will be {{monospace|Other Photos}} |
|||
}} |
}} |
Latest revision as of 10:29, 12 May 2024
The functions in this section test one or more arguments to produce either a true or false outcome, and execute specific actions depending upon that result.
The NOT operator ! (exclamation point) may be used in a conditional to invert the sense of the conditional test. Inverting the sense of a test can make reading expressions easier, or support better IfElse() sequences.
And(…)
- Tests a given set of values and returns 1 if all of them are true.
Description | And(value1, value2, valueN …)
The And() function tests value1, value2 through to valueN, and returns 1 if all of them are true, otherwise, returns zero. Two or more arguments may be used, separated by commas. Each Value will typically be a Conditional Function or a Test and Comparison Function thus avoiding long nested sequences. |
---|---|
Examples | And(IsEqual([artist],Mark W,8),IsEqual([People],Vada))
[=And(IsEqual([artist],Mark W,8),IsEqual([People],Vada))]=1
If(And(IsEqual([artist],Mark W,8),IsEqual([People],Vada),IsEqual([Places],France)),Photos of Vada in France Taken by Mark W,Other Photos)
|
FirstNotEmpty(…)
- Returns the first non-empty argument.
Description | FirstNotEmpty(value1, value2, …)
The FirstNotEmpty() function acts as a conditional by returning the first argument from value1, value2, ... that is not empty. Two or more arguments may be used, and the first non-empty argument is returned. With two arguments, is is functionally equivalent to the sequence such as if(!isempty(value1), value1, value2). With more than two arguments, FirstNotEmpty() avoids long nested If() sequences that simply test for emptiness. |
---|---|
Examples | firstnotempty([media sub type], Music Video)
firstnotempty([series], [name], Tag your Videos!)
|
If(…)
- Conditional if-else evaluator.
Description | If(test expression, true expression, false expression)
The If() function is used to evaluate a test expression, and will output the result of the true expression or false expression, depending upon the evaluation result. The test expression is expected to return a 0 (false value) or a non-zero (true value). Nesting is allowed. If the test expression is preceded by the NOT operator (!, an exclamation point), the sense of the test is inverted. Non-zero values are inverted to 0, and 0 is inverted to 1. |
---|---|
Examples | if(isequal([artist], bob dylan, 1), Genius, Mediocre)
if(isequal([artist], bob dylan, 1), Genius, if(isequal([album], Joshua Tree, 8), Great Album, Mediocre))
if(!isempty([comment]), regex([comment], /#^(\\S+\\s+\\S+\\s+\\S+)#/, 1), *No Comment)
|
IfCase(…)
- Functions as a switch or select case statement.
Description | IfCase(primary, mode, secondary1, action1, secondary2, action2, secondary3, action3..... etc …)
The IfCase() function performs an IsEqual() operation against one primary operand and several secondary operands, with an action for each secondary operand. IfCase() honors the same modes as IsEqual. IfCase() acts on the first match, and if no match occurs returns null. This saves a lot of typing of nested Compare() or IsEqual() statements when matching things against a possible list of values, and makes for much more readable expressions. When constructing the tests, always test from longest/largest to shortest/smallest. Available mode values:
| ||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Examples | IfCase([bitrate], 2, 320, High, 256, Medium, 128, Standard, 64, Low)
IfCase(Length([Name]), 5, 50, Wow this is super long, 30, This is a very long track name, 20, This is not so long)
IfCase([Oscar Awarded to], 8, Matt, Matt wins on his first acting job, meryl, The Oscar went to Meryl again, carrey, Unbelievable result)
|
IfElse(…)
- Conditional if-elseif evaluator.
Description | IfElse(test1, action1, test2, action2, test3, action3, …)
The IfElse() conditional provides a convenient mechanism for shortening and more clearly expressing nested conditionals into an alternating sequence of tests and actions. One or more test/action pairs may be specified. For example, consider a nested sequence of If() tests such as the following pseudo-code:
The IfElse() statement may be used to more cleanly express the flow of expression by removing the superfluous internal If() statements, converting the clumsy expression:
into the more elegant:
If any of the test expressions test1, etc. are preceded by the NOT operator (!, an exclamation point), the sense of that test is inverted. Non-zero values are inverted to 0, and 0 is inverted to 1. |
---|---|
Examples | ifelse(isequal([media type], Audio), Le Tunes, isequal([media type], Video), Flix)
ifelse(isequal([artist], Bob Dylan), Genius, isequal([album], Joshua Tree, 8), Great Album, 1, Mediocre)
|
Not(…)
- Negates the results of other (bool) functions.
Description | Not()
The Not() function is useful to negate, for example, Regex mode 0 which returns 0 or 1, and other bool functions. |
---|---|
Examples | Not(IsEmpty())
Use this Interact thread for further help and understanding of the use of the Not() funtion. |
Or(…)
- Tests a given set of values and returns 1 if any of them are true.
Description | Or(value1, value2, valueN …)
The Or() function tests value1, value2 through to valueN, and returns 1 if any of them are true, otherwise, returns zero. Two or more arguments may be used, separated by commas. Each Value will typically be a Conditional Function or a Test and Comparison Function thus avoiding long nested sequences. |
---|---|
Examples | Or(IsEqual([artist],Mark W,8),IsEqual([People],Vada))
[=Or(IsEqual([artist],Mark W,8),IsEqual([People],Vada))]=1
If(Or(IsEqual([artist],Mark W,8),IsEqual([People],Vada),IsEqual([Places],France)),Mish-Mash,Other Photos)
|