The Program Class

TODO(fairlight1337): Only list the members that are not listed on the Operators page.

class Program

A class holding the bytecode of a program that can be executed by the BEAST VM.

This is the main container class for program code that is executable by the BEAST Virtual Machine (for example using CpuVirtualMachine through a VmSession instance). It allows to add any available operator through a well-defined interface. The program has a constant size mode and a growing mode, depending on whether it was initialized with a maximum size. In constant size mode, no operator code can be added beyond the constructor-defined byte limit. In growing mode, the program size is virtually unlimited (depending on the available host memory). The program class also allows BEAST Virtual Machine instances to read individual parts and get general information about the program.

If any error arises during program definition (e.g., operands are inserted beyond a constant size limit), an exception is thrown.

Author
Jan Winkler
Date
2023-01-11

Public Types

enum VariableType

Enumeration of known variable types.

Variables that can be used by a program must be of one of these defined types. When a variable is declared in a program, the type needs to be passed in. A variable cannot be re-declared with a new type unless it is undeclared first.

Values:

Int32 = 0

A four byte signed integer type.

Link = 1

A link to another variable (resolved when the variable content is accessed)

Public Functions

Program()

Growing program constructor.

The default setting is to make programs gow dynamically.

Program(std::vector<unsigned char> data)

Predefined bytecode program constructor.

This constructor initializes the program with a predefined bytecode vector. The program is defined as constant size, with the size limit being set to the size of the passed in bytecode vector.

Parameters
  • data: The bytecode data to initialize the program with.

getSize() const

Return the current size of the program in bytes.

For constant size programs this returns the defined maximum size in bytes, for dynamically growing programs it returns the actually used space of the operands added so far.

Return
The size of the program in bytes.

getData4(int32_t offset)

Return the next 4 byte batch starting from an offset.

Returns the next 4 bytes from the program, starting at the defined offset. The value is returned as a signed int32_t variable. If the end point of the returned region would be beyond the end of the program, an exception is thrown.

Return
A 4 byte variable containing the next 4 program bytes, starting from an offset.
See
getData2(), getData1()
Parameters
  • offset: The starting point from where to return the data.

getData2(int32_t offset)

Return the next 2 byte batch starting from an offset.

Returns the next 2 bytes from the program, starting at the defined offset. The value is returned as a signed int16_t variable. If the end point of the returned region would be beyond the end of the program, an exception is thrown.

Return
A 2 byte variable containing the next 2 program bytes, starting from an offset.
See
getData4(), getData1()
Parameters
  • offset: The starting point from where to return the data.

getData1(int32_t offset)

Return the next byte starting from an offset.

Returns the next byte from the program, starting at the defined offset. The value is returned as a signed int8_t variable. If the end point of the returned region would be beyond the end of the program, an exception is thrown.

Return
A 1 byte variable containing the next 1 program byte, starting from an offset.
See
getData4(), getData2()
Parameters
  • offset: The starting point from where to return the data.

getPointer() const

Returns the byte position after the last inserted operator.

When an operand is added to the program, its code will be places at the location of this pointer. The pointer variable will then be advanced by the amount of bytes inserted. Hence, the pointer returned here always points to the next byte that has not yet been populated. For constant size programs, this points to the byte after the defined available space once the program is fully populated.

Return
The current program population pointer position.

insertProgram(const Program &other)

Inserts another program into this instance.

Any other program instance (constant size or dynamically growing) can be added to a program. The code of the program to be inserted will be added at the current program population pointer position. In the case of constant size programs, if the program to be added is larger than the available space, an exception is thrown. For dynamically growing programs, the containing program will be expanded accordingly.

Parameters
  • other: The program to be inserted into the current instance.

getData() const

Returns this program’s byte code.

This function returns a constant reference to the actual byte code contained in this program instance. For constant size programs, the returned std::vector will contain the amount of bytes corresponding to the program’s initialized maximum size. For dynamically growing programs, the std::vector will be of the exact size of the bytes previously added.

Return
A constant std::vector containing the byte code of this instance.

noop()

Adds a NoOp operation to the program.

A NoOp operation performs no operation when executed.

Identified by OpCode::NoOp. Represented by 1 byte.

declareVariable(int32_t variable_index, VariableType variable_type)

Declares a variable at an index and assigns a type.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Declares a numerical variable index, alongside its designated type. A variable type can either be an actual value storage (of type VariableType::Int32) or a link to another variable index (of type VariableType::Link).

Identified by OpCode::DeclareVariable. Represented by 6 bytes.

See
undeclareVariable()
Parameters
  • variable_index: The index to declare the variable at.
  • variable_type: The designated type of the variable.

