Mathematical Functions

In This Topic

- Action - Array - File - Lookup Table - Mathematical - Miscellaneous - Text - Variable - Database -
[ Full Index ] - [ Sorted Index ]

These functions deal with anything related to numbers, including trigonometry, rounding and randomness.

For functions that take any number of parameters (e.g. Average and Sum) you can also provide an array of values and it will be expanded first - see the tutorials on Arrays and Wall and PolyItem Edges: Array[i] Syntax.

Abs
Returns the absolute value of a number
Syntax	Abs (number)
Inputs	Number is what you want the absolute value of
Notes	The absolute value of a number is the number without its sign, and is therefore always positive. Taking the absolute of a positive number does not change it
Examples	Abs (5) = 5 Abs (-5) = 5
See Also	Sign

ACos
Returns the arccosine of a number. ACos is effectively the reverse of the Cos function
Syntax	ACos (number)
Inputs	Number is the cosine of the angle you want
Outputs	An angle in the range -90 to +90 degrees
Examples	ACos (0.5) = 60 degrees
See Also	ASin, ATan, ATan2

AngleBetween
Returns the measurement of an angle between 2 points
Syntax	AngleBetween (point1, point2)
Inputs	Point1, Point2 are the two points of the angle to be calculated
Outputs	An angle between currently selected units

ArcAngle
returns the angle subtended between two points on an arc
Syntax	ArcAngle (point1, point2, radius)
Inputs	Point1, Point2 are the endpoints of an arc drawn with arc radius specified
Outputs	The subtended angle of this arc is calculated and returned as an Angle type
See Also	ArcCentre, ArcLength

ArcCentre
Returns the centre of an arc between two points with given radius
Syntax	ArcCentre (point1, point2, radius)
Inputs	Point1, Point2 are the endpoints of an arc drawn with arc radius specified
Outputs	The centre point of this arc is calculated and returned as a Point2D
See Also	ArcAngle, ArcLength

ArcLength
Returns the length of an arc between two points with given radius
Syntax	ArcLength (point1, point2, radius)
Inputs	Point1, Point2 are the endpoints of an arc drawn with arc radius specified
Outputs	The length of this arc is calculated and returned
Notes	To use in an array, see Walls and Polyitem Edges.
See Also	ArcAngle, ArcCentre

Area
Computes an area from two lengths, using the formula "height x width"
Syntax	Area (length1, length2)
Inputs	Length1, length2 are the two dimensions of the area to be calculated
Outputs	An area in the currently selected units
Examples	Area (500mm, 1.5m) = 0.75 sqm

ASin
Returns the arcsine of a number. ASin is effectively the reverse of the Sin function
Syntax	ASin (number)
Inputs	Number is the sine of the angle you want
Outputs	An angle in the range -90 to +90 degrees
Examples	ASin (0.5) = 30 degrees
See Also	ACos, ATan, ATan2

ATan
Returns the arctangent of a number. ATan is effectively the reverse of the Tan function
Syntax	ATan (number)
Inputs	Number is the tangent of the angle you want
Outputs	An angle in the range -90 to +90 degrees
Notes	ATn has the same functionality
Examples	ATan (1) = 45 degrees
See Also	ASin, ACos, ATan2

ATan2
Returns the arctangent of a vector, i.e. the angle of a line between the origin and a specified point
Syntax	ATan2 (y, x)
Inputs	Y, X are the vertical and horizontal components of the vector
Outputs	An angle in the range -90 to +90 degrees
Notes	The vector is a line from the origin (0, 0) to a specified point (x, y). ATan2 calculates the angle between this line and the x-axis (zero degrees). ATan2 (y, x) is the same as ATan (y/x) except in ATan2 x can equal zero
Examples	ATan2 (1,1) = 45 degrees ATan2 (3, -3) = -45 degrees
See Also	ASin, ACos, ATan

Average
Calculates the average of two or more numbers
Syntax	Average (number1, number2, ...)
Inputs	Number1, number2, ... are the numbers you wish to get the average of, you can provide several
Examples	Average (3, 6, 5, 6) = 5
See Also	Max, Min

