SingleValueIf()

Format

SingleValueIf(Condition ,ValueIfTrue ,ValueIfFalse)

Returns

Returns the value of the ValueIfTrue expression if the Condition expression evaluates to true. Otherwise, returns the value of the ValueIfFalse expression. 

See also: If()

Inputs

Condition: The expression to be evaluated.
Behaviour: Required
Dimension: Collection, SingleValue
Valid data types: Boolean

Note: Valid comparison operators are: ==, !=, <, <=, >, >=
For a full list of operators, see Operators.

ValueIfTrue: The value returned if the condition evaluates to true.
Behaviour: Required
Dimension: Error, Collection, SingleValue, Matrix, MultiCollection
Valid data types: Null, Boolean, DateTime, Decimal, Integer, String, Duration, Error

ValueIfFalse: The value returned if the condition evaluates to false.
Behaviour: Required 
Dimension: Error, Collection, SingleValue, Matrix, MultiCollection
Valid data types: Null, Boolean, DateTime, Decimal, Integer, String, Duration, Error

How to format data types

Common Traps

If a collection is used for the condition, it must contain only 1 value. If the condition is a collection which contains 0 or more than 1 value, the function will return an error.

When to Use

The SingleValueIf() function takes a single value and returns a value which is either the true or false parameter, whereas If() takes the individual values in the collections and compares them, returning a collection comprised of the individual evaluations. 

Here are some examples which show the difference:

If([1, 1, 2, 2]   >= 2, [5, 5, 5, 5], [2, 2, 2, 2]) =  [2, 2, 5, 5]

SingleValueIf([1] >= 2, [5, 5, 5, 5], [2, 2, 2, 2]) =  [2, 2, 2, 2]

SingleValueIf([2] >= 2, [5, 5, 5, 5], [2, 2, 2, 2]) =  [5, 5, 5, 5]

Note: The ValueIfTrue and ValueIfFalse parameters do not need to be of the same type, so you can use this function to return different data types depending on the outcome.

Examples

Expression: SingleValueIf({tagname}>=2,[5, 5, 5, 5], [2, 2, 2, 2])
Result: If the value of {tagname} is greater than or equal to 2, return [5, 5, 5, 5]. Otherwise, return [2, 2, 2, 2].
Example outcomes:
     Where tagname is [1], the function returns [2, 2, 2, 2].
     Where tagname is [], the function returns an error, because the collection contains 0 values.
     Where tagname is [1,2,3], the function returns an error, because the collection contains more than 1 value.

Expression: SingleValueIf({tagname}>=0,{tagname},"Too Low")
Result: If the value of {tagname} is greater than or equal to zero, return the value of the tag. Otherwise, return the string "Too Low".
 

Release History

• SingleValueIf() 4.6.5
  • Changed ValueIfTrue and ValueIfFalse parameters to support MultiCollection values.
• SingleValueIf() 4.0
  • Initial version