setVariable(int32_t variable_index, int32_t content, bool follow_links)

Sets the value of a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Sets the value of a variable at the given index to the value content. The variable index needs to be declared prior to this.

Identified by OpCode::SetVariable. Represented by 10 bytes.

See
declareVariable()
Parameters
  • variable_index: The index of the variable.
  • content: The value to assign to the variable.
  • follow_links: Whether to resolve variable links.

undeclareVariable(int32_t variable_index)

Removes a variable declaration at the given index.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The variable declared at the given index is undeclared. The index, type, and value are removed from the variable memory. If at that index no variable is declared, an exception is thrown.

Identified by OpCode::UndeclareVariable. Represented by 5 bytes.

See
declareVariable()
Parameters
  • variable_index: The index of the variable to undeclare.

addConstantToVariable(int32_t variable_index, int32_t constant, bool follow_links)

Adds a constant value to the value held in a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AddConstantToVariable. Represented by 8 bytes.

Parameters
  • variable_index: The index of the variable to add the constant to.
  • constant: The constant value to add to the variable value.
  • follow_links: Whether to resolve variable links.

addVariableToVariable(int32_t source_variable_index, bool follow_source_links, int32_t destination_variable_index, bool follow_destination_links)

Adds the value of one variable to that of another variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The contents of source_variable_index are added to the contents of destination_variable_index. The result is stored in destination_variable_index.

Identified by OpCode::AddVariableToVariable. Represented by 11 bytes.

Parameters
  • source_variable_index: The index of the source variable.
  • follow_source_links: Whether to resolve source variable links.
  • destination_variable_index: The index of the destination variable.
  • follow_destination_links: Whether to resolve destination variable links.

subtractConstantFromVariable(int32_t variable_index, int32_t constant, bool follow_links)

Subtract a constant value from the value held in a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::SubtractConstantFromVariable. Represented by 10 bytes.

Parameters
  • variable_index: The index of the variable to subtract the constant from.
  • constant: The constant value to subtract from the variable value.
  • follow_links: Whether to resolve variable links.

subtractVariableFromVariable(int32_t source_variable_index, bool follow_source_links, int32_t destination_variable_index, bool follow_destination_links)

Subtracts the value of one variable from that of another variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The contents of source_variable_index are subtracted from the contents of destination_variable_index. The result is stored in destination_variable_index.

Identified by OpCode::SubtractVariableFromVariable. Represented by 11 bytes.

Parameters
  • source_variable_index: The index of the variable.
  • follow_source_links: Whether to resolve variable links.
  • destination_variable_index: The index of the variable.
  • follow_destination_links: Whether to resolve variable links.

relativeJumpToVariableAddressIfVariableGreaterThanZero(int32_t variable_index, bool follow_links, int32_t relative_jump_address_variable_index, bool follow_addr_links)

Performs a relative jump to a variable address if a variable is > 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::RelativeJumpToVariableAddressIfVariableGt0. Represented by 11 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • relative_jump_address_variable_index: The variable containing the absolute jump address.
  • follow_addr_links: Whether to follow links in the address variable.

relativeJumpToVariableAddressIfVariableLessThanZero(int32_t variable_index, bool follow_links, int32_t relative_jump_address_variable_index, bool follow_addr_links)

Performs a relative jump to a variable address if a variable is < 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::RelativeJumpToVariableAddressIfVariableLt0. Represented by 11 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • relative_jump_address_variable_index: The variable containing the absolute jump address.
  • follow_addr_links: Whether to follow links in the address variable.

relativeJumpToVariableAddressIfVariableEqualsZero(int32_t variable_index, bool follow_links, int32_t relative_jump_address_variable_index, bool follow_addr_links)

Performs a relative jump to a variable address if a variable is = 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::RelativeJumpToVariableAddressIfVariableEq0. Represented by 11 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • relative_jump_address_variable_index: The variable containing the absolute jump address.
  • follow_addr_links: Whether to follow links in the address variable.

absoluteJumpToVariableAddressIfVariableGreaterThanZero(int32_t variable_index, bool follow_links, int32_t absolute_jump_address_variable_index, bool follow_addr_links)

Performs an absolute jump to a variable address if a variable is > 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AbsoluteJumpToVariableAddressIfVariableGt0. Represented by 11 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • absolute_jump_address_variable_index: The variable containing the absolute jump address.
  • follow_addr_links: Whether to follow links in the address variable.

absoluteJumpToVariableAddressIfVariableLessThanZero(int32_t variable_index, bool follow_links, int32_t absolute_jump_address_variable_index, bool follow_addr_links)

