Standard Library

The Volang Standard Library provides a comprehensive set of built-in functions essential for modifying text, performing mathematical operations, and other common operations. These functions are available globally in every script.

String Operations

This section describes functions that manipulate strings.

str::len(text)

Calculates the number of characters in a given string.

• Parameters
  • text (string): The input string to measure.
• Returns
  • An integer value representing the count of characters in the string.

Example:

// Check if the user PIN code has the required length
user_pin = "1234"
if (str::len(user_pin) == 4) {
    ...
}

str::trim(text)

Removes all leading and trailing whitespace characters (spaces, tabs, newlines) from the string. This is essential for cleaning up user input or parsing commands received from external systems where extra spacing might occur.

• Parameters
  • text (string): The input string to trim.
• Returns
  • A new text containing the text without surrounding whitespace.

Example:

// Clean up a command received from an external module
input = "  START  "
command = str::trim(input)

// Now the string is "START" and can be compared safely
if (command == "START") {
    ....
}

str::concat(…strings)

Concatenates (joins) two or more strings into a single string. This function is variadic, meaning it accepts a variable number of arguments, allowing you to build complex messages or commands dynamically.

• Parameters
  • ...strings: A sequence of string arguments to be joined together. You can pass as many arguments as needed, separated by commas. A single argument can be also specified, in which case this function returns the argument itself.
• Returns
  • A new string consisting of all input strings appended in order.

Example:

room = "Living Room"
temp = "22.5"

// Construct a full status message using multiple arguments
message = str::concat("Status: ", room, " is currently ", temp, "°C")

// Result: "Status: Living Room is currently 22.5°C"

str::number(text)

Parses a string argument and converts it into a numeric value. The function automatically detects the format: if the string contains a decimal point, it returns a float number, otherwise, it returns an integer number.

• Parameters
  • text: The string containing the number representation.
• Returns
  • A numeric value, either integer or float, depending on the input format.

Example:

// Case 1: Parsing an integer (e.g., brightness level)
brightness = str::number("80") // Returns Integer 80

// Case 2: Parsing a float (e.g., temperature)
temp_str = "21.5"
threshold = str::number(temp_str) // Returns Float 21.5
current_temp = 22

// Using the converted value in logic
if (current_temp > threshold) {
    ...
}

str::fmt(template, …args)

Constructs a formatted string by replacing placeholders {} within a template string with the string representation of the provided arguments. It accepts a variable number of arguments of different types (string, numeric and boolean values) and automatically converts them to text before insertion. The replacement is positional: the first {} is replaced by the first argument, the second {} by the second, and so on.

• Parameters
  • template: The format string containing curly brace placeholders {}.
  • ...args: A sequence of values to substitute into the placeholders. Supported types include numbers, strings, and boolean literals (true/false).
• Returns
  • A new string with all placeholders replaced by the corresponding values.

Example:

sensorName = "Kitchen_Main"
temp = 22.5
isActive = true

// Format a complex log message without manual concatenation
log = str::format("Sensor {} status: Active={}, Value={}°C", sensorName, isActive, temp)

// Result: "Sensor Kitchen_Main status: Active=true, Value=22.5°C"

str::split(text, separator)

Initializes a string splitting operation and creates an iterator state. This function does not perform the actual splitting immediately. Instead, it returns an opaque handle object that encapsulates the current position and logic required to traverse the string. This object must be passed to str::split_next or str::split_hash_next to retrieve the actual substrings one by one.

• Parameters
  • text: The source string to be split.
  • separator: The delimiter string that marks the boundaries between chunks.
• Returns
  • An opaque handle representing the active splitting session. You should not modify this object directly.

Example:

rawData = "sensor1;25.5;active"

// Initialize the splitter. 'iterator' now holds the state.
iterator = str::split(rawData, ";")

// The iterator is now ready to be consumed by split_next...

str::split_has_next(state)

Checks if there are more substrings waiting to be retrieved from the current splitting session. This function examines the opaque state object created by str::split. It does not modify the state or advance the iterator position; it only verifies availability. It is commonly used as the condition in a while loop to iterate through all parts of a string.

• Parameters
  • state: The opaque handle returned by str::split.
• Returns
  • true if at least one more substring is available; otherwise, returns false.

Example:

data = "RED,GREEN,BLUE"
iterator = str::split(data, ",")

// Loop as long as there are tokens left
while (str::split_has_next(iterator)) {
    ...
    // Safe to call split_next() here
    // color = str::split_next(iterator) 
}

str::split_next(state)

Extracts and returns the next substring from the split sequence and advances the iterator to the next position. This function consumes the current segment of the string identified by the opaque state. It is designed to be called sequentially until all parts of the string have been processed.

• Parameters
  • state: The opaque handle returned by str::split.
• Returns
  • The next segment of the original text.

Example:

// Scenario: Parsing a command string "SET_COLOR;255;0;0"
commandRaw = "SET_COLOR;255;0;0"
iter = str::split(commandRaw, ";")

// We know the format, so we can extract parts manually
if (str::split_has_next(iter)) {
    cmd = str::split_next(iter)   // "SET_COLOR"
    r = str::split_next(iter)     // "255"
    g = str::split_next(iter)     // "0"
    b = str::split_next(iter)     // "0"
    ...
}

Array Operations

Time Operations

time::now()

Retrieves the current system time as a Unix timestamp. The value represents the number of seconds elapsed since 00:00:00 UTC on January 1, 1970 (the Unix Epoch).

This function is essential for tracking when events occurred, calculating time elapsed between actions, or synchronizing with external servers.

• Parameters
  • None.
• Returns
  • An integer value representing the current Unix timestamp (in seconds).

Example:

// Store the time when the motion was last detected
last_motion_time = time::now()

// ... later in the code ...

// Check if more than 60 seconds have passed since the last motion
if (time::now() > last_motion_time + 60) {
   ...
}

Math Operations

math::abs(value)

Calculates the absolute value of a number. If the input is negative, it returns the positive equivalent; if the input is positive, it returns the value unchanged. This function supports both integers and float types.

It is particularly useful for calculating the difference (delta) between two sensor readings without worrying about which value is larger (e.g., checking if the temperature has changed by more than 1 degree in any direction).

• Parameters
  • value: The number to process.
• Returns
  • A numeric value representing the non-negative value of the input. The return type matches the input type.

Example:

target_temp = 21.0
current_temp = 19.5

// Calculate the difference ignoring direction
delta = math::abs(target_temp - current_temp)

// If the difference is significant (more than 0.5 degrees), take action
if (delta > 0.5) {
    ....
}

math::round(value)

Rounds the given floating-point number to the nearest integer value. Halfway cases (where the fractional part is exactly 0.5) are rounded away from zero.

• Parameters
  • value: The number to be rounded.
• Returns
  • An integer representing the nearest whole number.

Example:

// Example 1: Rounding sensor data for display
rawTemp = 21.7
displayTemp = math::round(rawTemp) // Returns 22

// Example 2: Halfway cases (rounding away from zero)
val1 = math::round(2.5)  // Returns 3
val2 = math::round(-2.5) // Returns -3

// Setting a dimmer level (must be an integer 0-100)
calculatedLevel = 55.4