From cfe54cca75b9a03d858277aa3cb94701f38bd97b Mon Sep 17 00:00:00 2001 From: Matthew Paras <34500476+mattwparas@users.noreply.github.com> Date: Sun, 22 Dec 2024 17:26:25 -0800 Subject: [PATCH] Update hashset docs (#297) * refactor hashset functions, get ready for documentation * generate docs --- crates/steel-core/src/primitives/hashsets.rs | 250 ++++++++++--------- docs/src/builtins/steel_base.md | 159 ++++++++++-- docs/src/builtins/steel_bytevectors.md | 2 + docs/src/builtins/steel_ffi.md | 1 + docs/src/builtins/steel_filesystem.md | 8 +- docs/src/builtins/steel_http.md | 9 + docs/src/builtins/steel_identity.md | 1 + docs/src/builtins/steel_immutable-vectors.md | 6 +- docs/src/builtins/steel_meta.md | 5 +- docs/src/builtins/steel_numbers.md | 23 ++ docs/src/builtins/steel_polling.md | 13 + docs/src/builtins/steel_ports.md | 20 ++ docs/src/builtins/steel_sets.md | 68 +++++ docs/src/builtins/steel_syntax.md | 1 + docs/src/builtins/steel_tcp.md | 9 +- docs/src/builtins/steel_threads.md | 17 +- docs/src/builtins/steel_vectors.md | 3 + 17 files changed, 448 insertions(+), 147 deletions(-) create mode 100644 docs/src/builtins/steel_http.md create mode 100644 docs/src/builtins/steel_polling.md diff --git a/crates/steel-core/src/primitives/hashsets.rs b/crates/steel-core/src/primitives/hashsets.rs index 69d32a30c..eb8e61660 100644 --- a/crates/steel-core/src/primitives/hashsets.rs +++ b/crates/steel-core/src/primitives/hashsets.rs @@ -1,42 +1,34 @@ use crate::rvals::SteelHashSet; -use crate::stop; +use crate::rvals::{Result, SteelVal}; +use crate::steel_vm::vm::VmCore; use crate::values::lists::List; use crate::values::HashSet; -use crate::{ - core::utils::declare_const_ref_functions, - rvals::{Result, SteelVal}, -}; use crate::{gc::Gc, steel_vm::builtin::BuiltInModule}; - -use crate::primitives::VectorOperations; - -declare_const_ref_functions!( - HS_CONSTRUCT => hs_construct, - HS_LENGTH => hs_length, - HS_CONTAINS => hs_contains, - // HS_INSERT => hs_insert, - HS_TO_LIST => keys_to_list, - HS_TO_VEC => keys_to_vector, - HS_CLEAR => clear, - HS_SUBSET => is_subset, - LIST_TO_HS => list_to_hashset, -); +use crate::{stop, Vector}; pub(crate) fn hashset_module() -> BuiltInModule { let mut module = BuiltInModule::new("steel/sets"); module - .register_value("hashset", HS_CONSTRUCT) - .register_value("hashset-length", HS_LENGTH) - .register_value("hashset-contains?", HS_CONTAINS) + .register_native_fn_definition(HS_CONSTRUCT_DEFINITION) + .register_native_fn_definition(HASHSET_LENGTH_DEFINITION) + .register_native_fn_definition(HASHSET_CONTAINS_DEFINITION) .register_native_fn_definition(HS_INSERT_DEFINITION) - .register_value("hashset->list", HS_TO_LIST) - .register_value("hashset->vector", HS_TO_VEC) - .register_value("hashset-clear", HS_CLEAR) - .register_value("hashset-subset?", HS_SUBSET) - .register_value("list->hashset", LIST_TO_HS); + .register_native_fn_definition(HASHSET_TO_LIST_DEFINITION) + .register_native_fn_definition(HASHSET_TO_IMMUTABLE_VECTOR_DEFINITION) + .register_native_fn_definition(HASHSET_TO_MUTABLE_VECTOR_DEFINITION) + .register_native_fn_definition(HASHSET_CLEAR_DEFINITION) + .register_native_fn_definition(HASHSET_IS_SUBSET_DEFINITION) + .register_native_fn_definition(LIST_TO_HASHSET_DEFINITION); module } +/// Constructs a new hash set +/// +/// # Examples +/// ```scheme +/// (hashset 10 20 30 40) +/// ``` +#[steel_derive::native(name = "hashset", arity = "AtLeast(0)")] pub fn hs_construct(args: &[SteelVal]) -> Result { let mut hs = HashSet::new(); @@ -51,20 +43,26 @@ pub fn hs_construct(args: &[SteelVal]) -> Result { Ok(SteelVal::HashSetV(Gc::new(hs).into())) } -pub fn hs_length(args: &[SteelVal]) -> Result { - if args.len() != 1 { - stop!(ArityMismatch => "hs-length takes 1 argument") - } - - let hashmap = &args[0]; - - if let SteelVal::HashSetV(hm) = hashmap { - Ok(SteelVal::IntV(hm.len() as isize)) - } else { - stop!(TypeMismatch => "hs-length takes a hashmap") - } +/// Get the number of elements in the hashset +/// +/// # Examples +/// ```scheme +/// (hashset-length (hashset 10 20 30)) ;; => 3 +/// ``` +#[steel_derive::function(name = "hashset-length")] +pub fn hashset_length(hashset: &SteelHashSet) -> usize { + hashset.len() } +/// Insert a new element into the hashset. Returns a hashset. +/// +/// # Examples +/// ```scheme +/// (define hs (hashset 10 20 30)) +/// (define updated (hashset-insert hs 40)) +/// (equal? hs (hashset 10 20 30)) ;; => #true +/// (equal? updated (hashset 10 20 30 40)) ;; => #true +/// ``` #[steel_derive::function(name = "hashset-insert")] pub fn hs_insert(hashset: &mut SteelVal, value: SteelVal) -> Result { if value.is_hashable() { @@ -85,103 +83,113 @@ pub fn hs_insert(hashset: &mut SteelVal, value: SteelVal) -> Result { } } -pub fn hs_contains(args: &[SteelVal]) -> Result { - if args.len() != 2 { - stop!(ArityMismatch => "set-contains? get takes 2 arguments") - } - - let hashset = &args[0]; - let key = &args[1]; - - if let SteelVal::HashSetV(hm) = hashset { - if key.is_hashable() { - Ok(SteelVal::BoolV(hm.contains(key))) - } else { - stop!(TypeMismatch => "hash key not hashable!: {}", key); - } +/// Test if the hashset contains a given element. +/// +/// # Examples +/// ```scheme +/// (hashset-contains? (hashset 10 20) 10) ;; => #true +/// (hashset-contains? (hashset 10 20) "foo") ;; => #false +/// ``` +#[steel_derive::function(name = "hashset-contains?")] +pub fn hashset_contains(hashset: &SteelHashSet, key: &SteelVal) -> Result { + if key.is_hashable() { + Ok(SteelVal::BoolV(hashset.contains(key))) } else { - stop!(TypeMismatch => "set-contains? takes a hashmap") + stop!(TypeMismatch => "hash key not hashable!: {}", key); } } -pub fn is_subset(args: &[SteelVal]) -> Result { - if args.len() != 2 { - stop!(ArityMismatch => "hashset-subset? takes 2 arguments") - } - - let left = &args[0]; - let right = &args[1]; - - if let SteelVal::HashSetV(left) = left { - if let SteelVal::HashSetV(right) = right { - Ok(SteelVal::BoolV(left.is_subset(right.0.as_ref()))) - } else { - stop!(TypeMismatch => "hash-subset? takes a hashset") - } - } else { - stop!(TypeMismatch => "hashset-subset? takes a hashset") - } +/// Check if the left set is a subset of the right set +/// +/// # Examples +/// ```scheme +/// (hashset-subset? (hash 10) (hashset 10 20)) ;; => #true +/// (hashset-subset? (hash 100) (hashset 30)) ;; => #false +/// ``` +#[steel_derive::function(name = "hashset-subset?")] +pub fn hashset_is_subset(left: &SteelHashSet, right: &SteelHashSet) -> bool { + left.is_subset(right.0.as_ref()) } -// keys as list -pub fn keys_to_list(args: &[SteelVal]) -> Result { - if args.len() != 1 { - stop!(ArityMismatch => "hs-keys->list takes 1 argument") - } - - let hashset = &args[0]; +/// Creates a list from this hashset. The order of the list is not guaranteed. +/// +/// # Examples +/// ```scheme +/// (hashset->list (hashset 10 20 30)) ;; => '(10 20 30) +/// (hashset->list (hashset 10 20 30)) ;; => '(20 10 30) +/// ``` +#[steel_derive::function(name = "hashset->list")] +pub fn hashset_to_list(hashset: &SteelHashSet) -> SteelVal { + SteelVal::ListV(hashset.iter().cloned().collect::>()) +} - if let SteelVal::HashSetV(hs) = hashset { - Ok(SteelVal::ListV( - hs.iter().cloned().collect::>(), - )) - } else { - stop!(TypeMismatch => "hs-keys->list takes a hashmap") - } +/// Creates an immutable vector from this hashset. The order of the vector is not guaranteed. +/// +/// # Examples +/// ```scheme +/// (hashset->immutable-vector (hashset 10 20 30)) ;; => '#(10 20 30) +/// (hashset->immutable-vector (hashset 10 20 30)) ;; => '#(20 10 30) +/// ``` +#[steel_derive::function(name = "hashset->immutable-vector")] +pub fn hashset_to_immutable_vector(hashset: &SteelHashSet) -> SteelVal { + SteelVal::VectorV(Gc::new(hashset.0.iter().cloned().collect::>()).into()) } -// keys as vectors -pub fn keys_to_vector(args: &[SteelVal]) -> Result { - if args.len() != 1 { - stop!(ArityMismatch => "hs-keys->vector takes 1 argument") - } +/// Creates a mutable vector from this hashset. The order of the vector is not guaranteed. +/// +/// # Examples +/// ```scheme +/// (hashset->vector (hashset 10 20 30)) ;; => '#(10 20 30) +/// (hashset->vector (hashset 10 20 30)) ;; => '#(20 10 30) +/// ``` +#[steel_derive::context(name = "hashset->vector", arity = "Exact(1)")] +pub fn hashset_to_mutable_vector(ctx: &mut VmCore, args: &[SteelVal]) -> Option> { + fn hashset_to_mutable_vector_impl(ctx: &mut VmCore, args: &[SteelVal]) -> Result { + if args.len() != 1 { + stop!(ArityMismatch => "hashset->vector takes 1 argument") + } - let hashset = &args[0]; + let hashset = &args[0]; - if let SteelVal::HashSetV(hs) = hashset { - VectorOperations::vec_construct_iter_normal(hs.iter().cloned()) - } else { - stop!(TypeMismatch => "hs-keys->vector takes a hashmap") - } -} - -pub fn clear(args: &[SteelVal]) -> Result { - if args.len() != 1 { - stop!(ArityMismatch => "hs-clear takes 1 argument") + if let SteelVal::HashSetV(hs) = hashset { + Ok(ctx.make_mutable_vector(hs.iter().cloned().collect())) + } else { + stop!(TypeMismatch => "hashset->vector takes a hashset") + } } - let hashset = &args[0]; + Some(hashset_to_mutable_vector_impl(ctx, args)) +} - if let SteelVal::HashSetV(hs) = hashset { - let mut hs = hs.0.unwrap(); - hs.clear(); - Ok(SteelVal::HashSetV(Gc::new(hs).into())) +/// Clears the hashset and returns the passed in hashset. +/// This first checks if there are no other references to this hashset, +/// and if there aren't, clears that allocation. Given that there are +/// functional updates, this is only relevant if there are no more +/// references to a given hashset, and you want to reuse its allocation. +#[steel_derive::function(name = "hashset-clear")] +pub fn hashset_clear(hashset: &mut SteelVal) -> Result { + if let SteelVal::HashSetV(SteelHashSet(hs)) = hashset { + match Gc::get_mut(hs) { + Some(m) => { + m.clear(); + Ok(std::mem::replace(hashset, SteelVal::Void)) + } + None => Ok(SteelVal::HashSetV(Gc::new(HashSet::new()).into())), + } } else { - stop!(TypeMismatch => "hs-clear takes a hashmap") + stop!(TypeMismatch => format!("hashset-clear takes a hashset, found: {}", hashset)) } } -pub fn list_to_hashset(args: &[SteelVal]) -> Result { - if args.len() != 1 { - stop!(ArityMismatch => "list->hashset takes one argument") - } - if let SteelVal::ListV(l) = &args[0] { - Ok(SteelVal::HashSetV( - Gc::new(l.iter().cloned().collect::>()).into(), - )) - } else { - stop!(TypeMismatch => "list->hashset takes a hashset"); - } +/// Convert the given list into a hashset. +/// +/// # Examples +/// ```scheme +/// (list 10 20 30) ;; => (hashset 10 20 30) +/// ``` +#[steel_derive::function(name = "list->hashset")] +pub fn list_to_hashset(l: &List) -> SteelVal { + SteelVal::HashSetV(Gc::new(l.iter().cloned().collect::>()).into()) } #[cfg(test)] @@ -285,7 +293,7 @@ mod hashset_tests { ), SteelVal::StringV("foo".into()), ]; - let res = hs_contains(&args); + let res = steel_hashset_contains(&args); let expected = SteelVal::BoolV(true); assert_eq!(res.unwrap(), expected); } @@ -304,7 +312,7 @@ mod hashset_tests { ), SteelVal::StringV("bar".into()), ]; - let res = hs_contains(&args); + let res = steel_hashset_contains(&args); let expected = SteelVal::BoolV(false); assert_eq!(res.unwrap(), expected); } @@ -323,7 +331,7 @@ mod hashset_tests { ) .into(), )]; - let res = keys_to_vector(&args); + let res = steel_hashset_to_immutable_vector(&args); let expected = vector![ SteelVal::StringV("foo".into()), SteelVal::StringV("bar".into()), diff --git a/docs/src/builtins/steel_base.md b/docs/src/builtins/steel_base.md index 76ea1a7be..f3278dcfa 100644 --- a/docs/src/builtins/steel_base.md +++ b/docs/src/builtins/steel_base.md @@ -335,7 +335,6 @@ Rounds the given number up to the nearest integer not less than it. > (ceiling 42.1) ;; => 43 > (ceiling -42.1) ;; => -42 ``` - ### **change-current-directory!** Change the current working directory ### **char->integer** @@ -829,6 +828,76 @@ map: hash? > (hash-keys->vector (hash 'a 10 'b 20)), => [10 10]", ``` +### **hashset** +Constructs a new hash set + +#### Examples +```scheme +(hashset 10 20 30 40) +``` +### **hashset->immutable-vector** +Creates an immutable vector from this hashset. The order of the vector is not guaranteed. + +#### Examples +```scheme +(hashset->immutable-vector (hashset 10 20 30)) ;; => '#(10 20 30) +(hashset->immutable-vector (hashset 10 20 30)) ;; => '#(20 10 30) +``` +### **hashset->list** +Creates a list from this hashset. The order of the list is not guaranteed. + +#### Examples +```scheme +(hashset->list (hashset 10 20 30)) ;; => '(10 20 30) +(hashset->list (hashset 10 20 30)) ;; => '(20 10 30) +``` +### **hashset->vector** +Creates a mutable vector from this hashset. The order of the vector is not guaranteed. + +#### Examples +```scheme +(hashset->vector (hashset 10 20 30)) ;; => '#(10 20 30) +(hashset->vector (hashset 10 20 30)) ;; => '#(20 10 30) +``` +### **hashset-clear** +Clears the hashset and returns the passed in hashset. +This first checks if there are no other references to this hashset, +and if there aren't, clears that allocation. Given that there are +functional updates, this is only relevant if there are no more +references to a given hashset, and you want to reuse its allocation. +### **hashset-contains?** +Test if the hashset contains a given element. + +#### Examples +```scheme +(hashset-contains? (hashset 10 20) 10) ;; => #true +(hashset-contains? (hashset 10 20) "foo") ;; => #false +``` +### **hashset-insert** +Insert a new element into the hashset. Returns a hashset. + +#### Examples +```scheme +(define hs (hashset 10 20 30)) +(define updated (hashset-insert hs 40)) +(equal? hs (hashset 10 20 30)) ;; => #true +(equal? updated (hashset 10 20 30 40)) ;; => #true +``` +### **hashset-length** +Get the number of elements in the hashset + +#### Examples +```scheme +(hashset-length (hashset 10 20 30)) ;; => 3 +``` +### **hashset-subset?** +Check if the left set is a subset of the right set + +#### Examples +```scheme +(hashset-subset? (hash 10) (hashset 10 20)) ;; => #true +(hashset-subset? (hash 100) (hashset 30)) ;; => #false +``` ### **inexact->exact** Converts an inexact number to an exact number. @@ -967,6 +1036,13 @@ otherwise this function will error. ```scheme (list->bytes (list 0 1 2 3 4 5)) ;; => (bytes 0 1 2 3 4 5) ``` +### **list->hashset** +Convert the given list into a hashset. + +#### Examples +```scheme +(list 10 20 30) ;; => (hashset 10 20 30) +``` ### **list-ref** Returns the value located at the given index. Will raise an error if you try to index out of bounds. @@ -996,9 +1072,10 @@ Returns the local time in the format given by the input string (using `chrono::L * fmt : string? ### **lock-acquire!** -Lock the given mutex +Lock the given mutex. Note, this is most likely used as a building block +with the `lock!` function. ### **lock-release!** -Unlock the given mutex +Unlock the given mutex. ### **log** Computes the natural logarithm of the given number. @@ -1051,6 +1128,21 @@ Creates a thread local storage slot. These slots are static, and will _not_ be r When spawning a new thread, the value inside will be shared into that slot, however future updates to the slot will be local to that thread. +### **modulo** +Returns the remainder of the division of the first number by the second + +(modulo n m) -> integer? + +* n : integer? +* m : integer? + +#### Examples +```scheme +> (modulo 10 3) ;; => 1 +> (modulo -10 3) ;; => 2 +> (modulo 10 -3) ;; => -2 +> (module -10 -3) ;; => -1 +``` ### **mutex** Construct a new mutex ### **nan?** @@ -1264,6 +1356,21 @@ Reads a single byte from an input port. (read-byte [port]) -> byte? +* port : input-port? = (current-input-port) +### **read-bytes** +Reads bytes from an input port. + +(read-bytes amt [port]) -> bytes? + +* amt : (and positive? int?) +* port : input-port? = (current-input-port) +### **read-bytes-into-buf** +Reads bytes from an input port into a given buffer. + +(read-bytes-into-buf buf amt [port]) -> bytes? + +* buf : bytes? +* amt : (and positive? int?) * port : input-port? = (current-input-port) ### **read-char** Reads the next character from an input port. @@ -1360,6 +1467,16 @@ error[E11]: Generic ### **set-tls!** Set the value in the the thread local storage. Only this thread will see the updates associated with this TLS. +### **spawn-native-thread** +Spawns the given `func` on another thread. It is required that the arity of the +given function be 0. If the arity of the given function cannot be checked until runtime, +the thread will be spawned and the function will fail to execute. + +#### Examples + +```scheme +(define thread (spawn-native-thread (lambda () (displayln "Hello world!")))) +``` ### **split-many** Splits a string given a separator pattern into a list of strings. @@ -1818,6 +1935,10 @@ Serializes a Steel value into a string. ``` ### **void** The void value, returned by many forms with side effects, such as `define`. +### **would-block-object?** +Returns `#t` if the value is an EOF object. + +(eof-object? any/c) -> bool? ### **write-byte** Writes a single byte to an output port. @@ -1866,10 +1987,13 @@ Checks if the given real number is zero. ### **Some->value** ### **Some?** ### **TypeId?** +### **acos** ### **active-object-count** ### **arithmetic-shift** ### **arity?** +### **asin** ### **assert!** +### **atan** ### **atom?** ### **attach-contract-struct!** ### **block-on** @@ -1878,6 +2002,8 @@ Checks if the given real number is zero. ### **box** ### **box-strong** ### **breakpoint!** +### **bytes-clear!** +### **bytes-push!** ### **call-with-current-continuation** ### **call-with-exception-handler** ### **call/cc** @@ -1900,8 +2026,10 @@ Checks if the given real number is zero. ### **compose** ### **concat-symbols** ### **continuation?** +### **cos** ### **current-function-span** ### **current-os!** +### **current-thread-id** ### **dropping** ### **duration->seconds** ### **duration-since** @@ -1913,8 +2041,11 @@ Checks if the given real number is zero. ### **eqv?** ### **error-object?** ### **error-with-span** +### **eval** ### **eval!** +### **eval-string** ### **even?** +### **exact** ### **expand!** ### **extending** ### **f+** @@ -1929,15 +2060,9 @@ Checks if the given real number is zero. ### **get-test-mode** ### **hash-get** ### **hash?** -### **hashset** -### **hashset->list** -### **hashset->vector** -### **hashset-clear** -### **hashset-contains?** -### **hashset-insert** -### **hashset-length** -### **hashset-subset?** -### **inspect-bytecode** +### **immutable-vector** +### **immutable-vector?** +### **inspect** ### **instant/elapsed** ### **instant/now** ### **interleaving** @@ -1957,11 +2082,11 @@ Checks if the given real number is zero. ### **into-vector** ### **iter-next!** ### **join!** -### **list->hashset** ### **list->string** ### **list->vector** ### **list-tail** ### **list?** +### **load** ### **local-executor/block-on** ### **make-channels** ### **make-struct-type** @@ -1994,6 +2119,7 @@ Checks if the given real number is zero. ### **read!** ### **read-line-from-port** ### **read-to-string** +### **remainder** ### **run!** ### **set-box!** ### **set-current-dir!** @@ -2002,7 +2128,8 @@ Checks if the given real number is zero. ### **set-strong-box!** ### **set-test-mode!** ### **set?** -### **spawn-native-thread** +### **sin** +### **span-file-id** ### **spawn-process** ### **spawn-thread!** ### **stdout** @@ -2023,6 +2150,7 @@ Checks if the given real number is zero. ### **syntax/loc** ### **syntax?** ### **taking** +### **tan** ### **thread/available-parallelism** ### **thread::current/id** ### **transduce** @@ -2035,6 +2163,8 @@ Checks if the given real number is zero. ### **vec-rest** ### **vector** ### **vector-append!** +### **vector-copy!** +### **vector-fill!** ### **vector-length** ### **vector-push!** ### **vector-ref** @@ -2044,5 +2174,6 @@ Checks if the given real number is zero. ### **wait** ### **wait->stdout** ### **which** +### **would-block** ### **write-line!** ### **zipping** diff --git a/docs/src/builtins/steel_bytevectors.md b/docs/src/builtins/steel_bytevectors.md index fa6e54df8..ed1a54876 100644 --- a/docs/src/builtins/steel_bytevectors.md +++ b/docs/src/builtins/steel_bytevectors.md @@ -153,3 +153,5 @@ Creates a bytevector given a length and a default value. ``` ### **utf8->string** Alias of `bytes->string/utf8`. +### **bytes-clear!** +### **bytes-push!** diff --git a/docs/src/builtins/steel_ffi.md b/docs/src/builtins/steel_ffi.md index 57fe54e9b..0a863c25a 100644 --- a/docs/src/builtins/steel_ffi.md +++ b/docs/src/builtins/steel_ffi.md @@ -1,4 +1,5 @@ # steel/ffi ### **ffi-vector** ### **ffi-vector-ref** +### **function->ffi-function** ### **mutable-string** diff --git a/docs/src/builtins/steel_filesystem.md b/docs/src/builtins/steel_filesystem.md index 4c0aa195f..54d2dd954 100644 --- a/docs/src/builtins/steel_filesystem.md +++ b/docs/src/builtins/steel_filesystem.md @@ -3,26 +3,26 @@ Filesystem functions, mostly just thin wrappers around the `std::fs` functions i the Rust std library. ### **canonicalize-path** Returns canonical path with all components normalized +### **change-current-directory!** +Change the current working directory ### **copy-directory-recursively!** Recursively copies the directory from source to destination ### **create-directory!** Creates the directory ### **current-directory** Check the current working directory -### **change-current-directory!** -Change the current working directory ### **delete-directory!** Deletes the directory ### **delete-file!** Deletes the file ### **file-name** Gets the filename for a given path -### **parent-name** -Gets the parent directory name for a given path ### **is-dir?** Checks if a path is a directory ### **is-file?** Checks if a path is a file +### **parent-name** +Gets the parent directory name for a given path ### **path->extension** Gets the extension from a path ### **path-exists?** diff --git a/docs/src/builtins/steel_http.md b/docs/src/builtins/steel_http.md new file mode 100644 index 000000000..2d3c091ee --- /dev/null +++ b/docs/src/builtins/steel_http.md @@ -0,0 +1,9 @@ +# steel/http +### **http-parse-request** +### **http-parse-response** +### **http-request-body-offset** +### **http-request-headers** +### **http-request-method** +### **http-request-path** +### **http-request-version** +### **http-response-headers** diff --git a/docs/src/builtins/steel_identity.md b/docs/src/builtins/steel_identity.md index 86b41a3b7..7c71a4d9f 100644 --- a/docs/src/builtins/steel_identity.md +++ b/docs/src/builtins/steel_identity.md @@ -119,6 +119,7 @@ Checks if the given value is a real number ### **function?** ### **future?** ### **hash?** +### **immutable-vector?** ### **list?** ### **mutable-vector?** ### **not** diff --git a/docs/src/builtins/steel_immutable-vectors.md b/docs/src/builtins/steel_immutable-vectors.md index ae762020c..fb53cd8c9 100644 --- a/docs/src/builtins/steel_immutable-vectors.md +++ b/docs/src/builtins/steel_immutable-vectors.md @@ -1,6 +1,7 @@ # steel/immutable-vectors ### **immutable-vector-push** Pushes a value to the back of the vector, returning a new vector. +### **immutable-vector** ### **immutable-vector->list** ### **immutable-vector->string** ### **immutable-vector-append** @@ -10,5 +11,8 @@ Pushes a value to the back of the vector, returning a new vector. ### **immutable-vector-set** ### **immutable-vector-take** ### **make-immutable-vector** -### **vector** +### **vector->string** +### **vector-append** +### **vector-copy** +### **vector-immutable** ### **vector-push-front** diff --git a/docs/src/builtins/steel_meta.md b/docs/src/builtins/steel_meta.md index e9e5a0c54..8b1ec0809 100644 --- a/docs/src/builtins/steel_meta.md +++ b/docs/src/builtins/steel_meta.md @@ -28,14 +28,17 @@ Returns the message of an error object. ### **current-os!** ### **env-var** ### **error-with-span** +### **eval** ### **eval!** +### **eval-string** ### **expand!** ### **function-name** ### **get-contract-struct** ### **get-test-mode** -### **inspect-bytecode** +### **inspect** ### **iter-next!** ### **join!** +### **load** ### **local-executor/block-on** ### **make-struct-type** ### **maybe-get-env-var** diff --git a/docs/src/builtins/steel_numbers.md b/docs/src/builtins/steel_numbers.md index 3ab94d033..f06e45d96 100644 --- a/docs/src/builtins/steel_numbers.md +++ b/docs/src/builtins/steel_numbers.md @@ -249,6 +249,21 @@ Computes the magnitude of the given number. > (magnitude 5) ;; => 5 > (magnitude -5) ;; => 5 ``` +### **modulo** +Returns the remainder of the division of the first number by the second + +(modulo n m) -> integer? + +* n : integer? +* m : integer? + +#### Examples +```scheme +> (modulo 10 3) ;; => 1 +> (modulo -10 3) ;; => 2 +> (modulo 10 -3) ;; => -2 +> (module -10 -3) ;; => -1 +``` ### **nan?** Returns `#t` if the real number is Nan. @@ -365,7 +380,15 @@ Checks if the given real number is zero. > (zero? 0.0) ;; => #t > (zero? 0.1) ;; => #f ``` +### **acos** ### **arithmetic-shift** +### **asin** +### **atan** +### **cos** ### **even?** +### **exact** ### **f+** ### **odd?** +### **remainder** +### **sin** +### **tan** diff --git a/docs/src/builtins/steel_polling.md b/docs/src/builtins/steel_polling.md new file mode 100644 index 000000000..7c73023eb --- /dev/null +++ b/docs/src/builtins/steel_polling.md @@ -0,0 +1,13 @@ +# steel/polling +### **add-event-interest-all** +### **add-event-interest-read** +### **add-event-interest-write** +### **events->list** +### **events-clear!** +### **fresh-event-id** +### **make-poller** +### **modify-event-interest-all!** +### **modify-event-interest-read!** +### **modify-event-interest-write!** +### **poller-delete!** +### **poller-wait** diff --git a/docs/src/builtins/steel_ports.md b/docs/src/builtins/steel_ports.md index 7346041c1..5948954d3 100644 --- a/docs/src/builtins/steel_ports.md +++ b/docs/src/builtins/steel_ports.md @@ -109,6 +109,21 @@ Reads a single byte from an input port. (read-byte [port]) -> byte? +* port : input-port? = (current-input-port) +### **read-bytes** +Reads bytes from an input port. + +(read-bytes amt [port]) -> bytes? + +* amt : (and positive? int?) +* port : input-port? = (current-input-port) +### **read-bytes-into-buf** +Reads bytes from an input port into a given buffer. + +(read-bytes-into-buf buf amt [port]) -> bytes? + +* buf : bytes? +* amt : (and positive? int?) * port : input-port? = (current-input-port) ### **read-char** Reads the next character from an input port. @@ -132,6 +147,10 @@ Gets the port handle to stdin ```scheme > (stdin) ;; => # ``` +### **would-block-object?** +Returns `#t` if the value is an EOF object. + +(eof-object? any/c) -> bool? ### **write-byte** Writes a single byte to an output port. @@ -150,4 +169,5 @@ Writes the contents of a bytevector into an output port. ### **flush-output-port** ### **read-line-from-port** ### **stdout** +### **would-block** ### **write-line!** diff --git a/docs/src/builtins/steel_sets.md b/docs/src/builtins/steel_sets.md index 23eeca3e6..e27ca433f 100644 --- a/docs/src/builtins/steel_sets.md +++ b/docs/src/builtins/steel_sets.md @@ -1,10 +1,78 @@ # steel/sets ### **hashset** +Constructs a new hash set + +#### Examples +```scheme +(hashset 10 20 30 40) +``` +### **hashset->immutable-vector** +Creates an immutable vector from this hashset. The order of the vector is not guaranteed. + +#### Examples +```scheme +(hashset->immutable-vector (hashset 10 20 30)) ;; => '#(10 20 30) +(hashset->immutable-vector (hashset 10 20 30)) ;; => '#(20 10 30) +``` ### **hashset->list** +Creates a list from this hashset. The order of the list is not guaranteed. + +#### Examples +```scheme +(hashset->list (hashset 10 20 30)) ;; => '(10 20 30) +(hashset->list (hashset 10 20 30)) ;; => '(20 10 30) +``` ### **hashset->vector** +Creates a mutable vector from this hashset. The order of the vector is not guaranteed. + +#### Examples +```scheme +(hashset->vector (hashset 10 20 30)) ;; => '#(10 20 30) +(hashset->vector (hashset 10 20 30)) ;; => '#(20 10 30) +``` ### **hashset-clear** +Clears the hashset and returns the passed in hashset. +This first checks if there are no other references to this hashset, +and if there aren't, clears that allocation. Given that there are +functional updates, this is only relevant if there are no more +references to a given hashset, and you want to reuse its allocation. ### **hashset-contains?** +Test if the hashset contains a given element. + +#### Examples +```scheme +(hashset-contains? (hashset 10 20) 10) ;; => #true +(hashset-contains? (hashset 10 20) "foo") ;; => #false +``` ### **hashset-insert** +Insert a new element into the hashset. Returns a hashset. + +#### Examples +```scheme +(define hs (hashset 10 20 30)) +(define updated (hashset-insert hs 40)) +(equal? hs (hashset 10 20 30)) ;; => #true +(equal? updated (hashset 10 20 30 40)) ;; => #true +``` ### **hashset-length** +Get the number of elements in the hashset + +#### Examples +```scheme +(hashset-length (hashset 10 20 30)) ;; => 3 +``` ### **hashset-subset?** +Check if the left set is a subset of the right set + +#### Examples +```scheme +(hashset-subset? (hash 10) (hashset 10 20)) ;; => #true +(hashset-subset? (hash 100) (hashset 30)) ;; => #false +``` ### **list->hashset** +Convert the given list into a hashset. + +#### Examples +```scheme +(list 10 20 30) ;; => (hashset 10 20 30) +``` diff --git a/docs/src/builtins/steel_syntax.md b/docs/src/builtins/steel_syntax.md index 1819ae0d7..16127d480 100644 --- a/docs/src/builtins/steel_syntax.md +++ b/docs/src/builtins/steel_syntax.md @@ -1,4 +1,5 @@ # steel/syntax +### **span-file-id** ### **syntax->datum** ### **syntax-e** ### **syntax-loc** diff --git a/docs/src/builtins/steel_tcp.md b/docs/src/builtins/steel_tcp.md index 9d3d850de..922ecb5bf 100644 --- a/docs/src/builtins/steel_tcp.md +++ b/docs/src/builtins/steel_tcp.md @@ -1,7 +1,10 @@ # steel/tcp ### **tcp-accept** +### **tcp-accept-with-addr** ### **tcp-connect** ### **tcp-listen** -### **tcp-stream-buffered-output-port** -### **tcp-stream-input-port** -### **tcp-stream-output-port** +### **tcp-listener-set-non-blocking!** +### **tcp-stream-buffered-reader** +### **tcp-stream-reader** +### **tcp-stream-set-non-blocking!** +### **tcp-stream-writer** diff --git a/docs/src/builtins/steel_threads.md b/docs/src/builtins/steel_threads.md index 3acf340ae..4f87d851d 100644 --- a/docs/src/builtins/steel_threads.md +++ b/docs/src/builtins/steel_threads.md @@ -10,9 +10,10 @@ Returns `#t` if the value is an empty-channel object. ### **get-tls** Get the value out of the thread local storage slot. ### **lock-acquire!** -Lock the given mutex +Lock the given mutex. Note, this is most likely used as a building block +with the `lock!` function. ### **lock-release!** -Unlock the given mutex +Unlock the given mutex. ### **make-tls** Creates a thread local storage slot. These slots are static, and will _not_ be reclaimed. @@ -28,6 +29,16 @@ Using this directly is not recommended. ### **set-tls!** Set the value in the the thread local storage. Only this thread will see the updates associated with this TLS. +### **spawn-native-thread** +Spawns the given `func` on another thread. It is required that the arity of the +given function be 0. If the arity of the given function cannot be checked until runtime, +the thread will be spawned and the function will fail to execute. + +#### Examples + +```scheme +(define thread (spawn-native-thread (lambda () (displayln "Hello world!")))) +``` ### **thread-finished?** Check if the given thread is finished running. ### **thread-interrupt** @@ -51,8 +62,8 @@ bytecode instruction that is running. ### **channels-receiver** ### **channels-sender** ### **channels/new** +### **current-thread-id** ### **make-channels** -### **spawn-native-thread** ### **spawn-thread!** ### **thread/available-parallelism** ### **thread::current/id** diff --git a/docs/src/builtins/steel_vectors.md b/docs/src/builtins/steel_vectors.md index 0526ba18b..9d2c06765 100644 --- a/docs/src/builtins/steel_vectors.md +++ b/docs/src/builtins/steel_vectors.md @@ -1,4 +1,5 @@ # steel/vectors +### **immutable-vector** ### **make-vector** ### **mut-vec-len** ### **mut-vector-ref** @@ -16,6 +17,8 @@ ### **vec-rest** ### **vector** ### **vector-append!** +### **vector-copy!** +### **vector-fill!** ### **vector-length** ### **vector-push!** ### **vector-ref**