Performs an absolute jump to a variable address if a variable is < 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AbsoluteJumpToVariableAddressIfVariableLt0. Represented by 11 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • absolute_jump_address_variable_index: The variable containing the absolute jump address.
  • follow_addr_links: Whether to follow links in the address variable.

absoluteJumpToVariableAddressIfVariableEqualsZero(int32_t variable_index, bool follow_links, int32_t absolute_jump_address_variable_index, bool follow_addr_links)

Performs an absolute jump to a variable address if a variable is = 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AbsoluteJumpToVariableAddressIfVariableEq0. Represented by 11 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • absolute_jump_address_variable_index: The variable containing the absolute jump address.
  • follow_addr_links: Whether to follow links in the address variable.

relativeJumpToAddressIfVariableGreaterThanZero(int32_t variable_index, bool follow_links, int32_t relative_jump_address)

Performs a relative jump to a fixed address if a variable is > 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::RelativeJumpIfVariableGt0. Represented by 10 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • relative_jump_address: The relative address to jump to.

relativeJumpToAddressIfVariableLessThanZero(int32_t variable_index, bool follow_links, int32_t relative_jump_address)

Performs a relative jump to a fixed address if a variable is < 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::RelativeJumpIfVariableLt0. Represented by 10 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • relative_jump_address: The relative address to jump to.

relativeJumpToAddressIfVariableEqualsZero(int32_t variable_index, bool follow_links, int32_t relative_jump_address)

Performs a relative jump to a fixed address if a variable is = 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::RelativeJumpIfVariableEq0. Represented by 10 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • relative_jump_address: The relative address to jump to.

absoluteJumpToAddressIfVariableGreaterThanZero(int32_t variable_index, bool follow_links, int32_t absolute_jump_address)

Performs an absolute jump to a fixed address if a variable is > 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AbsoluteJumpIfVariableGt0. Represented by 10 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • absolute_jump_address: The absolute address to jump to.

absoluteJumpToAddressIfVariableLessThanZero(int32_t variable_index, bool follow_links, int32_t absolute_jump_address)

Performs an absolute jump to a fixed address if a variable is < 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AbsoluteJumpIfVariableLt0. Represented by 10 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • absolute_jump_address: The absolute address to jump to.

absoluteJumpToAddressIfVariableEqualsZero(int32_t variable_index, bool follow_links, int32_t absolute_jump_address)

Performs an absolute jump to a fixed address if a variable is = 0.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::AbsoluteJumpIfVariableEq0. Represented by 10 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • absolute_jump_address: The absolute address to jump to.

loadMemorySizeIntoVariable(int32_t variable_index, bool follow_links)

Loads the maximum number of VmSession variables into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::LoadMemorySizeIntoVariable. Represented by 6 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

checkIfVariableIsInput(int32_t source_variable_index, bool follow_source_links, int32_t destination_variable_index, bool follow_destination_links)

Check if a variable is defined as an input.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If the variable source_variable_index is defined as having the VariableIoBehavior::Input, set the value of the variable destination_variable_index to 0x1, else set it to 0x0.

Identified by OpCode::CheckIfVariableIsInput. Represented by 11 bytes.

Parameters
  • source_variable_index: The index of the source variable.
  • follow_source_links: Whether to resolve source variable links.
  • destination_variable_index: The index of the destination variable.
  • follow_destination_links: Whether to resolve destination variable links.

checkIfVariableIsOutput(int32_t source_variable_index, bool follow_source_links, int32_t destination_variable_index, bool follow_destination_links)

Check if a variable is defined as an output.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If the variable source_variable_index is defined as having the VariableIoBehavior::Output, set the value of the variable destination_variable_index to 0x1, else set it to 0x0.

Identified by OpCode::CheckIfVariableIsOutput. Represented by 11 bytes.

Parameters
  • source_variable_index: The index of the source variable.
  • follow_source_links: Whether to resolve source variable links.
  • destination_variable_index: The index of the destination variable.
  • follow_destination_links: Whether to resolve destination variable links.

loadInputCountIntoVariable(int32_t variable_index, bool follow_links)

Load the number of registered input variables into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::LoadInputCountIntoVariable. Represented by 6 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

loadOutputCountIntoVariable(int32_t variable_index, bool follow_links)

Load the number of registered output variables into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::LoadOutputCountIntoVariable. Represented by 6 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

loadCurrentAddressIntoVariable(int32_t variable_index, bool follow_links)

Load the current program execution pointer value into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::LoadCurrentAddressIntoVariable. Represented by 6 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

printVariable(int32_t variable_index, bool follow_links, bool as_char)

Print the value of a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The value stored in the variable variable_index will be printed. If as_char is true, then the variable’s least significant byte will be printed as an ASCII character instead.

