diff --git a/docs/stdlib.md b/docs/stdlib.md index f28d80e..12c34ee 100644 --- a/docs/stdlib.md +++ b/docs/stdlib.md @@ -2,9 +2,9 @@ Index: - [docs](#docs-module) -- [arraylist](#arraylist-module) -- [array](#array-module) - [iter](#iter-module) +- [array](#array-module) +- [arraylist](#arraylist-module) - [assoclist](#assoclist-module) - [bytes](#bytes-module) - [char](#char-module) @@ -18,7 +18,6 @@ Index: - [fs](#fs-module) - [hash](#hash-module) - [hashmap](#hashmap-module) -- [result](#result-module) - [json](#json-module) - [list](#list-module) - [obj](#obj-module) @@ -54,88 +53,90 @@ The interface for a documentation generator. Create an object to document members of a module. -## arraylist module +## iter module -A growable array. +Lazy iterators. -### function `to_iter(list)` +### function `intersperse(it, val)` -Create an iterator over the arraylist. +Yield `val` in between each element of `it`. -### function `contains(list, thing)` +### function `repeat(val, n)` -Check if any element in `list` is equal to `thing`. +Create an iterator that repeats `val` `n` times. -### function `some(list, func)` +### function `min(it)` -Check if any element in `list` satisfies the predicate `func`. +Find the smallest item in the iterator (using `<`). -### function `find_index(list, func)` +### function `max(it)` -Get the first element that satisfies the predicate `func`, or null if none exists. +Find the largest item in the iterator (using `>`). -### function `find_index(list, func)` +### function `fold(it, init, reducer)` -Get the index of the first element that satisfies the predicate `func`, or -1 -if none exists. +Reduce the iterator, using `init` as the initial value of the accumulator. -### function `foreach(list, func)` +### function `fold1(it, reducer)` -Call `func` for each element of `list`. +Reduce the iterator, using the first value as the initial value of the accumulator. -### function `pop(list)` +### function `flat(it)` -Remove and return the last element of `list`. +Flattens an iterator of iterators. -### object `collector` +### function `zip(a, b)` -A collector for converting an iterator into an arraylist. +Create an iterator that joins `a` and `b` pair-wise. -### function `push(list, value)` +### function `take_while(it, pred)` -Push `value` on to the end of `list`, growing it if necessary. +Create an iterator that yields the values of `it` until `pred` returns false. -### function `to_array(list)` +### function `drop(it, n)` -Copy the elements of `list` into a fixed-length array. +Create an iterator that ignores the first `n` elements of `it`. -### function `delete(list, idx)` +Note that calling this function immediately evaluates and drops the first `n` +values of `it`. -Remove the element at index `idx` from `list`. This involves shuffling all -elements after `idx` leftward, so it's not very efficient. +### function `take(it, n)` -### function `set(list, idx, value)` +Create an iterator that evaluates the first `n` elements of `it`. -Set the element of `list` at index `idx` to `value`. +Note that evaluating this iterator partially evalutaes `it`. -### function `get(list, idx)` +### function `map(it, fn)` -Get the element of `list` at index `idx`. +Return a new iterator that yields the values of `it` applied to `fn`. -### function `capacity(list)` +### function `collect(it)` -Get the maximum number of items `list` can hold. +Evaluate an iterator, returning an array of the values it yields. -### function `length(list)` +### function `foreach(it, fn)` -Get the number of items in `list`. +Call the function `fn` for every element of `it`. This evaluates the iterator. -### function `new()` +### function `enumerate(it)` -Create an empty arraylist with default initial capacity. +Create an iterator that yields pairs of index and value from `it`. -### function `with_capacity(cap)` +### function `range(to)` -Create an empty arraylist with the given initial capacity. +Create an iterator that counts from 0 to `to`. -### function `iter(list)` +### function `count(n)` -Create an iterator over arraylist `list`. +Create an iterator that counts up from `n` indefinitely. -### function `from_array(len, array)` +### struct `collector` -Create a new arraylist from `array`. The `len` argument should be the length -of `array`. +An struct defining the required functions to convert an iterator into an arbitrary collection. + +### object `STOP` + +A sentinel value indicating that an iterator has been exhausted. ## array module @@ -178,7 +179,7 @@ Call `func` with the element, index, and array for each element of `array`. ### function `find(array, predicate)` -Find the element element for which `predicate` returns true. If there is none, returns null. +Find the element for which `predicate` returns true. If there is none, returns null. ### function `find_index(array, predicate)` @@ -200,82 +201,89 @@ Get the length of array `array`. Create a new array of length `len`. -## iter module +## arraylist module -Lazy iterators. +A growable array. -### function `repeat(val, n)` +### function `contains(list, thing)` -Create an iterator that repeats `val` `n` times. +Check if any element in `list` is equal to `thing`. -### function `min(it)` +### function `some(list, func)` -Find the smallest item in the iterator (using `<`). +Check if any element in `list` satisfies the predicate `func`. -### function `max(it)` +### function `find(list, func)` -Find the largest item in the iterator (using `>`). +Get the first element that satisfies the predicate `func`, or null if none exists. -### function `fold(it, init, reducer)` +### function `map(list, func)` -Reduce the iterator, using `init` as the initial value of the accumulator. +Create a new arraylist where each element is the result of calling `func` on +the corresponding element of `list`. -### function `fold1(it, reducer)` +### function `find_index(list, func)` -Reduce the iterator, using the first value as the initial value of the accumulator. +Get the index of the first element that satisfies the predicate `func`, or -1 +if none exists. -### function `flat(it)` +### function `foreach(list, func)` -Flattens an iterator of iterators. +Call `func` for each element of `list`. -### function `zip(a, b)` +### function `pop(list)` -Create an iterator that joins `a` and `b` pair-wise. +Remove and return the last element of `list`. -### function `take_while(it, pred)` +### object `collector` -Create an iterator that yields the values of `it` until `pred` returns false. +A collector for converting an iterator into an arraylist. -### function `drop(it, n)` +### function `push(list, value)` -Create an iterator that ignores the first `n` elements of `it`. +Push `value` on to the end of `list`, growing it if necessary. -Note that calling this function immediately evaluates and drops the first `n` -values of `it`. +### function `to_array(list)` -### function `take(it, n)` +Copy the elements of `list` into a fixed-length array. -Create an iterator that evaluates the first `n` elements of `it`. +### function `delete(list, idx)` -Note that evaluating this iterator partially evalutaes `it`. +Remove the element at index `idx` from `list`. This involves shuffling all +elements after `idx` leftward, so it's not very efficient. -### function `map(it, fn)` +### function `set(list, idx, value)` -Return a new iterator that yields the values of `it` applied to `fn`. +Set the element of `list` at index `idx` to `value`. -### function `collect(it)` +### function `get(list, idx)` -Evaluate an iterator, returning an array of the values it yields. +Get the element of `list` at index `idx`. -### function `foreach(it, fn)` +### function `capacity(list)` -Call the function `fn` for every element of `it`. This evaluates the iterator. +Get the maximum number of items `list` can hold. -### function `enumerate(it)` +### function `length(list)` -Create an iterator that yields pairs of index and value from `it`. +Get the number of items in `list`. -### function `range(to)` +### function `new()` -Create an iterator that counts from 0 to `to`. +Create an empty arraylist with default initial capacity. -### function `count(n)` +### function `with_capacity(cap)` -Create an iterator that counts up from `n` indefinitely. +Create an empty arraylist with the given initial capacity. -### struct `collector` +### function `iter(list)` -An struct defining the required functions to convert an iterator into an arbitrary collection. +Create an iterator over arraylist `list`. + +### function `from_array(len, array)` + +Create a new arraylist from `array`. The `len` argument should be the length +of `array`. ## assoclist module @@ -326,6 +334,10 @@ Create an empty assoclist. A compact byte array type. +### function `iter(bytes)` + +Create an iterator over `bytes`. + ### object `collector` A collector for converting an iterator into byte array. @@ -516,6 +528,10 @@ Performs `a == b`. Functions for working with strings. +### function `join(strings, sep)` + +Join all `strings` together with `sep` in between each. + ### function `split(string, on)` Break a string into an array of parts, where each part is separated by `on`. @@ -575,6 +591,10 @@ or strings into a string. Create an iterator over the characters in `str`. +### function `from_bytes(bytes)` + +Convert a byte array to a string. + ### function `char_at(string, idx)` Get the `idx`th character of `string`. @@ -607,6 +627,10 @@ Testing utilities. Panics if `cond` is not truthy. +### struct `AssertionError` + +Error raised when an assertion fails. + ## base64 module Base64 encoding and decoding functions. @@ -789,52 +813,6 @@ Create a new hashmap with `n` buckets. Create a collector for converting an iterator of entries into a hashmap. -## result module - -A result type. Probably rendered obsolete by panicking. - -### function `map_error(result, fn)` - -Return a new result where the value has been processed by `fn` if the result -was unsuccessful. - -### function `map(result, fn)` - -Return a new result where the value has been processed by `fn` if the result -was successful. - -### function `data(result)` - -Get the value from `result`. - -### function `code(result)` - -Get the error code from `result`. - -### function `is_error(result)` - -Check if `result` was unsuccessful. - -### function `is_ok(result)` - -Check if `result` was successful. - -### function `error(code, value)` - -Create a failed result with error code `code` and data `value`. - -### function `ok(value)` - -Create a successful result containing `value`. - -### constant `ERROR` - -A sentinel value representing an unsuccessful result. - -### constant `OK` - -A sentinel value representing a successful result. - ## json module A partial implementation of a JSON parser. @@ -843,21 +821,22 @@ A partial implementation of a JSON parser. Parse the string `input` as JSON. -The returned value is a `result`, for historical reasons (lol). See the `result` -module for more information. - -### constant `E_INVALID_JSON` +### struct `InvalidJsonError` -An error returned when the input string is not able to be parsed. +Error raised when the input string is not able to be parsed. -### constant `E_UNEXPECTED_TOKEN` +### struct `UnexpectedTokenError` -An error returned when an unexpected token is encountered. +Error raised when an unexpected token is encountered. ## list module A linked list implementation. +### function `foldl(list, init, reducer)` + +Reduce the list from the left. + ### function `to_array(list)` Create a new array with the elements of `list`. @@ -886,13 +865,13 @@ Call `func` for every element of `list`. ### function `append(list, value)` -Add a value to the end of the list. +Return a new list with `value` added to the end. Like `length`, this function is O(n). ### function `prepend(list, value)` -Add a value to the front of the list. +Return a new list with `value` added to the front. This function is O(1) (i.e. takes the same time regardless of the length of the list). @@ -955,6 +934,10 @@ Define a class that extends `super`. The `methods` value should be a hashmap of functions. +### struct `NoSuchMethodError` + +Error raised when an unrecognized message is sent to an object. + ## path module Utilities for manipulating filesystem paths. diff --git a/scripts/generate-documentation b/scripts/generate-documentation index a496179..7cc6680 100755 --- a/scripts/generate-documentation +++ b/scripts/generate-documentation @@ -12,6 +12,7 @@ import fn; import fs; import hash; import hashmap; +import inet; import iter; import json; import list; @@ -20,7 +21,6 @@ import obj; import op; import path; import re; -import result; import string; import test;