Standard Library

The standard library incorporates a set of predefined functions that are available to be used at any time in the program without the need to create or import them.

These functions allow performing common and repetitive tasks efficiently and simply, without having to write code from scratch. Additionally, being standardized, their compatibility and consistency between different systems and language versions is guaranteed.

These functions are optimized to provide high performance and easy usability, making them ideal for solving many common problems.

Input/Output

readLine

The standard function readLine allows getting user input in the form of a text string from the console. This function is useful for requesting information from the user at runtime.

print("Please enter your name: ")
name = readLine()
println("Hello " + name + ", welcome!")

In this example, the readLine function waits for the user to type a line of text and press Enter. The entered text is returned as a string.

print / println

The print and println functions display text on the console. The difference is that println adds a newline at the end.

print("Hello ")      // Does not add newline
println("World!")    // Adds newline at the end

Console

cls

The cls function clears the console, erasing all visible text.

cls()  // Clears the console screen

ink

The ink function sets the text color in the console.

ink(4)  // Sets text color to red
println("This text is red")
ink(7)  // Returns to default color (white/gray)

paper

The paper function sets the console background color.

paper(1)  // Sets background to blue
println("Text with blue background")
paper(0)  // Returns to black background

Time

pause

The standard function pause allows stopping program execution for a determined time, in milliseconds. This means that after calling the pause function with a specific number of milliseconds as a parameter, the program will stop for that amount of time before continuing with its normal execution.

println("This message will be displayed on screen.")
pause(3000)
println("This message will be displayed after 3 seconds.")

clock

The clock function indicates the clock time that has elapsed since VM initialization during the process start in milliseconds.

This value can be used to measure the execution time of a specific code section or to track the total execution time of a program.

var start, finish, total_time
start = clock()

// Algorithm code would go here

finish = clock()
total_time = finish - start
println("The algorithm took ", total_time, " milliseconds")

Type Conversion

chr

The chr function in JARU is used to convert an integer to an ASCII character. For example, chr(65) will return the character 'A'. It's a useful function for handling characters and text strings in the language.

var letter = chr(65)
println(letter)  // Prints: A

var newline = chr(10)
print("Line 1" + newline + "Line 2")

int

The int function in JARU is a data type conversion function that allows converting a decimal number to an integer. This function rounds down the decimal value and returns an integer.

var decimal = 5.7
var integer = int(decimal)
println(integer)  // Prints: 5

// Also works with booleans
println(int(true))   // Prints: 1
println(int(false))  // Prints: 0

float

The float function converts a number or a string representing a number to a floating-point number (float type). It can be used to convert integers to floating-point numbers.

var integer = 10
var decimal = float(integer)
println(decimal)  // Prints: 10.0

// Useful for operations requiring decimal precision
var result = float(5) / float(2)
println(result)  // Prints: 2.5

Random Numbers

randomize

The randomize function in JARU is used to initialize the platform's random number generator with a specific initial value or seed. This ensures that random numbers generated in a later program execution are the same as those generated in a previous execution. This is useful when you want to perform a simulation or a game that requires random numbers and you want the results to be identical each time it runs.

randomize(12345)  // Initialize with seed 12345

// Now random() will generate the same sequence each time
println(random(100))  // Will always give the same result with the same seed

random

Function that generates random numbers. You can use this function to generate a random number within a specific range:

// Generate random 32-bit integer
random()

// Generate random integer between 0 and 10 inclusive
random(10)

// Generate random integer between 100 and 200 inclusive
random(100, 200)

Also works with floating-point numbers:

// Generate random float between 0.0 and 1.0
random(0.0, 1.0)

// Generate random float between -10.5 and 10.5
random(-10.5, 10.5)

Mathematical Functions

abs

The abs function returns the absolute value of a number. The absolute value of a number is its value without sign, regardless of whether it's negative or positive.

println(abs(-5))    // Prints: 5
println(abs(8))     // Prints: 8
println(abs(-3.14)) // Prints: 3.14

round

Takes a number as input and returns the rounded value of that number to its nearest integer. If the number has a decimal equal to or greater than 0.5, it will be rounded to the next integer. Otherwise, it will be rounded to the previous integer.

