;; ;; ;; dyn-vector documentation for the Chicken Scheme module system. ;; (require-library eggdoc) (import eggdoc) (define doc `((eggdoc:begin (name "dyn-vector") (description "Dynamic (dense) vectors based on SRFI-43.") (author (url "http://chicken.wiki.br/users/ivan-raikov" "Ivan Raikov")) (history (version "1.9" "Ported to Chicken 4") (version "1.8" "Build script updated for better cross-platform compatibility") (version "1.7" "eggdoc documentation fix") (version "1.6" "License upgrade to GPL v3") (version "1.5" "Minor updates to the setup script") (version "1.4" "Bug fix in the setup script") (version "1.3" "Added a clarification of how the vector grows [thanks to John Cowan]") (version "1.2" "Bug fix to handle zero-length initial base vector") (version "1.1" "Added optional dflt argument to list->dynvector and dynvector->tabulate") (version "1.0" "Initial release")) (requires (url "vector-lib.html" "vector-lib")) (usage "(require-extension dyn-vector)") (download "dyn-vector.egg") (documentation (p "The dyn-vector library is an implementation of a " "dynamically-growing vector, based on " (url "http://srfi.schemers.org/srfi-43/" "SRFI-43") ". " "An attempt to set the " (tt "i") "'th element of a dynvector of " "underlying size n causes the dynvector to grow to size " (tt "2n") ", " (tt "i+1") ", or " (tt "16") ", whichever is greatest. " "The semantics of this library follow SRFI-43 closely, " "with the exception of the following procedures: " (procedure "dynvector-ref vect i" (p "if the index " (tt "i") " is greater than the current size of the vector, " "this procedure returns the default value specified when " "the dynamic vector was created")) (procedure "dynvector-set! vect i e" (p "if the index " (tt "i") " is greater than the current size of the vector, " "the vector size is increased to " (tt "max(2*N,i+1)") " and the new element is then inserted in the vector")) (procedure "dynvector-clear! vect n" (p "this procedure removes all elements from the dynamic vector, " "and sets the size of the vector to " (tt "n"))) (procedure "dynvector-extend! vect n" (p "this procedure explicitly resizes the dynamic vector " "to the specified size")) (procedure "dynvector-tabulate f len [dflt]" (p "if the optional argument " (tt "dflt") " is specified, " "it is used as default value, otherwise the first element " "in the vector is used as default value")) (procedure "list->dynvector lst [dflt] -> dynvector" (p "if the optional argument " (tt "dflt") " is specified, " "it is used as default value, otherwise the first element " "in the list is used as default value"))) (subsection "Procedures" (procedure "dynvector? x -> boolean" (p "returns " (tt "#t") " if " (tt "x") " is a dynamic vector, " (tt "#f") " otherwise")) (procedure "dynvector-tabulate f len [dflt]" (p "creates a new dynamic vector of length " (tt "len") " and iterates across each index, applying f at each " "iteration to the current index; " "if the optional argument " (tt "dflt") " is specified, " "it is used as default value, otherwise the first element " "in the vector is used as default value")) (procedure "list->dynvector lst [dflt] -> dynvector" (p "creates a dynamic vector with the elements of the given list; " "if the optional argument " (tt "dflt") " is specified, " "it is used as default value, otherwise the first element " "in the vector is used as default value")) (procedure "make-dynvector n default -> dynvector" (p "creates a dynamic vector of length " (tt "n") " and fills it with value " (tt "default"))) (procedure "dynvector-clear! x n -> unspecified" (p "removes all elements from the given dynamic vector, " "and sets the size of the vector to " (tt "n"))) (procedure "dynvector-length x -> integer" (p "returns the length of the given dynamic vector")) (procedure "dynvector-ref x i -> value" (p "returns the element at index " (tt "i") "of the given dynamic vector" (tt "x"))) (procedure "dynvector-set! x i e -> unspecified" (p "updates the element at index " (tt "i") "of the given dynamic vector" (tt "x") "; " "if the index " (tt "i") " is greater than the current size of the vector, " "the vector size is increased to " (tt "max(2*N,i+1)") " and the new element is then inserted in the vector")) (procedure "dynvector-expand! x n -> unspecified" (p "expand the size of the dynamic vector to the given size " (tt "n"))) (procedure "dynvector-for-each f x1 ... -> unspecified" (p "dynamic vector iterator: applies " (tt "f") "to each index in the range " (tt "[0, k)") ", where " (tt "k") " is the length of the smallest " "dynamic vector argument passed, and the respective list of parallel " "elements from " (tt "x1") " ... at that index.")) (procedure "dynvector-map f x1 ... -> dynvector" (p "constructs a new dynamic vector of the shortest size " "of the given dynamic vector; " "each element at index " (tt "i") " of the new dynamic vector " "is mapped from the old vectors by " (tt "f i (dynvector-ref x1 i) ..."))) (procedure "dynvector-copy x -> dynvector" (p "creates a copy of the given dynamic vector")) (procedure "dynvector-fold f initial x1 ... -> state" (p "left-to-right dynamic vector iterator with state. " (tt "f") " is iterated over each index " "in all of the vectors, stopping at the end of the shortest; " (tt "f") " is applied as " (tt "(f i state (dynvector-ref x1 i) ...)") " where state is the current state value, which begins with " (tt "initial") " and becomes whatever " (tt "f") "returns at the respective iteration; " (tt "i") " is the current index")) (procedure "dynvector-fold-right f initial x1 ... -> state" (p "right-to-left dynamic vector iterator with state. " (tt "f") " is iterated over each index " "in all of the vectors, stopping at the end of the shortest; " (tt "f") " is applied as " (tt "(f i state (dynvector-ref x1 i) ...)") " where state is the current state value, which begins with " (tt "initial") " and becomes whatever " (tt "f") "returns at the respective iteration; " (tt "i") " is the current index")) (procedure "dynvector-index pred? x1 ... -> integer or #f" (p "finds and returns the index of the first elements in " (tt "x1 ...") " that satisfy " (tt "pred?") "; if no matching element " "is found by the end of the shortest vector, " (tt "#f") " is returned")) (procedure "dynvector-any pred? x1 ... -> value or #f" (p "finds the first set of elements in " (tt "x1 ... ") "for which " (tt "pred?") " returns a true value. " "If such a parallel set of elements exists, " "this procedure returns the value that " (tt "pred?") "returned for that set of elements")) (procedure "dynvector-every pred? x1 ... -> value or #f" (p "if, for every index " (tt "i") " between 0 and the length " "of the shortest vector argument, the set of elements " (tt "(dynvector-ref x1 i) ...") " satisfies " (tt "pred?") ", this procedure returns the value that " (tt "pred?") "returned for the last set of elements")) (procedure "dynvector->list x1 -> list" (p "returns a list containing all the elements in the given dynamic vector")))) (examples (pre #< (require-extension dyn-vector) csi> (define dv (make-dynvector 1 0)) csi> (dynvector-ref dv 6) 0 csi> (dynvector-set! dv 6 18) csi> (dynvector-ref dv 6) 18 csi> (define dv2 (list->dynvector '(1 2 3))) csi> dv2 #(dynvector 1 2 3) csi> (dynvector-ref dv2 4) 1 csi> (dynvector-clear! dv2 5) csi> (dynvector-for-each (lambda (i x) (print i " = " x)) dv2) 0 = 1 1 = 1 2 = 1 3 = 1 4 = 1 csi> (dynvector-map (lambda (i x) (+ x i)) dv2) #(dynvector 1 2 3 4 5) csi> (dynvector-fold (lambda (i state v) (+ state v)) 0 dv2) 5 EOF )) (license "Parts of this documentation are taken from SRFI-43. The rest was created by Ivan Raikov. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. A full copy of the GPL license can be found at .")))) (if (eggdoc->html doc) (void))