# Math Expressions

This section explains the syntax, and available functions and scopes for the math expressions. Math expressions are used in various places in the software:

• math parameters
• exports
• CID cell formatting

When writing a math expression there will be an auto complete functionality that can help to find parameter and function names. ## Syntax​

When writing a math expression, parameters from the current definition or other related definitions can be accessed and functions can be called to perform operations. Basic numerical, text and boolean operators are available.

### Accessing a parameter​

Parameters can be accessed by their names. Note that part item parameters are accessed using the name of the part parameter with `PartItem` added to the end of the name.

### Operators​

The following numerical operators are available:

• `+` addition
• `-` subtraction
• `*` multiplication
• `/` division

The following boolean operators are available:

• `<` less than
• `<=` less than or equal
• `<` greater than
• `<=` greater than or equal
• `&&` and
• `||` or
• `==` equal
• `!=` not equal

The following operators are available for date time parameters:

• `+` addition. If the LHS is a date time and the RHS is a numerical parameter then the return value will be a new date time with the number of seconds from the RHS added to the LHS date time
• `-` subtraction. If the LHS and RHS of the equation are both date time parameters then the return value will be a numerical value with the number of seconds difference between the two provided dates. If the LHS is a date time and the RHS is a numerical parameter then the return value will be a new date time with the number of seconds from the RHS subtracted from the LHS date time

#### String concatenation​

If the return types of the LHS and RHS of the `+` operator do not match then operator will return a string containing the concatenation of the two values. For example `1 + "test"` will return `"1test"`.

### Constant values​

Constant values can be defined in an expression:

• numerical: type a number, e.g. `1.23`
• string: type some text surrounded by double-quotes, e.g. `"test"`
• boolean: type either `true` or `false`

### Keywords​

The following keywords are available

• `null`: mainly used in a boolean comparison to check if a parameter is set, e.g. `FrontSpring != null`
• `this`: represents the current scope

### Scopes​

The scope is an important concept to be aware of when writing a math expression. The scope defines what entity the math expression is referencing. If you are writing a math expression in a math parameter in a setup definition, then that setup definition is the current scope. You can access any parameters on that setup directly by typing the parameter name. To change scope and access a parameter from a different entity the dot-notation is used. Again using the setup as an example, to reference a parameter from the related event you would type `Event.` and then a list of parameters defined in the event definition will be available in the auto update You can join as many scope changes together, for example writing `Event.Championship.Name` would let you access the championship name from a setup. The auto complete normally lets you find the correct scope for anything you need, but the data model documentation provides a full overview of the software.

### Unit Management​

Whenever a numerical parameter with a dimension and unit defined is accessed, a unit conversion can be performed to change the returned unit. This is done using square brackets, for example `mCornerFL["kg"]`. A list of all available dimensions and units can be found in the units documentation.

## Function Reference​

This section lists all functions that are available to be used in math expressions.

### Numerical Functions​

#### Abs​

Abs(Double)
Returns the absolute value of any supplied number
Example : Abs(-2.3)=2.3

#### ACos​

ACos(Double)
Returns the Arccosine of a number
Example : ACos(0)=Math.PI/2

#### ASin​

ASin(Double)
Returns the Arcsine of a number
Example : ASin(1)=Math.PI/2

#### ATan​

ATan(Double)
Returns the Arctangent of a number
Example : ATan(1)=Math.PI/4

#### Average​

Average(Double,...)
Returns the average of the entered values
Example : Average(2,3,4,5,6,7,8)=5

#### Cos​

Cos(Double)
Returns the Cosine of a number
Example : Cos(0)=1

#### Count​

Count(ListOfFlatModel, ListOfDouble)
Count the items from a list of values

#### Degrees​

Degrees(Double)
Example : Degrees(3.1415926535897931)=180

#### DoubleToString​

DoubleToString(Double)
Return the String that represents the double value
Example : DoubleToString(2)="2"

#### FirstNotNull​

FirstNotNull(Double,...)
Returns first parameter that is not null from a list of parameters
Example : FirstNotNull(2.5, 2.3)=2.5 FirstNotNull(null, 2.3)=2.3

#### Length​

Length(String)
Returns the length of a supplied text string
Example : Length("test")=4

#### Max​

Max(Double,...)
Returns the maximum of the entered values
Example : Max(2,3,4,2,-3,-12)=4

#### Min​

Min(Double,...)
Returns the minimum of the entered values
Example : Min(-2,3,5,-9)=-9

#### Pi​

Pi()
Returns the constant value of pi

#### Power​

Power(Double,Double)
Calculates a given number, raised to a supplied power
Example : Power(-2,2)=4

#### Round​

Round(Double,Double)
Rounds a supplied number up or down, to a specified number of decimal places
Example : Round(2.4563,2)=2.46

#### Sign​