var number = 3.14159265
var rounded_number = round(number)
println(rounded_number)  // Output: 3

println(round(3.5))   // Output: 4
println(round(3.49))  // Output: 3
println(round(-2.5))  // Output: -2

sqrt

A mathematical function that takes a number as input and returns its square root, which is a positive number. The square root is a number that, when multiplied by itself, produces the original number.

var x = 9
var result = sqrt(x)
println("The square root of ", x, " is ", result)  // Output: 3

println(sqrt(16))   // Output: 4.0
println(sqrt(2))    // Output: 1.4142135623730951

vlenght

The vlenght function calculates the length (magnitude) of a 2D vector given its X and Y components. It uses the Pythagorean theorem: √(x² + y²).

var length = vlenght(3, 4)
println(length)  // Output: 5.0

// Useful for calculating distances
var distance = vlenght(10.5, 20.3)
println("Distance: ", distance)

Utilities

len

The len function in JARU returns the length of a character string, a list, or a map.

// With strings
var string = "Hello world"
println(len(string))  // Prints: 11

// With lists
var list = [1, 2, 3, 4, 5]
println(len(list))  // Prints: 5

// With maps
var map = {"a": 1, "b": 2, "c": 3}
println(len(map))  // Prints: 3

System and Memory

memUse

Function that returns the amount of RAM memory being used in the JARU Virtual Machine (VM) at that moment. This information can be useful for monitoring resource usage and optimizing program performance.

var memory_used = memUse()
println("Memory used: ", memory_used, " bytes")

memFree

Function that returns the amount of free RAM memory available. This function is especially useful on devices with limited resources like the ESP32.

var free_memory = memFree()
println("Free memory: ", free_memory, " bytes")

Note

On Windows VM and Emscripten, memFree() returns 0 since there's no standard way to get system free memory. On ESP32, it returns the actual free heap size.

platform

The platform function returns an integer identifying the platform where the VM is running.

Value	Platform	Constant
0	Unknown platform	—
1	ESP32	HW_ESP32
2	ESP32-S3	HW_ESP32S3
3	Reserved	—
4	Windows (SDL2)	HW_WIN32
5	Web (Emscripten)	HW_WEB
6	ESP32-P4	HW_ESP32P4

Rather than comparing against the raw number, use the constants: they read better and they protect you if new platforms are added later.

var plat = platform()

if (plat == HW_ESP32 or plat == HW_ESP32S3 or plat == HW_ESP32P4) then
    println("Running on an ESP32")
elsif (plat == HW_WIN32) then
    println("Running on Windows")
elsif (plat == HW_WEB) then
    println("Running in web browser")
else
    println("Unknown platform")
end

Note

Value 3 is reserved. It belonged to the old RISC-V VM for the K210 (Kendryte/Maixduino), which was retired when that chip was discontinued. It will not be reused for any new platform, so no program can ever receive that value. The HW_RISCV constant that named it no longer exists: if your code used it, replace it with whichever check applies. The RISC-V platform JARU supports today is the ESP32-P4 (HW_ESP32P4).

vmerror

The vmerror function returns the code of the last error that occurred during JARU bytecode execution. After calling this function, the error value is reset to 0 (no error).

// Perform some operation that could fail
var result = someOperation()

var error = vmerror()
if (error != 0) then
    println("An error occurred with code: ", error)
else
    println("Operation successful")
end

Base64 Encoding

encode64

The encode64 function encodes a text string to Base64 format. It's useful for transmitting binary data in text formats or for encoding credentials.

var text = "Hello World"
var encoded = encode64(text)
println(encoded)  // Output: SGVsbG8gV29ybGQ=

b64Decode

The decode64 function decodes a Base64 format string to its original value.

var encoded = "SGVsbG8gV29ybGQ="
var decoded = decode64(encoded)
println(decoded)  // Output: Hello World

Common Usage

Base64 is very useful for sending data through protocols that only support text, such as HTTP or MQTT.

// Example: Encode sensor data to send via MQTT
var data = "temperature:25.5,humidity:60"
var payload = encode64(data)
MQTT.publish("sensors/data", payload)