Between
Tests whether a value is between a given lower and upper bound
Syntax	Between (value, lower, upper, inclusive)
Inputs	Returns Yes if value is more than lower and less than upper. Inclusive is an optional flag that indicates whether each bounds test is inclusive or exclusive, see Notes
Notes	Inclusive is a number from 1 to 4: If inclusive is 0, the test is "value > lower And value < upper" If inclusive is 1, the test is "value > lower And value <= upper" (default) If inclusive is 2, the test is "value >= lower And value < upper" If inclusive is 3, the test is "value >= lower And value <= upper"
Examples	Between (10, 5, 14) = Yes Between (10, 10, 11, 3) = Yes Between (34.2, 30, 34.2, 2) = No

Ceiling
Rounds a number up to the nearest whole number, or nearest multiple of a specified number
Syntax	Ceiling (number, step)
Inputs	Number is the number to be rounded up Step is optional. If included, number is rounded up to the nearest multiple of step
Notes	Note that unlike MRound, Ceiling always rounds up
Examples	Ceiling (34.2) = 35 Ceiling (-183.2) = -183 Ceiling (867.3, 40) = 880
See Also	Floor, MRound, Trunc

Cos
Returns the cosine of an angle
Syntax	Cos (angle)
Inputs	Angle is the angle (in degrees) that you want the cosine of
Examples	Cos (0) = 1 Cos (90) = 1 Cos (60) = 0.5
See Also	Sin, Tan, ACos

Degrees
Converts an angle from radians into degrees
Syntax	Degrees (angle)
Inputs	Angle is the number to be converted into degrees
Notes	If units are not provided, the input angle is assumed to be in radians
Examples	Degrees (1.5707) = 90 deg Degrees (Pi) = 180 deg
See Also	Radians

Distance
Measures the distance between 2 points
Syntax	Distance (Point1, Point2)
Inputs	Point1, Point2 are the points to measure distance between.
Notes	These can be defined in either 2 or 3 dimensions.

Even
Rounds a number up to the nearest even whole number
Syntax	Even (number)
Inputs	Number is what needs rounding up to an even number
Examples	Even (2.13) = 4 Even (-9.8) = -8
See Also	Odd

Floor
Rounds a number down to the nearest whole number, or nearest multiple of a specified number
Syntax	Floor (number, step)
Inputs	Number is the number to be rounded down Step is optional. If included, number is rounded down to the nearest multiple of step
Notes	Note that unlike MRound, Floor always rounds down
Examples	Floor (34.2) = 34 Floor (-183.95) = -184 Floor (867.3, 40) = 840
See Also	Ceiling, MRound, Trunc

Hypot
Returns the length of the hypotenuse of a right angled triangle
Syntax	Hypot (x, y)
Inputs	X, Y are the lengths of two sides of a right angled triangle. Hypot(x,y) returns sqrt(x2 + y2)
Notes	Hypot calculates the length of the hypotenuse of the right angled triangle.
Examples	Hypot (3,4) = 5 Hypot (3mm, 4mm) = 5mm
See Also	Sqrt

Intersection
For calculating the intersection of two 2D lines
Syntax	Intersection (line1Pt1, line1Pt2, line2Pt1, line2Pt2) or Intersection (line1Pt1, line1Angle, line2Pt1, line2Angle)
Inputs	Line1Pt1 and Line1Pt2 are the two endpoints of Line1 in the first syntax. In the second syntax, Line1Pt1 and Line2Angle defines a line through the point at specified angle. Line2Pt1 and Line2Pt2 are the two endpoints of Line2 in the first syntax. In the second syntax, Line2Pt1 and Line2Angle defines a line through the point at specified angle. The points must be Point2D types.
Outputs	Returns the intersection point of the two lines as a Point2D, or returns #N/A for failure. For lines specified as two endpoints, this will only return an intersection point if on or within the lines.
Notes	It is only valid to specify 2 angles or 2 secondary points, not a mix of types to a single call.

