Biblioteka standardowa

Biblioteka standardowa Volang udostępnia wszechstronny zestaw wbudowanych funkcji, niezbędnych do modyfikacji tekstu, wykonywania operacji matematycznych oraz innych typowych zadań. Funkcje te są dostępne globalnie w każdym skrypcie.

String Operations

Ta sekcja opisuje funkcje służące do operacji na ciągach znaków.

str::len(text)

Calculates the number of characters in a given string.

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

Przykład użycia:

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

str::trim(text)

Usuwa wszystkie początkowe i końcowe białe znaki (spacje, tabulatory, znaki nowej linii) z ciągu znaków. Jest to niezbędne do oczyszczania danych wejściowych od użytkownika lub przetwarzania poleceń z systemów zewnętrznych, w których mogą występować nadmiarowe odstępy.

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

Przykład użycia:

// 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.

• Parametery
  • ...strings: Sekwencja argumentów tekstowych, które mają zostać połączone. Możesz przekazać dowolną liczbę argumentów, oddzielając je przecinkami. Można również podać pojedynczy argument – w takim przypadku funkcja zwróci go w niezmienionej formie.
• Returns
  • A new string consisting of all input strings appended in order.

Przykład użycia:

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.

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

Przykład użycia:

// 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)

Tworzy sformatowany ciąg znaków, zastępując symbole zastępcze {} w szablonie tekstową reprezentacją przekazanych argumentów. Funkcja przyjmuje zmienną liczbę argumentów różnych typów (ciągi znaków, wartości liczbowe i logiczne) i automatycznie konwertuje je na tekst przed wstawieniem. Zastępowanie odbywa się według kolejności: pierwszy symbol {} jest zastępowany pierwszym argumentem, drugi symbol {} drugim i tak dalej.

• Parametery
  • 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.

Przykład użycia:

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"

Array Operations

Time Operations

time::now()

Pobiera aktualny czas systemowy w formacie znacznika czasu Unix (Unix timestamp). Wartość ta reprezentuje liczbę sekund, które upłynęły od godziny 00:00:00 UTC 1 stycznia 1970 roku (tzw. epoka Uniksa).

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

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

Przykład użycia:

// 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)

Oblicza wartość bezwzględną liczby. Jeśli podana wartość jest ujemna, funkcja zwraca jej dodatni odpowiednik; jeśli jest dodatnia, zwraca ją w niezmienionej formie. Funkcja obsługuje zarówno liczby całkowite, jak i zmiennoprzecinkowe. Jeśli podana wartość jest ujemna, funkcja zwraca jej dodatni odpowiednik; jeśli jest dodatnia, zwraca ją w niezmienionej formie. Funkcja obsługuje zarówno liczby całkowite, jak i zmiennoprzecinkowe. This function supports both integers and float types.

Jest to szczególnie przydatne przy obliczaniu różnicy (tzw. delty) między dwoma odczytami czujników, bez konieczności sprawdzania, która wartość jest większa (np. w celu weryfikacji, czy temperatura zmieniła się o więcej niż 1 stopień w dowolnym kierunku).

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

Przykład użycia:

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) {
    ....
}