# Arithmetic Calculations in SenseTalk

You can perform mathematical operations in SenseTalk by using mathematical operators as well as a variety of commands and functions. For detailed information about using operators, see the Expressions page, which describes the basics of using expressions in SenseTalk and links to pages for specific mathematical operators (+, -, *, and other operators) and other useful concepts such as comparisons and logical operators.

SenseTalk's arithmetic commands and functions also provide useful tools for working with numbers. Arithmetic Commands can be used to modify numeric values stored in containers. These commands perform the same arithmetic functions as the +, -, *, and / operators. The difference is that these commands take one of their operands from a container and store the result of the calculation back into that container. Arithmetic Functions operate on numbers. You can use these functions to manipulate numbers in a variety of ways.

In a topic related to arithmetic calculations, Points and Rectangles describes how SenseTalk understands the concepts of geometric points and rectangles. Any list of two numbers, or a text string consisting of two numbers separated by a comma, can be treated as a point. The functions explained on the **Points and Rectangles** page can be used to extract the various component values of a point or rectangle.

## Arithmetic Commands

There are four arithmetic commands:

Use them to modify values stored in containers. These commands perform the same arithmetic functions as the +, -, *, and / operators. The difference is that these commands take one of their operands from a container and store the result of the calculation back into that container.

`Add`

Command

**Behavior:** Use the `add`

command when you want to add a number to the value in a container, replacing the value in the container by the sum. Lists of values can be added, provided that both the source and destination lists contain the same number of items. Each item from the source list is added to the corresponding item of the destination container. *NumExpr* is a source expression. It can be a number, any formula, or another container. *Chunk* is a chunk expression describing part of a container (lines, words, items, or characters). *Container* is any container.

Syntax:

addnumExprto{chunkof}container

#### Examples

`add amount to dollarsVariable`

add 37 to item 2 of line 3 of scores

add speed * time to item 1 of distances

add [10,5] to centerPoint

**Related:**

`Subtract`

Command

**Behavior:** Use the `subtract`

command when you want to subtract a number from the value in a container, replacing the value in the container by the result. Lists of values can be subtracted, provided that both the source and destination lists contain the same number of items. Each item from the source list is subtracted from the corresponding item of the destination container. *NumExpr* is a source expression. It can be a number, any formula, or another container. *Chunk* is a chunk expression describing part of a container (lines, words, items, or characters). *Container* is any container.

Syntax:

subtractnumExprfrom{chunkof}container

#### Examples

`subtract checkAmt from accountBalance`

subtract 1 from property CountDown of gameController

subtract rate * pmt from line 4 of amortization

subtract [1,2] from boxDimensions

**Related:**

`Multiply`

Command

**Behavior:** Use the `multiply`

command when you want to multiply a value in a container by another number, replacing the value in the container by the product. Lists of values can be multiplied, provided that both the source and destination lists contain the same number of items, or that the source is a single value. Each item in the destination container is multiplied by the corresponding item of the source list, or by the source value. *NumExpr* is a source expression. It can be a number, any formula, or another container. *Chunk* is a chunk expression describing part of a container (lines, words, items, or characters). *Container* is any container.

Syntax:

multiply{chunkof}containerbynumExpr

#### Examples

`multiply score by weightingFactor`

multiply accountBalance by 1 + interestRate

multiply item 3 of line x of table by 2

**Related:**

`Divide`

Command

**Behavior:** Use the `divide`

command when you want to divide a value in a container by another number, replacing the value in the container by the quotient. Lists of values can be divided, provided that both the source and destination lists contain the same number of items, or that the source is a single value. Each item in the destination container is divided by the corresponding item of the source list, or by the source value. *NumExpr* is a source expression. It can be a number, any formula, or another container. *Chunk* is a chunk expression describing part of a container (lines, words, items, or characters). *Container* is any container.

Syntax:

divide{chunkof}containerbynumExpr

#### Examples

`divide score by totalCount`

divide item 1 of balances by 12

**Related:**

## Arithmetic Functions

Use these functions to manipulate numbers.

`Abs`

, `As a positive number`

, `As a negative number`

Functions

**Behavior:** Returns the absolute value of its numeric parameter. The absolute value is the magnitude of a number regardless of its sign — it is always positive or zero. `As a positive number`