Sign(Double)
Returns the arithmetic sign (+1, -1 or 0) of a supplied number
Example : Sign(-2)=-1

#### Sin​

Sin(Double)
Returns the Sine of a number
Example : Sin(0)=0

#### Sqrt​

Sqrt(Double)
Calculates the positive square root of a supplied number
Example : Sqrt(4)=2

#### Sum​

Sum(ListOfDouble)
Returns the sum of the items in a list

#### Tan​

Tan(Double)
Returns the Tangent of a number
Example : Tan(0)=0

#### Truncate​

Truncate(Double,Double)
Returns the truncated number based on a number of digit
Example : Truncate(-53.456677,2)=-53.45

### String Manipulation Functions​

#### Concatenate​

Concatenate(Double, String, Boolean,Double, String, Boolean,...)
Join two or more text strings into one string
Example : Concatenate("test1","-","test2")="test1-test2"

#### GetCurrentUserProperty​

GetCurrentUserProperty(String)
Returns the current username. It allows to display UserName or DisplayName according to the parameter used as input ("Username", "DisplayName")

#### Left​

Left(String,Double)
Returns a specified number of characters from the start of a supplied text string
Example : Left("test",3)="tes"

#### Lower​

Lower(String)
Converts all characters in a supplied text string to lowercase
Example : Lower("TesT1")="test1"

#### Mid​

Mid(String,Double,Double)
Returns a specified number of characters from the middle of a supplied text string.
Example : Mid("test1",2,2)="st"

#### Proper​

Proper(String)
Converts all characters in a supplied text string to proper case
Example : Proper("tesT1")="Test1"

#### Replace​

Replace(String,Double,Double,String)
Replaces part of a text string, based on the number of characters you specify, with a different text string
Example : Replace("01234567",2,5,"Hello")="01Hello7"

Right(String,Double)
Returns a specified number of characters from the end of a supplied text string
Example : Right("test",3)="est"

#### StringToDateTime​

StringToDateTime(String,String,String)
Returns a datetime from the input string. The function expects three inputs, the first is the datetime value, the second one is the time zone and the third is the pattern used. Empty time zone is considered UTC.
Example : StringToDateTime("2020-01-24 13:41", "America/Argentina/Buenos_Aires", "yyyy-MM-dd HH:mm")

#### StripLetters​

StripLetters(String)
Removes all letter characters and white spaces from a string
Example : StripLetters("Run 1")="1"

#### Substitute​

Substitute(String,String,String)
Substitutes new_text for old_text in a text string
Example : Substitute("test1","1","2")="test2"

#### TextJoin​

TextJoin(String,Boolean,String,...)
Joins together a series of supplied text strings into one combined text string. The user can specify a delimiter to add between the individual text items, if required.Ignore_empty is to allow to ignore empty cells to not end up with two delimiter consecutively
Example : TextJoin("-",false,"Test1","Test2")="Test1-Test2"

#### ToString​

ToString(Double, String, Boolean, JsonElement)
Returns the string representation of the input
Example : ToString(3)="3"

#### Upper​

Upper(String)
Converts all characters in a supplied text string to uppercase
Example : Upper("test1")="TEST1"

### Logical Functions​

#### GetPropertyValue​

GetPropertyValue(Part,PartProperty,type)
Returns Part.PartProperty. The type is the return type ("string","double", "boolean"). It allows to have dynamic part property access.
Example : GetPropertyValue(SpringFL,"Rate","double") returns SpringFL.Rate
GetPropertyValue(ARBFront,Concatenate("kArb",PosFL.Name"",ARBPosFR.Name),"double") returns ARBFront.kArb_1_1 if ARBPosFL & FR are equal to "1".

#### If​

If(Boolean,Any,Any)
An if statement. The return type is dependent on the return types of the 2nd and 3rd arguments. If there is any mismatch then their string values are returned
Example : If(1>0,"Correct","Incorrect")="Correct"

#### IsNull​

IsNull(Double, String, Boolean, DateTime, FlatModel)
Returns true if the input value is null
Example : IsNull("")=true IsNull(2)=false

### Date Time Functions​

#### DateTimeToString​

DateTimeToString(DateTime,String)
Formats a DateTime as a string using the provided format.
Example : If datetime is Friday 3rd of July 2019, 05:12:15.325 PM, then DateTimeToString(DateTime,"yyyy")="2019"
Other values for format string:
"yy" returns "19"
"MM" returns "07", "MMM" returns "JUL", "MMM" returns "JULY"
"dd" returns "03", "ddd" returns "Fri" , "dddd" returns "Friday"
"hh" returns "05", "HH" returns "17"
"mm" returns "12"
"ss" returns "15"
"ss.fff" returns "15.325", "ss.f" returns "15.3"
"tt" returns "PM"
"yyyy/MM/dd" returns "2019/07/03"
"hh:mm:ss" returns "05:12:15"

