Skip to main content
  • KSP Reference Manual
  • Arithmetic Commands & Operators

Arithmetic Commands & Operators

Basic Operators

The following operators work on both integers and real numbers.

x := y

Assignment (the value of y is assigned to x).

x + y

Addition.

x - y

Subtraction.

x * y

Multiplication.

x / y

Division.

-x

Negative value.

abs(x)

Absolute value.

signbit(x)

Sign bit (returns 1 if the number is negative, 0 otherwise).

sgn(x)

Signum function (returns -1 if the number is negative, 0 if it's zero, 1 if it's positive).

Integer Number Commands

The following commands and operators can only be performed on integer variables and values.

inc(x)

Increments an expression by 1 (x := x + 1).

dec(x)

Decrements an expression by 1 (x := x – 1).

x mod y

Modulo operator. Returns the remainder after integer division.

e.g. 13 mod 8 will return 5.

Real Number Commands

The following commands can only be performed on real numbers.

x mod y

Modulo operator. Returns the remainder after division.

e.g. 4.5 mod 2.0 returns the value 0.5.

exp(x)

Exponential function (returns the value of ex).

exp2(x)

Binary exponential function (returns the value of 2x).

log(x)

Natural logarithmic function (base e).

log2(x)

Binary logarithmic function (base 2).

log10(x)

Common logarithmic function (base 10).

pow(x, y)

Power function (returns the value of xy).

sqrt(x)

Square root function.

cbrt(x)

Cube root function.

Rounding Commands

Rounding commands can only be performed on real numbers.

ceil(x)

Ceiling (round up).

ceil(2.3) = 3.0

floor(x)

Floor (round down).

floor(2.8) = 2.0

round(x)

Round (round to nearest).

round(2.3) = 2.0

round(2.8) = 3.0

Trigonometric Commands

Trigonometric commands can only be performed on real numbers.

cos(x)

Cosine function.

sin(x)

Sine function.

tan(x)

Tangent function.

acos(x)

Arccosine (inverse cosine) function.

asin(x)

Arcsine (inverse sine) function.

atan(x)

Arctangent (inverse tangent) function.

Bitwise Operators

The following bitwise operators can be used:

x .and. y

Bitwise AND.

x .or. y

Bitwise OR.

x .xor. y

Bitwise XOR.

.not. x

Bitwise NOT (negation).

sh_left(<expression>, <shift-bits>)

Shifts the bits in <expression> by the amount of <shift-bits> to the left. Effectively multiplies the expression by 2.

sh_right(<expression>, <shift-bits>)

Shifts the bits in <expression> by the amount of <shift-bits> to the right. Effectively divides the expression by 2.

random()

random(<min>, <max>)

Generates a random integer between (and including) <min> and <max>.

Examples

on init
    declare $rnd_amt
    declare $new_vel
end on

on note
    $rnd_amt := $EVENT_VELOCITY * 10 / 100
    $new_vel := random($EVENT_VELOCITY - $rnd_amt, $EVENT_VELOCITY + $rnd_amt)

    { mirror invalid velocity values into the allowed velocity range }
    if ($new_vel > 127)
        $new_vel := 127 - ($new_vel mod 127)
    end if

    if ($new_vel < 1)
        $new_vel := 1 + abs($new_vel)
    end if

    change_velo($EVENT_ID, $new_vel)
end on

Randomly changing velocities by ±10 percent.

real()

real(<integer-value>)

Converts an integer value into a real number.

Examples

on init
    declare ~velocity_disp
end on

on note
    ~velocity_disp := real($EVENT_VELOCITY) / 127.0
    message(~velocity_disp)
end on

Displays the event velocity in the range from 0.0 to 1.0.

See Also

int()

int()

int(<real-value>)

Converts a real number into an integer.

Remarks

  • Using this command without any rounding function will cause the real value to be truncated, so performing this function with real values 2.2 and 2.8 will both return an integer value of 2

  • Be aware that this command reduces precision from 64-bit to 32-bit, which means that valid real numbers outside of 32-bit signed integer range (-2147483648 ... 2147483647) will not be properly converted, since they end up in overflow.

Examples

on init
    declare $test_int
    declare ~test_real := 2.8

    $test_int := int(~test_real)
    message($test_int)
end on

Converting a variable from real to integer and then displaying it.

See Also

real()

Rounding Commands: ceil(), floor(), round()

msb()

msb(<value>)

Returns the most significant byte portion of a 14-bit value.

Examples

on rpn
    message(msb($RPN_VALUE))
end on

Commonly used when working with RPN and NRPN messages.

on init
    declare ui_value_edit $Value (0, 16383, 1)
end on

on ui_control ($Value)
    message("MSB: " & msb($Value) & " - LSB: " & lsb($Value))
end on

Understanding MSB and LSB.

See Also

lsb()

Events and MIDI: $RPN_ADDRESS, $RPN_VALUE

lsb()

lsb(<value>)

Returns the least significant byte portion of a 14-bit value.

Examples

on rpn
    message(lsb($RPN_VALUE))
end on

Commonly used when working with RPN and NRPN messages.

on init
    declare ui_value_edit $Value (0, 16383, 1)
end on

on ui_control ($Value)
    message("MSB: " & msb($Value) & " - LSB: " & lsb($Value))
end on

Understanding MSB and LSB.

See Also

msb()

Events and MIDI: $RPN_ADDRESS, $RPN_VALUE