returns the absolute value. `As a negative number`

returns the negative absolute value.

Syntax:

abs(numExpr)

the abs ofnumFactor

numFactoras a positive number

numFactoras a negative number

#### Examples

`put abs(-11) --> 11`

put the abs of -11 --> 11

#### Example

`if height is a negative number then put abs(height) into height`

#### Examples

`put (3 - 16) as a positive number --> 13`

put 500 as a negative number --> -500

`ACos`

Function

**Behavior:** Calculates the trigonometric arc cosine of a value and returns the result as an angle expressed in radians.

Syntax:

acos(numExpr)

{the}acos ofnumFactor

#### Examples

`put acos(0) --> 1.570796 radians`

put the acos of 0 --> 1.570796 radians

put acos(0.5) as degrees --> 60 degrees

**Related:**

`ACosh`

Function

**Behavior:** Calculates the inverse hyperbolic cosine of a value and returns the result as an angle expressed in radians.

Syntax:

acosh(numExpr)

{the}acosh ofnumFactor

#### Examples

`put acosh(2.509178) rounded to the nearest degree --> 90 degrees`

put the acosh of 1 --> 0 radians

**Related:**

`Annuity`

Function

**Behavior:** Calculates the present value of an ordinary annuity with payments of one unit, based on the specified interest rate per period and the number of periods.

Syntax:

annuity(interest,periods)

#### Example

`put annuity(1%, 32) --> 27.269589`

**Related:**

`ASin`

Function

**Behavior:** Calculates the trigonometric arc sine of a value and returns the result as an angle expressed in radians.

Syntax:

asin(numExpr)

{the}asin ofnumFactor

#### Examples

`put asin(0) --> 0 radians`

put asin of 1 --> 1.570796 radians

put asin(0.5) as degrees --> 30 degrees

**Related:**

`ASinh`

Function

**Behavior:** Calculates the inverse hyperbolic sine of a value and returns the result as an angle expressed in radians.

Syntax:

asinh(numExpr)

{the}asinh ofnumFactor

#### Examples

`put asinh(0) --> 0 radians`

put the asinh of 2.301299 rounded to the nearest degree --> 90 degrees

**Related:**

`ATan`

Function

**Behavior:** Returns the trigonometric arctangent of its parameter as an angle expressed in radians.

Syntax:

atan(numExpr)

the atan ofnumFactor

#### Examples

`put atan(19) --> 1.518213 radians`

put the atan of 5 --> 1.373401 radians

**Related:**

`ATanh`

Function

**Behavior:** Calculates the inverse hyperbolic tangent of a value and returns the result as an angle expressed in radians.

Syntax:

atanh(numExpr)

{the}atanh ofnumFactor

#### Examples

`put atanh(0.917152) rounded to the nearest degree --> 90 degrees`

put the atanh of 0 --> 0 radians

**Related:**

`ATanPt`

Function

**Behavior:** Calculates the trigonometric arc tangent of a point and returns the result as an angle expressed in radians.

Syntax:

atanPt(aPoint)

atanPt(xCoord,yCoord)

{the}atanPt ofaPoint

The `atanPt`

function provides the same functionality as the **atan2** function in other languages, but accepts either a point, or coordinates in *x,y* order as parameters, rather than *y,x*.

#### Examples

`put atanPt(123,0) --> 0 radians`

put the atanPt of [11,56] --> 1.376837 radians

#### Example

`set myPoint to [50,50]`

put atanPt(myPoint) as degrees --> 45 degrees

**Related:**

`Average`

Function

**Behavior:** Returns the average of its parameters.

Syntax:

average(numList)

{the}average ofnumList

The parameter *numList* may be a list of numbers, an expression which evaluates to a list of numbers separated by commas, or a combination of these, nested to any depth.

#### Examples

`put average(8, 10, 12) --> 10`

put the average of [3,7,15,84,6,42,11] --> 24

#### Example

This example is an incomplete portion of code meant to illustrate how the feature may be used

`if the average of [x,y,z] is greater than z then`

put "Z is below average!"

end if

**Related:**

`Compound`

Function

