diff --git a/docs/reference/ax-language.md b/docs/reference/ax-language.md index dc44a77..bbbe6f6 100644 --- a/docs/reference/ax-language.md +++ b/docs/reference/ax-language.md @@ -236,7 +236,7 @@ import "std-name" Import statements load a standard library package at compile time. The library source is inlined into the compilation unit before type-checking. The import line itself is removed from the compiled output. -Standard library packages are resolved from the `libs/` directory relative to the current working directory. +Standard library packages are resolved from the `libs/` directory relative to the current working directory. When a library source is inlined, any `fn main() -> Int` stub present in the library file is stripped so it does not conflict with the importing program's own `main`. Example: @@ -259,6 +259,20 @@ These functions are provided by the runtime and do not need to be imported: | `__builtin_float_to_string` | `(Float) -> String` | Convert a float to its string representation | | `__builtin_string_len` | `(String) -> Int` | Length of a string in bytes | | `__builtin_string_chars` | `(String) -> List` | Split a string into a list of single-character strings | +| `__builtin_string_contains` | `(String, String) -> Bool` | True if first string contains the second | +| `__builtin_string_starts_with` | `(String, String) -> Bool` | True if string starts with prefix | +| `__builtin_string_ends_with` | `(String, String) -> Bool` | True if string ends with suffix | +| `__builtin_string_to_upper` | `(String) -> String` | Uppercase copy | +| `__builtin_string_to_lower` | `(String) -> String` | Lowercase copy | +| `__builtin_string_trim` | `(String) -> String` | Strip leading/trailing whitespace | +| `__builtin_string_join` | `(List, String) -> String` | Join list with separator | +| `__builtin_list_len` | `(List) -> Int` | Number of elements | +| `__builtin_list_is_empty` | `(List) -> Bool` | True if list has zero elements | +| `__builtin_list_head` | `(List) -> Option` | First element, or None | +| `__builtin_list_tail` | `(List) -> List` | All elements after the first | +| `__builtin_list_append` | `(List, T) -> List` | New list with item added at end | +| `__builtin_list_concat` | `(List, List) -> List` | Concatenate two lists | +| `__builtin_list_reverse` | `(List) -> List` | Reversed copy | These built-ins are also wrapped in `std-json` (via `int_to_string`, `json_escape`) and can be called directly in any `.ax` file. diff --git a/docs/spec/ax-language-1.0.md b/docs/spec/ax-language-1.0.md index 6750211..59794dc 100644 --- a/docs/spec/ax-language-1.0.md +++ b/docs/spec/ax-language-1.0.md @@ -438,6 +438,42 @@ Pattern matching introduces bindings into the arm's scope: Bindings are only in scope within the arm's right-hand side. +## 5a. Standard built-in functions + +The following functions are provided by the runtime in every compilation unit. They require no import. Their names begin with `__builtin_` to prevent shadowing by user-defined identifiers. + +All built-ins are pure (no capability annotation). Their semantics are defined below. + +### String operations + +| Name | Signature | Semantics | +|------|-----------|-----------| +| `__builtin_int_to_string` | `(Int) -> String` | Returns the decimal string representation of the argument. | +| `__builtin_float_to_string` | `(Float) -> String` | Returns a string representation of the float argument. | +| `__builtin_string_len` | `(String) -> Int` | Returns the number of bytes in the UTF-8 encoding of the string. | +| `__builtin_string_chars` | `(String) -> List` | Returns a list of single-character strings, one per Unicode scalar value. | +| `__builtin_string_contains` | `(String, String) -> Bool` | Returns `true` iff the first argument contains the second as a substring. | +| `__builtin_string_starts_with` | `(String, String) -> Bool` | Returns `true` iff the first argument begins with the prefix given by the second. | +| `__builtin_string_ends_with` | `(String, String) -> Bool` | Returns `true` iff the first argument ends with the suffix given by the second. | +| `__builtin_string_to_upper` | `(String) -> String` | Returns a copy of the string with all ASCII alphabetic characters uppercased. | +| `__builtin_string_to_lower` | `(String) -> String` | Returns a copy of the string with all ASCII alphabetic characters lowercased. | +| `__builtin_string_trim` | `(String) -> String` | Returns a copy of the string with leading and trailing ASCII whitespace removed. | +| `__builtin_string_join` | `(List, String) -> String` | Returns the elements of the list concatenated, with the second argument inserted between each pair of adjacent elements. | + +### List operations + +| Name | Signature | Semantics | +|------|-----------|-----------| +| `__builtin_list_len` | `(List) -> Int` | Returns the number of elements in the list. | +| `__builtin_list_is_empty` | `(List) -> Bool` | Returns `true` iff the list has zero elements. | +| `__builtin_list_head` | `(List) -> Option` | Returns `Some(first)` if the list is non-empty, otherwise `None`. | +| `__builtin_list_tail` | `(List) -> List` | Returns a new list containing all elements after the first. Returns an empty list if the argument is empty. | +| `__builtin_list_append` | `(List, T) -> List` | Returns a new list equal to the original with the second argument appended at the end. | +| `__builtin_list_concat` | `(List, List) -> List` | Returns a new list that is the concatenation of the two arguments, in order. | +| `__builtin_list_reverse` | `(List) -> List` | Returns a new list containing the same elements in reversed order. | + +All list built-ins are non-mutating; the original list is unchanged. This is consistent with the immutability requirement in ยง7.2. + ## 6. Capability semantics ### 6.1 Annotation form