Identified by OpCode::PrintVariable. Represented by 7 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • as_char: If true, print least significant byte as char.

setStringTableEntry(int32_t string_table_index, const std::string &string)

Set the content of an entry in the string table.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Sets the value that is stored for a specified entry in the string table.

Identified by OpCode::SetStringTableEntry. Represented by 7 + string length bytes.

Parameters
  • string_table_index: The string table index to set.
  • string: The content to store in the string table.

printStringFromStringTable(int32_t string_table_index)

Prints a string from the string table.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::PrintStringFromStringTable. Represented by 5 bytes.

Parameters
  • string_table_index: The string stored at this index will be printed.

loadStringTableLimitIntoVariable(int32_t variable_index, bool follow_links)

Loads the maximum number of items in the string table into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

This is equivalent to the number of possible string items an associated VmSession provides.

Identified by OpCode::LoadStringTableLimitIntoVariable. Represented by 6 bytes.

Parameters
  • variable_index: The index of the variable to load the limit into.
  • follow_links: Whether to resolve variable links.

terminate(int8_t return_code)

Immediately terminates the program.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

No further program operators will be executes. The program’s return code will be set to the value of the parameter return_code.

Identified by OpCode::Terminate. Represented by 2 bytes.

Parameters
  • return_code: The return code of the program after termination.

copyVariable(int32_t source_variable_index, bool follow_source_links, int32_t destination_variable_index, bool follow_destination_links)

Copies the value of one variable into another.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::CopyVariable. Represented by 11 bytes.

Parameters
  • source_variable_index: The index of the source variable.
  • follow_source_links: Whether to resolve source variable links.
  • destination_variable_index: The index of the destination variable.
  • follow_destination_links: Whether to resolve destination variable links.

loadStringItemLengthIntoVariable(int32_t string_table_index, int32_t variable_index, bool follow_links)

Load the actual length of a string table item into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::LoadStringItemLengthIntoVariable. Represented by 10 bytes.

Parameters
  • string_table_index: The string table item’s index to read the length from.
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

checkIfInputWasSet(int32_t variable_index, bool follow_links, int32_t destination_variable_index, bool follow_destination_links)

Determine whether an input variable was written to since the last read operation.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If since the last read operation the given variable at variable_index was written to, store the value 0x1 in the variable at destination_variable_index. Store 0x0 otherwise.

For details on I/O behaviors, also see VmSession::setVariableBehavior.

Identified by OpCode::CheckIfInputWasSet. Represented by 11 bytes.

See
VmSession::setVariableBehavior()
Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • destination_variable_index: The index of the destination variable.
  • follow_destination_links: Whether to resolve destination variable links.

loadStringTableItemLengthLimitIntoVariable(int32_t variable_index, bool follow_links)

Load the maximum length of string table items into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

This is the limit imposed on the Program by the VmSession associated to it during execution.

Identified by OpCode::LoadStringTableItemLengthLimitIntoVariable. Represented by 6 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

loadRandomValueIntoVariable(int32_t variable_index, bool follow_links)

Stores a random value into the given variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

A random numeric value will be stored in the variable variable_index. It is drawn from the full range of the data type int32_t.

Identified by OpCode::LoadRandomValueIntoVariable. Represented by 6 bytes.

Parameters
  • variable_index: The index of the variable to store the random value in.
  • follow_links: Whether to resolve variable links.

unconditionalJumpToAbsoluteAddress(int32_t addr)

Jumps to the given absolute address.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::UnconditionalJumpToAbsoluteAddress. Represented by 5 bytes.

Parameters
  • addr: The absolute address to jump to.

unconditionalJumpToAbsoluteVariableAddress(int32_t variable_index, bool follow_links)

Jumps to an absolute address stored in a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::UnconditionalJumpToAbsoluteVariableAddress. Represented by 6 bytes.

Parameters
  • variable_index: The index of the variable holding the absolute address to jump to.
  • follow_links: Whether to resolve variable links.

unconditionalJumpToRelativeAddress(int32_t addr)

Jumps to the given relative address.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::UnconditionalJumpToRelativeAddress. Represented by 5 bytes.

Parameters
  • addr: The relativeaddress to jump to.

unconditionalJumpToRelativeVariableAddress(int32_t variable_index, bool follow_links)

Jumps to a relative address stored in a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::UnconditionalJumpToRelativeVariableAddress. Represented by 6 bytes.

Parameters
  • variable_index: The index of the variable holding the relative address to jump to.
  • follow_links: Whether to resolve variable links.

loadStringItemIntoVariables(int32_t string_table_index, int32_t start_variable_index, bool follow_links)