**Behavior:** Computes the principal plus accrued interest on an investment of 1 unit, based on the specified interest rate and the number of periods.

Syntax:

compound(interest,periods)

#### Example

`put compound(7.25%, 6) --> 1.521892`

#### Example

`put 10 into initialinvestment`

put initialInvestment * compound(6.7%, 12) into currentValue

put currentvalue --> 21.775746

**Related:**

`Cos`

Function

**Behavior:** Returns the trigonometric cosine of its parameter, which is an angle expressed in radians.

Syntax:

cos(numExpr)

{the}cos ofnumFactor

#### Examples

`put cos(18) --> 0.660317`

put the cos of 18 --> 0.660317

**Related:**

`Cosh`

Function

**Behavior:** Returns the hyperbolic cosine of its parameter, which is an angle expressed in radians.

Syntax:

cosh(numExpr)

{the}cosh ofnumFactor

#### Examples

`put cosh(0) --> 1 (no units specified, so 0 radians assumed)`

put cosh of 90 degrees --> 2.509178

**Related:**

`Cube Root`

, `CbRt`

Function

**Behavior:** Computes the cube root of its parameter.

Syntax:

cube root(number)

{the}cube root ofnumber

cbrt(numExpr)

#### Examples

`put cube root (27) --> 3`

put the cube root of 8 --> 2

put cbrt(125) --> 5

**Related:**

`Exp`

Function

**Behavior:** Returns the natural exponential of its parameter (that is, the mathematical constant **e** raised to the power of the parameter).

Syntax:

exp(numExpr)

{the}exp ofnumFactor

#### Examples

`put exp(2) --> 7.389056`

put the exp of 1 --> 2.718282

**Related:**

`Exp1`

Function

**Behavior:** Returns one less than the natural exponential of its parameter (that is, the mathematical constant e raised to the power of the parameter, minus 1).

Syntax:

exp1(numExpr)

{the}exp1 ofnumFactor

#### Examples

`put exp1(2) --> 6.389056`

put the exp1 of 2 --> 6.389056

**Related:**

`Exp2`

Function

**Behavior:** Returns 2 raised to the power of its parameter.

Syntax:

exp2(numExpr)

{the}exp2 ofnumFactor

#### Examples

`put exp2(8) --> 256`

put exp2 of 10 --> 1024

**Related:**

`Frac`

Function

**Behavior:** Returns the fractional part of a number. Use the `trunc`

function to get the whole number part of a value. The `trunc`

and `frac`

functions are defined such that `trunc(x) + frac(x)`

is always equal to `x`

.

Syntax:

frac(numExpr)

{the}frac ofnumFactor

#### Examples

`put frac(81.236) --> 0.236`

put frac of 8.125 --> 0.125

**Related:**

`Ln`

Function

**Behavior:** Returns the natural logarithm of its parameter.

Syntax:

ln(numExpr)

{the}ln ofnumFactor

#### Examples

`put ln(2) --> 0.693147`

put the ln of 4 --> 1.386294

**Related:**

`Ln1`

Function

**Behavior:** Returns the natural logarithm of 1 more than its parameter.

Syntax:

ln1(numExpr)

{the}ln1 ofnumFactor

#### Examples

`put ln1(2) --> 1.098612`

put the ln1 of 8 --> 2.197225

**Related:**

`Log10`

Function

**Behavior:** Returns the base 10 logarithm of its parameter.

Syntax:

log10(numExpr)

{the}log10 ofnumFactor

#### Examples

`put log10(100) --> 2`

put the log10 of one million --> 6

**Related:**

`Log2`

Function

**Behavior:** Returns the base 2 logarithm of its parameter.

Syntax:

log2(numExpr)

{the}log2 ofnumFactor

#### Examples

`put log2(256) --> 8`

put the log2 of 8 --> 3

**Related:**

`Maximum`

, `Max`

, `HighestValue`

, `LargestValue`

Functions

**Behavior:** Returns the highest number from a list. The `maximum`

function may be abbreviated as `max`

or expressed using one of the synonyms `highestValue`

or `largestValue`

.

Syntax:

[max|maximum|highestValue|largestValue](numList)

{the} [max|maximum|highest value|largest value]ofnumList