#### Now​

Now()
Returns an Instant representing the exact time the function is called. The function expects one input representing the time zone. If no input is specified, the time zone is considered to be UTC.
Example : Now("America/Argentina/Buenos_Aires")

### Flat Model Functions​

#### CalculateChanges​

CalculateChanges(FlatModel,FlatModel)
Returns a string that lists the differences between two flat models. The output of this function is impacted by any applicable Change Fromatter that is defined.
Example: CalculateChanges(Previous, this)

#### Lookup​

Lookup(ListOfFlatModel,String,Double, String, Boolean)
Return FlatModel for a given collection

Reads the contents of the attached file in the provided flat model, with the provided name (based on a singular named attached file parameter) and returns the contents of the file as a string.

#### Select​

Select(ListOfFlatModel,String)
Return a parameter of a given collection

### JSON Functions​

Adds a new, empty JSON object to the JSON element provided in the first argument. The second argument specifies the path to add the new object to, and the third arugment specifies the name.

Adds a JSON value to the JSON element provided in the first argument. The second argument specifies the path to add the new object to, and the third arugment specifies the name. The fourth argument specifies the value to add.

#### FindJsonObjectFromJsonObjectArray​

FindJsonObjectFromJsonObjectArray(JsonElement,String,String,String)
Searches for and returns the first Json object within a Json array that matches a specified search criteria. The first argument is the main Json element, the second argument is the path to the Json array. The thrid argument is the path to value within the object to check and the fourth argument is the value to match.
For example: FindJsonObjectFromJsonObjectArray(JsonObject, "Car.FlSuspension.Points", "Name", "IFLWB")

#### GetBooleanFromJsonElement​

GetBooleanFromJsonElement(JsonElement,String)
Extracts a boolean value from the input JSON element, based on the input path. The path supports indices if an item from array is to be retrieved. For example: GetStringFromJsonElement(jsonObject, "Car.FlSuspension.Points.2.IsInboard)

#### GetDoubleFromJsonElement​

GetDoubleFromJsonElement(JsonElement,String)
Extracts a numerical value from the input JSON element, based on the input path. The path supports indices if an item from array is to be retrieved. For example: GetDoubleFromJsonElement(jsonObject, "Car.FlSuspension.Points.2.Coordinates.X)

#### GetJsonFromOtherProfile​

GetJsonFromOtherProfile(String,FlatModel)
Returns the JSON from another profile. The profile name is provided in the first argument and the scope for the export is provided in the second argument.

#### GetJsonObjectFromJsonElement​

GetJsonObjectFromJsonElement(JsonElement,String)
Extracts a JSON element from the input JSON element, based on the input path. The path supports indices if an item from array is to be retrieved. For example: GetJsonObjectFromJsonElement(jsonObject, "Car.FlSuspension.Points.2.Coordinates)

#### GetStringFromJsonElement​

GetStringFromJsonElement(JsonElement,String)
Extracts a string value from the input JSON element, based on the input path. The path supports indices if an item from array is to be retrieved. For example: GetStringFromJsonElement(jsonObject, "Car.FlSuspension.Points.2.Coordinates.Comments)

#### IsJsonPathValid​

IsJsonPathValid(JsonElement,String)
Checks if the provided path is valid in the provided JsonElement and returns a boolean.

#### ParseJson​

ParseJson(String)
Parses the provided string and returns the parsed string as a JsonElement. This function coud be used with the ReadAttachedFile function, for example: ParseJson(ReadAttachedFile(FrontSpring, "SpringData"))

#### SelectBooleanFromJsonObjectArray​

SelectBooleanFromJsonObjectArray(JsonElement,String,String)
Extracts a list of boolean values from objects in an array within the input JSON element, based on the input path. For example: SelectBooleanFromJsonObjectArray(jsonObject, "Car.FlSuspension.Points", "IsValid")

#### SelectDoubleFromJsonObjectArray​

SelectDoubleFromJsonObjectArray(JsonElement,String,String)
Extracts a list of double values from objects in an array within the input JSON element, based on the input path. For example: SelectDoubleFromJsonObjectArray(jsonObject, "Car.FlSuspension.Points", "Distance")

#### SelectStringFromJsonObjectArray​

SelectStringFromJsonObjectArray(JsonElement,String,String)
Extracts a list of string values from objects in an array within the input JSON element, based on the input path. For example: SelectStringFromJsonObjectArray(jsonObject, "Car.FlSuspension.Points", "Name")

#### SubstituteJsonValue​

SubstituteJsonValue(JsonElement,String,Double, String, Boolean,Boolean)
Substitutes a value in a JsonElement. The inputs are the JsonElement, the path to the element to be replaced, the new value to be entered into the JsonElement. If the fourth boolean argument is true and the new value is null then the value will not be substituted. An overload with a fifth argument allows a format string for a double value to be specified.