Loads an item from the string table into consecutive variables.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The item at the string table index string_table_index will be stored in the variables starting at index start_variable_index, consecutively. Each variable stores the character value from the respective string table item. Example:

String table item: Entry

  • start_variable_index + 0 = E
  • start_variable_index + 1 = n
  • start_variable_index + 2 = t
  • start_variable_index + 3 = r
  • start_variable_index + 4 = y

The follow_links parameter will be applied to every index separately.

Identified by OpCode::LoadStringItemIntoVariables. Represented by 10 bytes.

See
loadVariableStringItemLengthIntoVariable()
Parameters
  • string_table_index: The string table item to read character from.
  • start_variable_index: The index of the start variable.
  • follow_links: Whether to resolve variable links.

performSystemCall(int8_t major_code, int8_t minor_code, int32_t variable_index, bool follow_links)

Performs a system call according to its parameters.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Performs system calls for different purposes. The currently implemented set of functionalities and valid parameter ranges can be found in VmSession::performSystemCall.

Identified by OpCode::PerformSystemCall. Represented by 8 bytes.

See
VmSession::performSystemCall()
Parameters
  • major_code: The major code of the system call to perform
  • minor_code: The minor code of the system call to perform
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

bitShiftVariableLeft(int32_t variable_index, bool follow_links, int8_t places)

Bit-shift a variable to the left.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Bit-shifts the given variable by places bits to the left. The right side will be filled up with zero bits.

Identified by OpCode::BitShiftVariableLeft. Represented by 7 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • places: The amount of places to shift the variable to the left.

bitShiftVariableRight(int32_t variable_index, bool follow_links, int8_t places)

Bit-shift a variable to the right.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Bit-shifts the given variable by places bits to the right. The left side will be filled up with zero bits.

Identified by OpCode::BitShiftVariableRight. Represented by 7 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • places: The amount of places to shift the variable to the right.

bitWiseInvertVariable(int32_t variable_index, bool follow_links)

Bit-wise inverts the given variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::BitWiseInvertVariable. Represented by 5 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

bitWiseAndTwoVariables(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b)

Performs a bit-wise AND operation on two variables.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The result will be stored in variable_index_b.

Identified by OpCode::BitWiseAndTwoVariables. Represented by 11 bytes.

Parameters
  • variable_index_a: The index of the first variable.
  • follow_links_a: Whether to resolve first variable’s links.
  • variable_index_b: The index of the second variable.
  • follow_links_b: Whether to resolve second variable’s links.

bitWiseOrTwoVariables(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b)

Performs a bit-wise OR operation on two variables.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The result will be stored in variable_index_b.

Identified by OpCode::BitWiseOrTwoVariables. Represented by 11 bytes.

Parameters
  • variable_index_a: The index of the first variable.
  • follow_links_a: Whether to resolve first variable’s links.
  • variable_index_b: The index of the second variable.
  • follow_links_b: Whether to resolve second variable’s links.

bitWiseXorTwoVariables(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b)

Performs a bit-wise XOR operation on two variables.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The result will be stored in variable_index_b.

Identified by OpCode::BitWiseXorTwoVariables. Represented by 11 bytes.

Parameters
  • variable_index_a: The index of the first variable.
  • follow_links_a: Whether to resolve first variable’s links.
  • variable_index_b: The index of the second variable.
  • follow_links_b: Whether to resolve second variable’s links.

moduloVariableByConstant(int32_t variable_index, bool follow_links, int32_t modulo_constant)

Performs a constant modulo operation on a variable and stores the result.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The given constant will be modulo’ed onto the given variable. The result will be stored in the same variable.

variable = variable % constant

Identified by OpCode::ModuloVariableByConstant. Represented by 11 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • modulo_constant: The constant to modulo onto the variable.

moduloVariableByVariable(int32_t variable_index, bool follow_links, int32_t modulo_variable_index, bool modulo_follow_links)

Performs a variable modulo operation on a variable and stores the result.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

The modulo variable’s value will be modulo’ed onto the given variable. The result will be stored in the first variable.

variable = variable % modulo_variable

Identified by OpCode::ModuloVariableByVariable. Represented by 11 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • modulo_variable_index: The index of the modulo variable.
  • modulo_follow_links: Whether to resolve the modulo variable’s links.

rotateVariableLeft(int32_t variable_index, bool follow_links, int8_t places)

Bit-wise rotate the given variable to the left.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Negative values cause a rotation to the right.

Identified by OpCode::RotateVariableLeft. Represented by 7 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • places: How many bits to rotate the variable to the left (can be negative).

rotateVariableRight(int32_t variable_index, bool follow_links, int8_t places)

Bit-wise rotate the given variable to the left.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Negative values cause a rotation to the left.