The parameter *numList* may be a list of numbers, an expression which evaluates to a list of numbers separated by commas, or a combination of these, nested to any depth.

#### Examples

`put max(4, 6, 5, 7, 3) --> 7`

put largestValue of [2,23,45,76] --> 76

put the highest value of [3,42,9,13,21] --> 42

#### Example

This example is an incomplete portion of code meant to illustrate how the feature may be used

`if the maximum of [x,y,z] is z then`

put "Z is the greatest!"

end if

**Related:**

`Median`

Function

**Behavior:** Returns the median (middle value) of its parameters when arranged in numeric order, or the average of the two middle values.

Syntax:

median(numList)

{the}median ofnumList

The parameter *numList* may be a list of numbers, an expression which evaluates to a list of numbers separated by commas, or a combination of these, nested to any depth. If *numList* contains an odd number of numbers, the median is the middle value of the sorted list of numbers, otherwise it is the average of the two middle values.

#### Examples

`put median(1, 2, 8, 9, 12) --> 8`

put the median of "2,7,8,10" --> 7.5

**Related:**

`Minimum`

, `Min`

, `LowestValue`

, `SmallestValue`

Functions

**Behavior:** Returns the lowest number from a list. The `minimum`

function may be abbreviated as `min`

or given as one of the synonyms `lowestValue`

or `smallestValue`

.

Syntax:

[min|minimum|lowestValue|smallestValue](numList)

{the} [min|minimum|lowest value|smallest value]ofnumList

The parameter *numList* may be a list of numbers, an expression which evaluates to a list of numbers separated by commas, or a combination of these, nested to any depth.

#### Examples

`put min(4,6,5,7,3) --> 3`

put lowestValue of [3,9,13,21,42] --> 3

put smallest value of [9,13,21,56,72] --> 9

#### Example

This example is an incomplete portion of code meant to illustrate how the feature may be used

`if the min of [x,y,z] is z then put "Z is the smallest!"`

**Related:**

`Payment`

Function

**Behavior:** Returns the payment amount of a loan, given a loan amount, interest rate, term, and frequency of payments.

Syntax:

payment(loanProperties)

payment(principal,rate,term{,frequency}){

the} {daily|weekly|monthly|quarterly|yearly|annual}payment on{a} {loan of}principal{loan}at{a rate of}rate{interest}for{a term of}term{ {with} [ [payments|paid]frequency|frequencypayments] }

If *loanProperties* is given as a property list, it should include:

**Principal**or**Amount**—*principal*amount of the loan (may be specified with a currency unit)**Rate**— interest*rate*of the loan (may be specified as percent per year, calendarQuarter, month, week, day — if per period is not specified, annual interest rate is assumed)**Term**— the*term*length of the loan (may be given as a duration of time or as a number of payments. If a number of payments is used (with no duration units), then frequency parameter is required)**Frequency**— the*frequency*of loan payments (optional if loan term is given as a duration) — may be one of these terms: monthly, months, calendarMonths, quarterly, calendarQuarters, annual, annually, yearly, years, calendarYears, decades, calendarDecades

If the *principal* is given in units of a particular currency, then the payment amount returned will have the same units. If *term* is specified with units of duration and *frequency* is omitted, then the term's units will be used as the frequency of payments.

#### Examples

`put payment($10000,7.5%,60,"months") --> $200.379486`

put payment(amount:$1000, rate: 6.5% per year, term:60 months) --> $19.566148

#### Examples

`put the monthly payment on a ten thousand dollar loan at 4.5% yearly for 10 years --> $103.638409`

put payment on a loan of $50000 at 7 percent interest for 60 months rounded to 2 places --> $990.06

**Related:**

`Random`

Function

**Behavior:** Returns a randomly generated integer between 1 and the value of its parameter, or between two values, inclusive.

Syntax:

random(numExpr{,secondExpr})

{the}random ofnumFactor

#### Examples

`put random(12) -- returns any number from 1 to 12`

put random(20,30) -- gets a number from 20 to 30, inclusive

put (random(100) / 100) into randomPercentage

**Related:**

`Reset Random`

Command

**Behavior:** Resets the random number generator sequence used by the `random`

