Built-in Functions Reference

Complete reference for all built-in functions in CacaoLang.

Array Functions

len(array | string)

Returns the length of an array or string.

let numbers = [1, 2, 3, 4, 5];
print len(numbers);  // 5

let text = "Hello";
print len(text);  // 5

push(array, value)

Adds an element to the end of an array and returns the new array.

let numbers = [1, 2, 3];
numbers = push(numbers, 4);
print numbers;  // [1, 2, 3, 4]

pop(array)

Removes and returns the last element from an array.

let numbers = [1, 2, 3, 4];
let last = pop(numbers);
print last;  // 4

Higher-Order Functions

map(array, lambda)

Transforms each element of an array using a lambda function.

let numbers = [1, 2, 3, 4, 5];
let doubled = map(numbers, |x| => { return x * 2; });
print doubled;  // [2, 4, 6, 8, 10]

filter(array, lambda)

Keeps only elements that satisfy the lambda condition.

let numbers = [1, 2, 3, 4, 5, 6];
let evens = filter(numbers, |x| => { return x % 2 == 0; });
print evens;  // [2, 4, 6]

reduce(array, initial, lambda)

Combines array elements into a single value.

let numbers = [1, 2, 3, 4, 5];
let sum = reduce(numbers, 0, |acc, x| => { return acc + x; });
print sum;  // 15

Math Functions

sqrt(number)

Returns the square root of a number.

print sqrt(16);  // 4
print sqrt(25);  // 5

pow(base, exponent)

Raises base to the power of exponent.

print pow(2, 3);   // 8
print pow(10, 2);  // 100

abs(number)

Returns the absolute value.

print abs(-42);  // 42
print abs(15);   // 15

floor(number)

Rounds down to nearest integer.

print floor(3.7);  // 3
print floor(9.1);  // 9

ceil(number)

Rounds up to nearest integer.

print ceil(3.2);  // 4
print ceil(7.8);  // 8

round(number)

Rounds to nearest integer.

print round(3.5);  // 4
print round(3.4);  // 3

min(a, b)

Returns the smaller of two numbers.

print min(5, 3);   // 3
print min(-2, 10); // -2

max(a, b)

Returns the larger of two numbers.

print max(5, 3);  // 5
print max(-2, 10); // 10

Random Functions

random()

Returns a random float between 0 and 1.

let r = random();
print r;  // e.g., 0.742

random_int(min, max)

Returns a random integer between min and max (inclusive).

let dice = random_int(1, 6);
print dice;  // e.g., 4

String Functions

str(value)

Converts a value to a string.

let num = 42;
let text = str(num);
print text;  // "42"

uppercase(string)

Converts string to uppercase.

print uppercase("hello");  // HELLO

lowercase(string)

Converts string to lowercase.

print lowercase("WORLD");  // world

substr(string, start, length)

Extracts a substring.

let text = "Hello World";
print substr(text, 0, 5);  // Hello

split(string, delimiter)

Splits string into an array.

let sentence = "apple,banana,cherry";
let fruits = split(sentence, ",");
print fruits;  // ["apple", "banana", "cherry"]

join(array, separator)

Joins array elements into a string.

let words = ["Hello", "World"];
let sentence = join(words, " ");
print sentence;  // Hello World

Type Functions

typeof(value)

Returns the type of a value as a string.

print typeof(42);      // number
print typeof("hello"); // string
print typeof(true);    // bool
print typeof([1,2,3]); // array

int(value)

Converts to integer.

print int("42");   // 42
print int(3.7);    // 3
print int("3.14"); // 3

float(value)

Converts to floating-point number.

print float("3.14");  // 3.14
print float(42);      // 42.0

File I/O Functions

read_file(filename)

Reads entire file contents as a string.

let content = read_file("data.txt");
print content;

write_file(filename, content)

Writes string to file (overwrites existing).

write_file("output.txt", "Hello, World!");

append_file(filename, content)

Appends string to end of file.

append_file("log.txt", "New log entry\n");

file_exists(filename)

Checks if file exists.

if file_exists("config.txt") == true {
    print "Config found";
}

Input/Output Functions

input(prompt)

Reads a line of user input.

let name = input("Enter your name: ");
print "Hello, #{name}!";

print(value)

Prints value to console with newline.

print "Hello, World!";
print 42;
print [1, 2, 3];

Bitwise Functions

bitwise_and(a, b)

Performs bitwise AND operation.

let result = bitwise_and(12, 10);  // 8
print result;

bitwise_or(a, b)

Performs bitwise OR operation.

let result = bitwise_or(12, 10);  // 14
print result;

bitwise_xor(a, b)

Performs bitwise XOR operation.

let result = bitwise_xor(12, 10);  // 6
print result;

bitwise_not(a)

Performs bitwise NOT operation.

let result = bitwise_not(5);
print result;

shift_left(value, bits)

Shifts bits left.

let result = shift_left(5, 2);  // 20
print result;

shift_right(value, bits)

Shifts bits right.

let result = shift_right(20, 2);  // 5
print result;

count_bits(number)

Counts the number of set bits (1s).

let bits = count_bits(7);  // 3 (binary: 111)
print bits;

to_binary(number)

Converts number to binary string.

print to_binary(42);  // "101010"

to_hex(number)

Converts number to hexadecimal string.

print to_hex(255);  // "ff"

from_binary(string)

Converts binary string to number.

print from_binary("1010");  // 10

from_hex(string)

Converts hexadecimal string to number.

print from_hex("ff");  // 255