Identified by OpCode::RotateVariableRight. Represented by 7 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • places: How many bits to rotate the variable to the right (can be negative).

pushVariableOnStack(int32_t stack_variable_index, bool follow_links_stack, int32_t variable_index, bool follow_links)

Pushes the content of a variable onto a stack.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

A stack is identified by a variable holding the current size of the stack, and a number of declared variables after it. This operator increases the current size of the stack by 1, and copies the value of the passed in variable into the variable index that is at stack_variable_index + previous_size + 1.

Identified by OpCode::PushVariableOnStack. Represented by 11 bytes.

See
pushConstantOnStack(), popVariableFromStack(), popTopItemFromStack(), checkIfStackIsEmpty()
Parameters
  • stack_variable_index: The index of the stack variable.
  • follow_links_stack: Whether to resolve the stack variable’s links.
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

pushConstantOnStack(int32_t stack_variable_index, bool follow_links_stack, int32_t constant)

Pushes a constant value onto a stack.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Similar to pushVariableOnStack, but pushes a constant value passed to this operand onto the stack rather than reading the value from a variable.

Identified by OpCode::PushConstantOnStack. Represented by 10 bytes.

See
pushVariableOnStack(), popVariableFromStack(), popTopItemFromStack(), checkIfStackIsEmpty()
Parameters
  • stack_variable_index: The index of the variable.
  • follow_links_stack: Whether to resolve variable links.
  • constant: tbd

popVariableFromStack(int32_t stack_variable_index, bool follow_links_stack, int32_t variable_index, bool follow_links)

Removes the top item from the stack and stores it in a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Removes the top item from the stack, reducing the stack size by 1. The value of the removed item will be stored in variable_index. Throws if the stack was empty before.

Identified by OpCode::PopVariableFromStack. Represented by 11 bytes.

See
pushVariableOnStack(), pushConstantOnStack(), popTopItemFromStack(), checkIfStackIsEmpty()
Parameters
  • stack_variable_index: The index of the variable.
  • follow_links_stack: Whether to resolve variable links.
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

popTopItemFromStack(int32_t stack_variable_index, bool follow_links_stack)

Removes the top item from the stack.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Effectively, the stack size will be reduced by 1. The top item will be discarded. Throws if the stack was empty before.

Identified by OpCode::PopTopItemFromStack. Represented by 6 bytes.

See
popVariableFromStack(), popVariableFromStack(), checkIfStackIsEmpty()
See
pushVariableOnStack(), pushConstantOnStack(), popVariableFromStack(), checkIfStackIsEmpty()
Parameters
  • stack_variable_index: The index of the variable.
  • follow_links_stack: Whether to resolve variable links.

checkIfStackIsEmpty(int32_t stack_variable_index, bool follow_links_stack, int32_t variable_index, bool follow_links)

Checks whether there are no items on a stack.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If the stack at variable stack_variable_index contains no items, the variable at variable_index will be set to 0x1, and 0x0 if there is at least one item on the stack.

Identified by OpCode::CheckIfStackIsEmpty. Represented by 11 bytes.

See
pushConstantOnStack(), pushVariableOnStack(), pushConstantOnStack(), popTopItemFromStack()
Parameters
  • stack_variable_index: The index of the variable.
  • follow_links_stack: Whether to resolve variable links.
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

swapVariables(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b)

Swaps the contents of two variables.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::SwapVariables. Represented by 11 bytes.

Parameters
  • variable_index_a: The index of the variable.
  • follow_links_a: Whether to resolve variable links.
  • variable_index_b: The index of the variable.
  • follow_links_b: Whether to resolve variable links.

setVariableStringTableEntry(int32_t variable_index, bool follow_links, const std::string &string)

Sets an entry in the string table at a variable index.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::SetVariableStringTableEntry. Represented by 8 + string length bytes.

See
setStringTableEntry()
Parameters
  • variable_index: The index of the variable to read the string table index from.
  • follow_links: Whether to resolve variable links.
  • string: The string to store in the string table

printVariableStringFromStringTable(int32_t variable_index, bool follow_links)

Prints an entry from the string table from a variable index.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::PrintVariableStringFromStringTable. Represented by 6 bytes.

See
printStringFromStringTable()
Parameters
  • variable_index: The index of the variable to read the string table index from.
  • follow_links: Whether to resolve variable links.

loadVariableStringItemLengthIntoVariable(int32_t string_item_variable_index, bool follow_links_string_item, int32_t variable_index, bool follow_links)

Loads the length of a variable string table index into a variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::LoadVariableStringItemLengthIntoVariable. Represented by 11 bytes.