function and whenever SenseTalk selects things at random. By setting a specific *seedExpr* value for the random number generator, you can obtain a repeatable sequence of "random" events. This can be very useful for testing purposes. Use the `reset random`

command without a seed value to get an unpredictable sequence.

Syntax:

reset random{{with|from} {seed}seedExpr}

#### Example

`reset random with seed 27`

#### Example

`reset random`

#### Example

`reset random 2`

repeat 10 times

put 1..10 into NumberRange

put any item of NumberRange into ReplaceitemNumber

log ReplaceitemNumber // Using reset random [#] as shown in line 1 results in the same list every time you run the loop.[#] can be any seed number.

// Commenting out "reset random 2" in line 1 and running the repeat loop multiple times results in a different list every time you run the loop.

end repeat

**Related:**

`Round`

Function

**Behavior:** Returns the value of its parameter rounded to the nearest whole number. An optional second parameter may be supplied to specify the number of decimal places to round to. A negative number of places will round to the left of the decimal point.

Syntax:

round(numExpr{,decimalPlaces})

{the}round ofnumFactor

#### Examples

`put round(6.5) --> 7`

put round(6.49) --> 6

put round(6.49 , 1) --> 6.5

put round(2389 , -2) --> 2400

**Related:**

`RoundToNearest`

Function

**Behavior:** Returns the value of its first parameter rounded to the nearest whole multiple of its second parameter.

Syntax:

roundToNearest(numExpr,nearestMultiple)

numExprrounded to{the}nearest{multiple of}nearestMultiple

#### Examples

`put roundToNearest(643,100) --> 600`

put roundToNearest(643,25) --> 650

put 12.16 rounded to the nearest multiple of .25 --> 12.25

**Related:**

`Sin`

Function

**Behavior:** Returns the trigonometric sine of its parameter, which is an angle expressed in radians.

Syntax:

sin(numExpr)

{the}sin ofnumFactor

#### Examples

`put sin(18) --> -0.750987`

put the sin of 8 --> 0.989358

**Related:**

`Sinh`

Function

**Behavior:** Returns the hyperbolic sine of its parameter, which is an angle expressed in radians.

Syntax:

sinh(numExpr)

{the}sinh ofnumFactor

#### Examples

`put sinh(0) --> 0 (no units specified, so 0 radians assumed)`

put sinh of 90 degrees --> 2.301299

**Related:**

`Square Root`

, `SqRt`

Function

**Behavior:** Returns the square root of its parameter.

Syntax:

sqrt(numExpr)

{the} [square root|sqrt]ofnumFactor

#### Examples

`put sqrt(16) --> 4`

put the square root of nine --> 3

**Related:**

`Sum`

Function

**Behavior:** Returns the sum of its parameters.

Syntax:

sum(numList)

{the}sum ofnumList

*numList* may be a list of numbers, an expression which evaluates to a list of numbers separated by commas, or a combination of these, nested to any depth.

#### Example

`put sum("8,1", [10,11], 12) --> 42`

#### Example

This example does not run as written and must be modified to execute

`if the sum of [x,y,z] is more than 100 then`

put "The sum exceeds 100"

end if

**Related:**

`Tan`

Function

**Behavior:** Returns the trigonometric tangent of its parameter, which is an angle expressed in radians.

Syntax:

tan(numExpr)

{the}tan ofnumFactor

#### Examples

`put tan(18) --> -1.137314`

put tan of 10 --> 0.648361

**Related:**

`Tanh`

Function

**Behavior:** Returns the hyperbolic tangent of its parameter, which is an angle expressed in radians.

Syntax:

tanh(numExpr)

{the}tanh ofnumFactor

#### Examples

`put tanh(0) --> 0 (no units specified, so 0 radians assumed)`

put tanh of 90 degrees --> 0.917152

**Related:**

`Trunc`

Function

**Behavior:** Truncates a number, returning the integer part of its parameter, and discarding any fractional part. Use the `frac`

function to get the fractional part of a value. The `trunc`

and `frac`

functions are defined such that `trunc(x) + frac(x)`

is always equal to `x`

.

Syntax:

trunc(numExpr)

{the}trunc ofnumFactor

#### Examples

`put trunc(6.8) --> 6`

put trunc(6.49) --> 6

**Related:**