ReplaceValues()

Format

ReplaceValues(Source, Replace, Replacement)

Returns

Replaces the values in the first argument it is passed.

Inputs

Source: The argument in which values will be replaced.
Behaviour: Required
Dimensions: Collection, SingleValue, MultiCollection
Valid data types: Null, Boolean, DateTime, Decimal, Integer, String, Duration

Replace: The value that has to be replaced. This must be the same data type as the Source value.
Behaviour: Required
Dimensions: SingleValue
Valid data types: Null, Boolean, DateTime, Decimal, Integer, String, Duration

Replacement: The replacement value for all matched values in the source expression. For single values, this may be of a different data type to the Source value. For collections, this should be the same data type as the Source value.
Behaviour: Required
Dimensions: SingleValue
Valid data types: Null, Boolean, DateTime, Decimal, Integer, String, Duration

How to format data types

Error Conditions

An error will be thrown if:

• A tag or entity supplied as an argument does not exist.
• The data type of the first two arguments are not the same.
  • Error example: The value cannot be converted from error to boolean.
• The data type of the Replacement is not compatible with the data type of the Source (applies to collections).
  • Error example: The type of the supplied VariableValue ("String") is not compatible with the type of the VariableValueCollection ("Integer").
• The data type of a parameter is not valid.

Examples

Expression: ReplaceValues(2 + 3, 5, 6)
Result: 6

Expression: ReplaceValues({Tag1}, 0, 1)
Result: The value of the Tag1 tag with every 0 value replaced with an integer value of 1.

Expression: ReplaceValues(Boolean(0), False, True)
Result: Replaces the Boolean False value, with a Boolean value of True.

Expression: ReplaceValues(DateTime(12), DateTime(12), 13)
Result: Replaces the DateTime value of 12, with an integer value of 13.

Tip: If you have access to the sample data, try running the following examples using the calculation tester. 

Expression: ReplaceValues({Archer[Oil Producing Well]:Status!Actual}, 0, 3)
Result: The value of the Archer[Oil Producing Well]:Status!Actual attribute, with every 0 value replaced with an integer of 3.

Expression: ReplaceValues({ReturnNull}, Null, 1)
Result: The value of the ReturnNull calculation, with every null value replaced with an integer value of 1. This is different from ReplaceNull(), which replaces null values in a collection with the last known value.

Expression: ReplaceValues({OperatingStatus}, 0, "test")
Result: This will fail because you cannot put a string value into an integer collection.

Expression: ReplaceValues({OperatingStatus}, 0, null)
Result: The value of the OperatingStatus calculation, with every 0 integer value replaced with a null value. This is allowed because nulls and integers can be mixed in a collection. Errors and integers can also be mixed in a collection.

Release History

• ReplaceValues() 4.6.5
  • Changed Source parameter to support MultiCollection values.
• ReplaceValues() 4.5.1
  • Initial version