Max
Returns the largest number from a set of numbers
Syntax	Max (number1, number2, ...)
Inputs	Number1, number2, ... are the numbers you wish to find the maximum of, you can provide several
Examples	Max (23, 17, 34, 29) = 34
See Also	Min, Average

MidPoint
Find the midpoint between 2 points.
Syntax	MidPoint (Point1, Point2)
Inputs	Point1 is the first point and Point2 is the second point to find the midpoint between.
Notes	These can be defined in either 2 or 3 dimensions. See also EdgeMidPoint in tutorial Wall and PolyItem Edges.

Min
Returns the smallest number from a set of numbers
Syntax	Min (number1, number2, ...)
Inputs	Number1, number2, ... are the numbers you wish to find the minimum of, you can provide several
Examples	Min (23, 17, 34, 29) = 17
See Also	Max, Average

Mod
Returns the remainder when a specified number is divided by another
Syntax	Mod (number1, number2)
Inputs	Number1 is divided by number2 and the remainder is given. Number2 should not be zero, as dividing by zero is undefined
Notes	If number2 divides exactly into number2, the result of Mod will be zero. This is useful for testing for multiples (factors)
Examples	Mod (22, 8) = 6 Mod (-8, 3) = -2 Mod (16, 4) = 0
See Also	Quotient

MRound
Rounds a number to the nearest whole number, or nearest multiple of a specified number
Syntax	MRound (number, step)
Inputs	Number is the number to be rounded Step is optional. If included, number is rounded to the nearest multiple of step
Examples	MRound (34.2) = 34 MRound (-183.95) = -184 MRound (867.3, 40) = 880
See Also	Ceiling, Floor, Trunc

Odd
Rounds a number up to the nearest odd whole number
Syntax	Odd (number)
Inputs	Number is what needs rounding up to an odd number
Examples	Odd (2.13) = 3 Odd (-9.8) = -9
See Also	Even

Power
Returns a number raised to a specific power
Syntax	Power (base, exponent)
Inputs	Base is the number to be raised to the power of exponent
Examples	Power (2, 8) = 256
See Also	Sqrt

Product
Returns the result when a set of numbers is multiplied together
Syntax	Product (number1, number2, ...)
Inputs	Number1, number2, ... are the numbers to be multiplied, you can provide several
Examples	Product (3, 4, 2) = 24 Product (-5, 8, 0.5) = -20

ProjectOntoLine
Projects a point
Syntax	ProjectOntoLine (point, linepoint1, linepoint2]) or ProjectOntoLine (point, linepoint1, lineangle])
Inputs	Point is the point to be projected onto the line joining LinePoint1 to LinePoint2 in the first syntax. The second syntax option allows you to define a line through LinePoint1 at the specified LineAngle
Outputs	Returns the projected point on the specified line. Calling the function with Point2D parameters will return a Point2D output. Calling with Point3D returns Point3D output.
Notes	The input point parameters can be all Point2D types or Point3D types, but not a mixture.

Quotient
Returns how many times one number divides into another
Syntax	Quotient (number1, number2)
Inputs	Number1 is divided by number2 and the remainder is discarded
Notes	This function is equivalent to Floor (number1 / number2). Number2 should not be zero or an error will result
Examples	Quotient (20, 8) = 2 Quotient (-9, 2) = -4
See Also	Mod

Radians
Converts an angle from degrees into radians
Syntax	Radians (angle)
Inputs	Angle is the number to be converted into radians
Notes	If units are not provided, the input angle is assumed to be in degrees
Examples	Radians (90) = 1.5707 rad Radians (180) = 3.1415 (i.e. the value of Pi)
See Also	Degrees

Rand
Generates a random number between zero and one
Syntax	Rand ( )
Inputs	None
Outputs	A random number R is created, such that 0 ≤ R < 1 ie can be exactly 0 but never exactly 1
Notes	Even though Rand doesn't take any inputs, you must still include the empty brackets to indicate it is a function. There is also a constant Rnd which acts the same as Rand
Examples	Rand ( ) = 0.868927 Rand ( ) = 0.018311
See Also	Random, RandBetween, Rnd