Parameters
  • string_item_variable_index: The index of the variable to read the string table index from
  • follow_links_string_item: Whether to resolve the string table index variable’s links
  • variable_index: The index of the variable to store the length in
  • follow_links: Whether to resolve the target variable’s links

loadVariableStringItemIntoVariables(int32_t string_item_variable_index, bool follow_links_string_item, int32_t variable_index, bool follow_links)

Loads a variable item from the string table into consecutive variables.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

See loadStringItemLengthIntoVariable for details. The string table index is not fixed in this variant, but is read from the string_item_variable_index variable.

Identified by OpCode::LoadVariableStringItemIntoVariables. Represented by 11 bytes.

See
loadStringItemLengthIntoVariable()
Parameters
  • string_item_variable_index: The index of the variable.
  • follow_links_string_item: Whether to resolve variable links.
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

terminateWithVariableReturnCode(int32_t variable_index, bool follow_links)

Immediately terminates the program, returning a variable return code.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

No further program operators will be executes. The program’s return code will be set to the value of the value of the variable_index variable.

Identified by OpCode::TerminateWithVariableReturnCode. Represented by 6 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.

variableBitShiftVariableLeft(int32_t variable_index, bool follow_links, int32_t places_variable_index, bool follow_links_places)

Bit-shifts a variable to the left by a variable amount of places.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::VariableBitShiftVariableLeft. Represented by 11 bytes.

See
bitShiftVariableLeft()
Parameters
  • variable_index: The target variable that should be bit-shifted
  • follow_links: Whether to resolve the target variable’s links
  • places_variable_index: The variable holding the amount to shift by
  • follow_links_places: Whether to resolve the amount variable’s links

variableBitShiftVariableRight(int32_t variable_index, bool follow_links, int32_t places_variable_index, bool follow_links_places)

Bit-shifts a variable to the right by a variable amount of places.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::VariableBitShiftVariableRight. Represented by 11 bytes.

See
bitShiftVariableRight()
Parameters
  • variable_index: The target variable that should be bit-shifted
  • follow_links: Whether to resolve the target variable’s links
  • places_variable_index: The variable holding the amount to shift by
  • follow_links_places: Whether to resolve the amount variable’s links

variableRotateVariableLeft(int32_t variable_index, bool follow_links, int32_t places_variable_index, bool follow_links_places)

Rotates a variable to the left by a variable amount of places.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::VariableRotateVariableLeft. Represented by 11 bytes.

Parameters
  • variable_index: The target variable that should be rotated
  • follow_links: Whether to resolve the target variable’s links
  • places_variable_index: The variable holding the amount to rotate by
  • follow_links_places: Whether to resolve the amount variable’s links

variableRotateVariableRight(int32_t variable_index, bool follow_links, int32_t places_variable_index, bool follow_links_places)

Rotates a variable to the right by a variable amount of places.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

Identified by OpCode::VariableRotateVariableRight. Represented by 11 bytes.

Parameters
  • variable_index: The target variable that should be rotated
  • follow_links: Whether to resolve the target variable’s links
  • places_variable_index: The variable holding the amount to rotate by
  • follow_links_places: Whether to resolve the amount variable’s links

compareIfVariableGtConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)

Compares if a variable is > a given constant.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If the variable is greater than the given constant, the value 0x1 will be stored in the target variable, else 0x0 will be stored.

Identified by OpCode::CompareIfVariableGtConstant. Represented by 15 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • constant: The constant
  • target_variable_index: The index of the variable.
  • target_follow_links: Whether to resolve variable links.

compareIfVariableLtConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)

Compares if a variable is < a given constant.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If the variable is smaller than the given constant, the value 0x1 will be stored in the target variable, else 0x0 will be stored.

Identified by OpCode::CompareIfVariableLtConstant. Represented by 15 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • constant: The constant
  • target_variable_index: The index of the variable.
  • target_follow_links: Whether to resolve variable links.

compareIfVariableEqConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)

Compares if a variable is = a given constant.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If the variable is equal to the given constant, the value 0x1 will be stored in the target variable, else 0x0 will be stored.

Identified by OpCode::CompareIfVariableEqConstant. Represented by 15 bytes.

Parameters
  • variable_index: The index of the variable.
  • follow_links: Whether to resolve variable links.
  • constant: The constant
  • target_variable_index: The index of the variable.
  • target_follow_links: Whether to resolve variable links.

compareIfVariableGtVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)

Compares if a variable is > another variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If variable a is greater than variable b, the value 0x1 will be stored in the target variable, else 0x0 will be stored.

Identified by OpCode::CompareIfVariableGtVariable. Represented by 16 bytes.

