Merge pull request #20 from EpitechPGE3-2025/dev/std-lib

Dev/std lib

Author: lg-epitech

docs/STDLIB.md

@@ -9,8 +9,11 @@ stdlib/
   std/
     core.top
     string.top
+    math.top
     collections/
       list.top
+      aliases.top
+      functional.top
 ```
 
 ### std.core
@@ -37,7 +40,35 @@ Utilities layered on top of the VM's native list support (`VList`, `IListGet`, `
 | `list_concat` | Delegates to the runtime concatenation primitive. |
 | `list_single` | Creates a one-element list. |
 
-At this stage higher-order helpers (`map`, `filter`, …) are earmarked for a future iteration once the parser grows richer list syntax.
+### std.collections.aliases
+
+Convenient short aliases for common list operations:
+
+| Symbol | Description |
+|--------|-------------|
+| `length(lst)` | Alias for `__list_length`. Returns the number of elements in a list. |
+| `head(lst)` | Alias for safe first element access. Returns `nil` if list is empty. |
+| `tail(lst)` | Returns all elements except the first. Returns `[]` if list is empty or has one element. |
+| `concat(left, right)` | Alias for `__list_append`. Concatenates two lists. |
+| `last(lst)` | Alias for safe last element access. Returns `nil` if list is empty. |
+
+### std.collections.functional
+
+Higher-order list functions for functional programming:
+
+| Symbol | Description |
+|--------|-------------|
+| `fold(lst, init, func)` | Reduces a list to a single value using an accumulator function. Left fold. |
+| `map(lst, func)` | Transforms each element of a list using the provided function. |
+| `filter(lst, predicate)` | Returns a new list containing only elements that satisfy the predicate. |
+| `reverse(lst)` | Returns a new list with elements in reverse order. |
+| `take(lst, n)` | Returns the first `n` elements of the list. |
+| `drop(lst, n)` | Returns all elements after dropping the first `n`. |
+| `find(lst, predicate)` | Returns the first element matching the predicate, or `nil` if none found. |
+| `contains(lst, value)` | Returns `true` if the list contains the value, `false` otherwise. |
+| `index_of(lst, value)` | Returns the index of the first occurrence of value, or `-1` if not found. |
+| `range(start, end)` | Generates a list of integers from `start` to `end` (inclusive). |
+| `zip(lst1, lst2)` | Zips two lists into a list of pairs up to the shorter length. |
 
 ### std.string
 
@@ -48,6 +79,74 @@ Convenience wrappers around the existing string builtins:
 | `string_is_empty` | Checks whether a string has length zero. |
 | `string_starts_with` / `string_ends_with` | Prefix and suffix checks expressed via `__substring`. |
 