RandBetween
Generates a random whole number between two specified limits
Syntax	RandBetween (lower, upper)
Inputs	Lower, upper are the two limits that the random number must fall within
Outputs	A random integer R is created, such that lower ≤ R ≤ upper
Notes	The specified limits are inclusive, ie the random number could be equal to one of the limits. RandBetween is different from the other random functions in that it returns a whole number instead of a fraction (floating point number)
Examples	RandBetween (1000, 2000) = 1492 RandBetween (10, 15) = 12
See Also	Rand, Random, Rnd

Random
Generates a random number between zero and one inclusive
Syntax	Random ( )
Inputs	None
Outputs	A random number R is created, such that 0 ≤ R ≤ 1
Notes	Even though Random doesn't take any inputs, you must still include the empty brackets to indicate it is a function. Random differs from the Rand function because its range includes 1
Examples	Random ( ) = 0.868927 Random ( ) = 1.000
See Also	Rand, RandBetween, Rnd

Rnd
Generates a random number between zero and one
Syntax	Rnd ( )
Inputs	None
Outputs	A random number R is created, such that 0 ≤ R < 1 ie can be exactly 0 but never exactly 1
Notes	Acts is same way as Rand and you must still include the empty brackets to indicate it is a function. See topic on constants Rnd.
Examples	Rnd ( ) = 0.868927 Rnd ( ) = 0.018311
See Also	Rand, Random, RandBetween

RotatePoint
Rotates a point
Syntax	RotatePoint (point, angle [, centerPoint])
Inputs	Point the point to be rotated Angle determining how much rotation to apply centerPoint is optional and is the center of rotation - if not specified, the point is rotated about the origin, ie Point2D(0mm,0mm)

Sign
Indicates whether a specified number is positive, negative or zero
Syntax	Sign (number)
Inputs	Number is what you need the sign of
Outputs	Sgn and Sign returns -1 if number is negative, +1 if its positive, and 0 if it is equal to zero
Notes	The Sign function is effectively the same as "number / Abs (number)", except number can equal zero
Examples	Sign (-21384) = -1 Sign (43) = 1
See Also	Abs

Sin
Returns the sine of an angle
Syntax	Sin (angle)
Inputs	Angle is the angle (in degrees) that you want the sine of
Examples	Sin (0) = 0 Sin (90) = 1 Sin (30) = 0.5
See Also	Cos, Tan, ASin

Sqrt
Returns the square root of a specified number
Syntax	Sqrt (number)
Inputs	Number is what you want the square root of
Notes	Number must not be negative. Use Abs to ensure it is always positive. Sqr is an alias for Sqrt (as per VBA). To square a single value, use SumSq with one argument.
Examples	Sqrt (16) = 4 Sqrt (123) = 11.090537
See Also	Hypot

Sum
Adds together a specified set of numbers and returns the result
Syntax	Sum (number1, number2, ...)
Inputs	Number1, number2, ... are the numbers you want to be added, you can provide several
Examples	Sum (10, 5, 300, -50) = 265
See Also	SumSq

SumSq
Adds together the squares of a specified set of numbers and returns the result
Syntax	SumSq (number1, number2, ...)
Inputs	Number1, number2, ... are the numbers of which you want the squares to added, you can provide several
Notes	Each number is squared first, and then the squares are added together. This is not the same as using the Sum function then squaring that result
Examples	SumSq (4, 2, 10) = 120
See Also	Sum

Tan
Returns the tangent of an angle
Syntax	Tan (angle)
Inputs	Angle is the angle (in degrees) that you want the tangent of
Examples	Tan (0) = 0 Tan (45) = 1 Tan (90) = undefined
See Also	Sin, Cos, ATan

Trunc
Removes any fraction from the specified number and returns a whole number
Syntax	Trunc (number)
Inputs	Number is the number to be truncated
Notes	Trunc does not round numbers to the nearest whole number, it just cuts off anything after the decimal point
Examples	Trunc (34.2) = 34 Trunc (-183.95) = -183
See Also	Floor, Ceiling, MRound