Parameters
  • variable_index_a: The index of the variable.
  • follow_links_a: Whether to resolve variable links.
  • variable_index_b: The index of the variable.
  • follow_links_b: Whether to resolve variable links.
  • target_variable_index: The index of the variable.
  • target_follow_links: Whether to resolve variable links.

compareIfVariableLtVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)

Compares if a variable is < another variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If variable a is smaller than variable b, the value 0x1 will be stored in the target variable, else 0x0 will be stored.

Identified by OpCode::CompareIfVariableLtVariable. Represented by 16 bytes.

Parameters
  • variable_index_a: The index of the variable.
  • follow_links_a: Whether to resolve variable links.
  • variable_index_b: The index of the variable.
  • follow_links_b: Whether to resolve variable links.
  • target_variable_index: The index of the variable.
  • target_follow_links: Whether to resolve variable links.

compareIfVariableEqVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)

Compares if a variable is = another variable.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

If variable a is equal to variable b, the value 0x1 will be stored in the target variable, else 0x0 will be stored.

Identified by OpCode::CompareIfVariableEqVariable. Represented by 16 bytes.

Parameters
  • variable_index_a: The index of the variable.
  • follow_links_a: Whether to resolve variable links.
  • variable_index_b: The index of the variable.
  • follow_links_b: Whether to resolve variable links.
  • target_variable_index: The index of the variable.
  • target_follow_links: Whether to resolve variable links.

getMaxOfVariableAndConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)

Compare a variable to a constant and store the larger value.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

This operator compares the value stored in a variable against a constant. The larger value is stored in the target variable.

Identifier by OpCode::GetMaxOfVariableAndConstant. Represented by 15 bytes.

See
getMinOfVariableAndConstant(), getMaxOfVariableAndVariable(), getMinOfVariableAndVariable()
Parameters
  • variable_index: The index of the variable used for the comparison.
  • follow_links: Whether to follow variable links for the comparison variable.
  • constant: The constant to compare the variable against.
  • target_variable_index: The index of the variable to store the result in.
  • target_follow_links: whether to follow variable links for the target variable.

getMinOfVariableAndConstant(int32_t variable_index, bool follow_links, int32_t constant, int32_t target_variable_index, bool target_follow_links)

Compare a variable to a constant and store the smaller value.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

This operator compares the value stored in a variable against a constant. The smaller value is stored in the target variable.

Identifier by OpCode::GetMinOfVariableAndConstant. Represented by 15 bytes.

See
getMaxOfVariableAndConstant(), getMaxOfVariableAndVariable(), getMinOfVariableAndVariable()
Parameters
  • variable_index: The index of the variable used for the comparison.
  • follow_links: Whether to follow variable links for the comparison variable.
  • constant: The constant to compare the variable against.
  • target_variable_index: The index of the variable to store the result in.
  • target_follow_links: whether to follow variable links for the target variable.

getMaxOfVariableAndVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)

Compare a variable to another variable and store the larger value.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

This operator compares the value stored in one variable against the value stored in another variable. The larger value is stored in the target variable.

Identifier by OpCode::GetMaxOfVariableAndVariable. Represented by 16 bytes.

See
getMaxOfVariableAndConstant(), getMinOfVariableAndConstant(), getMinOfVariableAndVariable()
Parameters
  • variable_index_a: The index of the first variable used for the comparison.
  • follow_links_a: Whether to follow the first variable’s links for the comparison variable.
  • variable_index_b: The index of the second variable used for the comparison.
  • follow_links_b: Whether to follow the second variable’s links for the comparison variable.
  • target_variable_index: The index of the variable to store the result in.
  • target_follow_links: whether to follow variable links for the target variable.

getMinOfVariableAndVariable(int32_t variable_index_a, bool follow_links_a, int32_t variable_index_b, bool follow_links_b, int32_t target_variable_index, bool target_follow_links)

Compare a variable to another variable and store the smaller value.

This call adds the corresponding operator to the program. The operator’s action does not take immediate effect.

This operator compares the value stored in one variable against the value stored in another variable. The smaller value is stored in the target variable.

Identifier by OpCode::GetMinOfVariableAndVariable. Represented by 16 bytes.

See
getMaxOfVariableAndConstant(), getMinOfVariableAndConstant(), getMaxOfVariableAndVariable()
Parameters
  • variable_index_a: The index of the first variable used for the comparison.
  • follow_links_a: Whether to follow the first variable’s links for the comparison variable.
  • variable_index_b: The index of the second variable used for the comparison.
  • follow_links_b: Whether to follow the second variable’s links for the comparison variable.
  • target_variable_index: The index of the variable to store the result in.
  • target_follow_links: whether to follow variable links for the target variable.