+## Built-in Functions
+
+The Topineur runtime provides several built-in functions implemented in Haskell:
+
+### Math Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `abs(x)` | `Int\|Float -> Int\|Float` | Returns the absolute value. Preserves input type. |
+| `sqrt(x)` | `Int\|Float -> Float` | Returns the square root. Always returns Float. |
+| `pow(a, b)` | `Int\|Float, Int\|Float -> Float` | Exponentiation. Returns Float. |
+| `floor(x)` | `Int\|Float -> Int` | Largest integer not greater than `x`. For Int, passthrough. |
+| `ceil(x)` | `Int\|Float -> Int` | Smallest integer not less than `x`. For Int, passthrough. |
+| `round(x)` | `Int\|Float -> Int` | Rounds to the nearest integer (banker's rounding as in Haskell). For Int, passthrough. |
+| `sin(x)` | `Int\|Float -> Float` | Sine of `x` in radians. |
+| `cos(x)` | `Int\|Float -> Float` | Cosine of `x` in radians. |
+| `tan(x)` | `Int\|Float -> Float` | Tangent of `x` in radians. |
+| `asin(x)` | `Int\|Float -> Float` | Arc-sine in radians. Domain [-1,1]. |
+| `acos(x)` | `Int\|Float -> Float` | Arc-cosine in radians. Domain [-1,1]. |
+| `atan(x)` | `Int\|Float -> Float` | Arc-tangent in radians. |
+| `atan2(y, x)` | `Int\|Float, Int\|Float -> Float` | Arc-tangent of `y/x` accounting for quadrant, in radians. |
+| `pi` | `Float` | π constant (3.14159…). |
+| `e` | `Float` | Euler's number e (2.71828…). |
+
+### std.math (Topineur)
+
+Convenience numeric utilities implemented in Topineur:
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `min(a, b)` | `Int\|Float -> Int\|Float` | Returns the smaller of two numbers. |
+| `max(a, b)` | `Int\|Float -> Int\|Float` | Returns the larger of two numbers. |
+| `clamp(x, lo, hi)` | `Int\|Float -> Int\|Float` | Clamps `x` into `[lo, hi]` using `max(lo, min(x, hi))`. |
+| `sign(x)` | `Int\|Float -> Int` | Returns `-1`, `0`, or `1`. |
+
+### Type Conversions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `int(x)` | `Int\|Float\|String -> Int` | Converts to Int. Truncates floats towards zero. |
+| `float(x)` | `Int\|Float\|String -> Float` | Converts to Float. |
+| `show(x)` | `Any -> String` | Converts any value to its string representation. |
+
+**Conversion behaviors:**
+- `int(3.9)` → `3` (truncate towards zero)
+- `int(-3.9)` → `-3` (truncate towards zero)
+- `float(42)` → `42.0`
+- `abs(-5)` → `5` (preserves Int type)
+- `abs(-3.14)` → `3.14` (preserves Float type)
+- `sqrt(16)` → `4.0` (always Float)
+
+### List Primitives
+
+| Function | Description |
+|----------|-------------|
+| `__list_length(lst)` | Runtime primitive for list length. |
+| `__list_get(lst, idx)` | Runtime primitive for element access by index. |
+| `__list_append(left, right)` | Runtime primitive for list concatenation. |
+| `__list_single(value)` | Runtime primitive to create a single-element list. |
+
+### String Primitives
+
+| Function | Description |
+|----------|-------------|
+| `__string_length(str)` | Runtime primitive for string length. |
+| `__string_append(s1, s2)` | Runtime primitive for string concatenation. |
+| `__substring(str, start, end)` | Runtime primitive to extract substring. |
+
 ## Using the Stdlib
 
 ```topineur

examples/topineur/math-builtins.top

@@ -0,0 +1,110 @@
+package test_math_builtins
+
+|- Test abs function
+def test_abs(): Int {
+  println("Testing abs():")
+  
+  |- Test with positive integer
+  let abs_pos = abs(42)
+  println("  abs(42) = " ++ show(abs_pos))
+  
+  |- Test with negative integer
+  let abs_neg = abs(-42)
+  println("  abs(-42) = " ++ show(abs_neg))
+  
+  |- Test with zero
+  let abs_zero = abs(0)
+  println("  abs(0) = " ++ show(abs_zero))
+  
+  |- Test with positive float
+  let abs_float_pos = abs(3.14)
+  println("  abs(3.14) = " ++ show(abs_float_pos))
+  
+  |- Test with negative float
+  let abs_float_neg = abs(-3.14)
+  println("  abs(-3.14) = " ++ show(abs_float_neg))
+  
+  top 0
+}
+
+|- Test sqrt function
+def test_sqrt(): Int {
+  println("")
+  println("Testing sqrt():")
+  
+  |- Test with perfect square
+  let sqrt_16 = sqrt(16.0)
+  println("  sqrt(16.0) = " ++ show(sqrt_16))
+  
+  |- Test with integer input (should convert to float)
+  let sqrt_25 = sqrt(25)
+  println("  sqrt(25) = " ++ show(sqrt_25))
+  
+  |- Test with non-perfect square
+  let sqrt_2 = sqrt(2.0)
+  println("  sqrt(2.0) = " ++ show(sqrt_2))
+  
+  |- Test with zero
+  let sqrt_zero = sqrt(0.0)
+  println("  sqrt(0.0) = " ++ show(sqrt_zero))
+  
+  top 0
+}
+
+|- Test int function
+def test_int(): Int {
+  println("")
+  println("Testing int():")
+  
+  |- Test with integer input (should return same)
+  let int_42 = int(42)
+  println("  int(42) = " ++ show(int_42))
+  
+  |- Test truncation (positive)
+  let int_pos = int(3.9)
+  println("  int(3.9) = " ++ show(int_pos) ++ " (should be 3, truncate towards zero)")
+  
+  |- Test truncation (negative)
+  let int_neg = int(-3.9)
+  println("  int(-3.9) = " ++ show(int_neg) ++ " (should be -3, truncate towards zero)")
+  
+  |- Test with exact float
+  let int_exact = int(5.0)
+  println("  int(5.0) = " ++ show(int_exact))
+  
+  top 0
+}
+
+|- Test float function
+def test_float(): Int {
+  println("")
+  println("Testing float():")
+  
+  |- Test with float input (should return same)
+  let float_pi = float(3.14)
+  println("  float(3.14) = " ++ show(float_pi))
+  
+  |- Test with integer input
+  let float_42 = float(42)
+  println("  float(42) = " ++ show(float_42) ++ " (should be 42.0)")
+  
+  |- Test with zero
+  let float_zero = float(0)
+  println("  float(0) = " ++ show(float_zero))
+  
+  top 0
+}
+
+def main(): Int {
+  println("=== Math Builtins Test Suite ===")
+  println("")
+  
+  test_abs()
+  test_sqrt()
+  test_int()
+  test_float()
+  
+  println("")
+  println("=== All Tests Complete ===")
+  top 0
+}

examples/topineur/test-adv-math.top

@@ -0,0 +1,59 @@
+package test_adv_math
+
+|- Advanced math builtins tests: pow, floor, ceil, round, trig, constants
+
+def test_pow(): Int {
+    println("Testing pow():")
+    println("  pow(2, 3) = " ++ show(pow(2, 3)) ++ " (should be 8.0)")
+    println("  pow(9, 0.5) = " ++ show(pow(9, 0.5)) ++ " (should be 3.0)")
+    println("  pow(2.5, 2) = " ++ show(pow(2.5, 2)) ++ " (should be 6.25)")
+    top 0
+}
+
+def test_rounding(): Int {
+    println("")
+    println("Testing floor/ceil/round:")
+    println("  floor(3.7) = " ++ show(floor(3.7)) ++ " (should be 3)")
+    println("  ceil(3.1) = " ++ show(ceil(3.1)) ++ " (should be 4)")
+    println("  round(3.5) = " ++ show(round(3.5)) ++ " (Haskell rounds to 4)")
+    println("  round(2.5) = " ++ show(round(2.5)) ++ " (Haskell rounds to 2)")
+    println("  floor(5) = " ++ show(floor(5)) ++ " (should be 5)")
+    println("  ceil(5) = " ++ show(ceil(5)) ++ " (should be 5)")
+    println("  round(5) = " ++ show(round(5)) ++ " (should be 5)")
+    top 0
+}
+
+def test_trig(): Int {
+    println("")
+    println("Testing trig functions (radians):")
+    println("  sin(0) = " ++ show(sin(0)) ++ " (should be 0.0)")
+    println("  cos(0) = " ++ show(cos(0)) ++ " (should be 1.0)")
+    println("  tan(0) = " ++ show(tan(0)) ++ " (should be 0.0)")
+    println("  asin(0) = " ++ show(asin(0)) ++ " (should be 0.0)")
+    println("  acos(1) = " ++ show(acos(1)) ++ " (should be 0.0)")
+    println("  atan(1) = " ++ show(atan(1)) ++ " (should be ~0.785)")
+    println("  atan2(1, 1) = " ++ show(atan2(1, 1)) ++ " (should be ~0.785)")
+    top 0
+}
+
+def test_constants(): Int {
+    println("")
+    println("Testing constants:")
+    println("  pi = " ++ show(pi))
+    println("  e = " ++ show(e))
+    top 0
+}
+
+def main(): Int {
+    println("=== Advanced Math Builtins Test Suite ===")
+    println("")
+
+    test_pow()
+    test_rounding()
+    test_trig()
+    test_constants()
+
+    println("")
+    println("=== All Adv Math Tests Complete ===")
+    top 0
+}