# Utility and Conversion Functions

## Data Type Conversion

**IMPORTANT**: For more information about AeroScript data types, refer to AeroScript Programming Language

### Integer and Real Data Types

The AeroScript programming language automatically converts between real data types (IEEE 64-bit floating point) and integer data types (64-bit signed integer). If a function or a variable assignment expects a real data type and you provide an integer, one of the scenarios that follow occurs:

- If the integer data type can be represented as a real (no loss of precision), the conversion occurs automatically.
- If the integer data type cannot be represented as a real (because of having more than 53 bits of precision), the conversion causes a task error

If a function or a variable assignment expects an integer and you provide a real data type, one of the scenarios that follow occurs:

- If the real data type can be represented as an integer (no fractional component), the conversion occurs automatically.
- If the real data type cannot be represented as an integer (because of a fractional component), the conversion causes a task error.

If you want to do rounding or determine the integer and fractional components of a real data type, use one of the functions in the Math Functions topic.

Use the function that follows to determine if a real value is a not-a-number (NaN) value.

function RealIsNan($value as real) as integer

Returns whether the specified value is NaN.

Arguments

$value A 64-bit floating-point value.

Returns

Returns 1 if the real is NaN, 0 otherwise.

Use the function that follows to determine if a real value represents infinity.

function RealIsInfinity($value as real) as integer

Returns whether the specified value is infinite.

Arguments

$value A 64-bit floating-point value.

Returns

Returns 1 if the real is +infinity or -infinity, 0 otherwise.

Use the functions that follow to convert an IEEE floating-point value to a bit value represented as an integer or to convert a bit value represented as an integer to an IEEE floating-point value.

function BitConvertFloat32ToUInt32($value as real) as integer

Stores the bit pattern of a 32-bit floating-point value into an unsigned 32-bit integer.

Arguments

$value The value from which to get the bit pattern.

Returns

The bit pattern that represents the 32-bit floating-point value.

function BitConvertFloat64ToInt64($value as real) as integer

Stores the bit pattern of a 64-bit floating-point value into a signed 64-bit integer.

Arguments

$value The value from which to get the bit pattern.

Returns

The bit pattern that represents the 64-bit floating-point value.

function BitConvertUInt32ToFloat32($value as integer) as real

Converts a 32-bit integer bit pattern to its 32-bit floating-point representation.

Arguments

$value The bit pattern.

Returns

The 32-bit floating-point value that represents the specified bit pattern value.

function BitConvertInt64ToFloat64($value as integer) as real

Converts a 64-bit integer bit pattern to its 64-bit floating-point representation.

Arguments

$value The bit pattern.

Returns

The 64-bit floating-point value that represents the specified bit pattern value.

### Axis Data Type

You can convert the axis data type to an axis index with the function that follows. The returned value is an integer, but you can also assign it to a real variable.

function AxisToInteger($value as axis) as integer

Gets the index of the specified axis as an integer.

Arguments

$value The axis from which to get the index.

Returns

The index of the specified axis.

To convert an axis index stored as an integer or real into an axis data type, use the special @ AeroScript language keyword. For example:

var $myAxis as axis = @0

### String Data Type

You can convert between a string data type and an axis, integer, or real data type with the functions in the String Functions topic. See the relevant string functions that follow.

function AxisToString($value as axis) as string

Returns the string representation of the specified axis value.

Arguments

$value The axis value to convert to a string.

Returns

The string representation of the specified axis.

function IntegerToString($value as integer) as string

Returns the string representation of the specified integer value.

Arguments

$value The integer value to convert to a string.

Returns

The string representation of the specified integer.

function RealToString($value as real) as string

Returns the string representation of the specified real value.

Arguments

$value The real value to convert to a string.

Returns

The string representation of the specified real.

function StringToInteger($string as string) as integer

Returns the integer value of the specified string.

Arguments

$string The string from which to get the integer value.

Returns

The integer value of the specified string.

function StringToReal($string as string) as real

Returns the real value of the specified string.

Arguments

$string The string from which to get the real value.

Returns

The real value of the specified string.

To convert an axis name stored as a string into an axis data type, use the special @ AeroScript language keyword. For example:

var $myStr as string = "X"

var $axis as axis = @$myStr

## Units Conversion

Controller positional units are usually specified in millimeters (mm), micrometers (µm), or degrees (deg), but you can configure them for any type of unit. Machine Setup configures each axis in your system to the units you specify. Because the controller internally stores positions in encoder counts, you can use the functions that follow to convert between units and counts. A value in counts is useful for some advanced controller features such as PSO.

**IMPORTANT**: If the ReverseMotionDirection parameter is set to Yes, the `CountsToUnits()`

and `UnitsToCounts()`

functions invert the sign of the returned value.

function CountsToUnits($axis as axis, $counts as real) as real

Returns the value in user units of a specified value in counts.

Arguments

$axis The axis to use when performing the conversion.

$counts The value in counts.

Returns

The value converted to user units.

function UnitsToCounts($axis as axis, $units as real) as real

Returns the value in counts of a specified value in user units.

Arguments

$axis The axis to use when performing the conversion.

$units The value in user units.

Returns

The value converted to counts.

## Timers

You can measure the execution time of a section of an AeroScript program by clearing and reading one of the 32 system timers. Automation1 has 32 timers, and you can select them by entering their zero-based index number (0-31) as the timer number.

Each timer runs independently and continuously from the last time you zero it or the last controller reset.

Timer values are always returned in milliseconds. If the timer mode is set to TimerMode.Standard, the TimerRead() function returns an integer number of milliseconds. If the timer mode is set to TimerMode.Precise, the TimerRead() returns a decimal number of milliseconds with a resolution of 0.0001 milliseconds.

function TimerClear($timerNum as integer)

Sets the value of the specified timer to zero.

Arguments

$timerNum The timer to clear.

function TimerRead($timerNum as integer, $timerMode as TimerMode) as real

Gets the value of the specified timer.

Arguments

$timerNum The timer to read.

$timerMode The mode to use when reading the timer.

Returns

The value of the specified timer.

## Random Number Generation

You can generate pseudo-random numbers in an AeroScript program. This capability can be useful for testing or simulation purposes. Each task uses a different pseudo-random number generator.

To use the random number generator, you must first provide a seed with the RandomSeed() function. Then every subsequent call to RandomNextInteger() or RandomNextReal() will return the next pseudo-random value.

- For RandomNextInteger(), the returned value is one of 32,768 unique values in the range of 0 to 32767.
- For RandomNextReal(), the returned value is one of 32,768 unique values in the range of 0.0 to 1.0.

function RandomSeed($seed as integer)

Seed the pseudo-random number generator.

Arguments

$seed The number used to initialize the pseudo-random number generator.

function RandomNextInteger() as integer

Generate a pseudo-random integer.

Returns

A pseudo-random integer in the range [0, 32767].

function RandomNextReal() as real

Generate a pseudo-random real.

Returns

A pseudo-random real, uniformly-distributed in the range [0.0, 1.0] among 32,768 unique values.

For any given seed, the pseudo-random number generator generates the same sequence of values. When you reset the controller, the controller reseeds the pseudo-random number generator with a seed of 1.