From 66f5694462f15a4a2d5641fa04b6768cb4888a43 Mon Sep 17 00:00:00 2001 From: Doug Coleman Date: Sat, 17 Jan 2009 22:15:57 -0600 Subject: [PATCH 1/2] document more core/ words --- core/assocs/assocs-docs.factor | 7 ++++ core/byte-arrays/byte-arrays-docs.factor | 4 +++ core/math/math-docs.factor | 6 +++- core/sequences/sequences-docs.factor | 46 ++++++++++++++++++++++-- 4 files changed, 60 insertions(+), 3 deletions(-) diff --git a/core/assocs/assocs-docs.factor b/core/assocs/assocs-docs.factor index 2f486cd948..627d4aeb80 100644 --- a/core/assocs/assocs-docs.factor +++ b/core/assocs/assocs-docs.factor @@ -115,6 +115,7 @@ $nl { $subsection assoc-map } { $subsection assoc-push-if } { $subsection assoc-filter } +{ $subsection assoc-filter-as } { $subsection assoc-contains? } { $subsection assoc-all? } "Additional combinators:" @@ -232,6 +233,12 @@ HELP: assoc-filter { $values { "assoc" assoc } { "quot" { $quotation "( key value -- ? )" } } { "subassoc" "a new assoc" } } { $description "Outputs an assoc of the same type as " { $snippet "assoc" } " consisting of all entries for which the predicate quotation yields true." } ; +HELP: assoc-filter-as +{ $values { "assoc" assoc } { "quot" { $quotation "( key value -- ? )" } } { "exemplar" assoc } { "subassoc" "a new assoc" } } +{ $description "Outputs an assoc of the same type as " { $snippet "exemplar" } " consisting of all entries for which the predicate quotation yields true." } ; + +{ assoc-filter assoc-filter-as } related-words + HELP: assoc-contains? { $values { "assoc" assoc } { "quot" { $quotation "( key value -- ? )" } } { "?" "a boolean" } } { $description "Tests if the assoc contains an entry satisfying a predicate by applying the quotation to each entry in turn. Iteration stops if an entry is found for which the quotation outputs a true value." } ; diff --git a/core/byte-arrays/byte-arrays-docs.factor b/core/byte-arrays/byte-arrays-docs.factor index 25bff0fce5..f1d94a46f7 100644 --- a/core/byte-arrays/byte-arrays-docs.factor +++ b/core/byte-arrays/byte-arrays-docs.factor @@ -30,6 +30,10 @@ HELP: ( n -- byte-array ) { $values { "n" "a non-negative integer" } { "byte-array" "a new byte array" } } { $description "Creates a new byte array holding " { $snippet "n" } " bytes." } ; +HELP: (byte-array) +{ $values { "n" "a non-negative integer" } { "byte-array" "a new byte array" } } +{ $description "Creates a new byte array with unspecified contents of length " { $snippet "n" } " bytes." } ; + HELP: >byte-array { $values { "seq" "a sequence" } { "byte-array" byte-array } } { $description diff --git a/core/math/math-docs.factor b/core/math/math-docs.factor index 2f7ab75103..348d27ba0f 100644 --- a/core/math/math-docs.factor +++ b/core/math/math-docs.factor @@ -1,5 +1,5 @@ USING: help.markup help.syntax kernel sequences quotations -math.private ; +math.private byte-arrays io.binary ; IN: math HELP: number= @@ -306,6 +306,10 @@ HELP: find-last-integer { $description "Applies the quotation to each integer from " { $snippet "n" } " down to 0, inclusive. Iteration stops when the quotation outputs a true value or 0 is reached. If the quotation yields a true value for some integer, the word outputs that integer. Otherwise, the word outputs " { $link f } "." } { $notes "This word is used to implement " { $link find-last } "." } ; +HELP: byte-array>bignum +{ $values { "byte-array" byte-array } { "n" integer } } +{ $description "Converts a byte-array, interpreted as little-endian, into a bignum integer. User code should call " { $link >le } " or " { $link >be } " instead." } ; + ARTICLE: "division-by-zero" "Division by zero" "Floating point division never raises an error if the denominator is zero. This means that if at least one of the two inputs to " { $link / } ", " { $link /f } " or " { $link mod } " is a float, the result will be a floating point infinity or not a number value." $nl diff --git a/core/sequences/sequences-docs.factor b/core/sequences/sequences-docs.factor index 0b9dbcdfa7..1aeed75470 100644 --- a/core/sequences/sequences-docs.factor +++ b/core/sequences/sequences-docs.factor @@ -679,12 +679,28 @@ HELP: append } } ; +HELP: append-as +{ $values { "seq1" sequence } { "seq2" sequence } { "exemplar" sequence } { "newseq" sequence } } +{ $description "Outputs a new sequence of the same type as " { $snippet "exemplar" } " consisting of the elements of " { $snippet "seq1" } " followed by " { $snippet "seq2" } "." } +{ $errors "Throws an error if " { $snippet "seq1" } " or " { $snippet "seq2" } " contain elements not permitted in sequences of the same class as " { $snippet "exemplar" } "." } +{ $examples + { $example "USING: prettyprint sequences ;" + "{ 1 2 } B{ 3 4 } B{ } append-as ." + "B{ 1 2 3 4 }" + } + { $example "USING: prettyprint sequences strings ;" + "\"go\" \"ing\" SBUF\" \" append-as ." + "SBUF\" going\"" + } +} ; + +{ append append-as } related-words + HELP: prepend { $values { "seq1" sequence } { "seq2" sequence } { "newseq" sequence } } { $description "Outputs a new sequence of the same type as " { $snippet "seq2" } " consisting of the elements of " { $snippet "seq2" } " followed by " { $snippet "seq1" } "." } { $errors "Throws an error if " { $snippet "seq1" } " contains elements not permitted in sequences of the same class as " { $snippet "seq2" } "." } -{ $examples - { $example "USING: prettyprint sequences ;" +{ $examples { $example "USING: prettyprint sequences ;" "{ 1 2 } B{ 3 4 } prepend ." "B{ 3 4 1 2 }" } @@ -705,6 +721,19 @@ HELP: 3append } } ; +HELP: 3append-as +{ $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "exemplar" sequence } { "newseq" sequence } } +{ $description "Outputs a new sequence consisting of the elements of " { $snippet "seq1" } ", " { $snippet "seq2" } " and " { $snippet "seq3" } " in turn of the same type as " { $snippet "exemplar" } "." } +{ $errors "Throws an error if " { $snippet "seq1" } ", " { $snippet "seq2" } ", or " { $snippet "seq3" } " contain elements not permitted in sequences of the same class as " { $snippet "exemplar" } "." } +{ $examples + { $example "USING: prettyprint sequences ;" + "\"a\" \"b\" \"c\" SBUF\" \" 3append-as ." + "SBUF\" abc\"" + } +} ; + +{ 3append 3append-as } related-words + HELP: surround { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "newseq" sequence } } { $description "Outputs a new sequence with " { $snippet "seq1" } " inserted between " { $snippet "seq2" } " and " { $snippet "seq3" } "." } @@ -891,6 +920,16 @@ HELP: produce { $unchecked-example "USING: kernel prettyprint random sequences ;" "[ 10 random dup 1 > ] [ ] [ drop ] produce ." "{ 8 2 2 9 }" } } ; +HELP: produce-as +{ $values { "pred" { $quotation "( -- ? )" } } { "quot" { $quotation "( -- obj )" } } { "tail" "a quotation" } { "exemplar" sequence } { "seq" "a sequence" } } +{ $description "Calls " { $snippet "pred" } " repeatedly. If the predicate yields " { $link f } ", stops, otherwise, calls " { $snippet "quot" } " to yield a value. Values are accumulated and returned in a sequence of type " { $snippet "exemplar" } " at the end." } +{ $examples + "The following example divides a number by two until we reach zero, and accumulates intermediate results:" + { $example "USING: kernel math prettyprint sequences ;" "1337 [ dup 0 > ] [ 2/ dup ] [ ] V{ } produce-as nip ." "V{ 668 334 167 83 41 20 10 5 2 1 0 }" } + "The " { $snippet "tail" } " quotation is used when the predicate produces more than one output value. In this case, we have to drop this value even if the predicate fails in order for stack inference to calculate a stack effect for the " { $link produce } " call:" + { $unchecked-example "USING: kernel prettyprint random sequences ;" "[ 10 random dup 1 > ] [ ] [ drop ] B{ } produce-as ." "B{ 8 2 2 9 }" } +} ; + HELP: sigma { $values { "seq" sequence } { "quot" quotation } { "n" number } } { $description "Like map sum, but without creating an intermediate sequence." } @@ -1359,8 +1398,10 @@ ARTICLE: "sequences-reshape" "Reshaping sequences" ARTICLE: "sequences-appending" "Appending sequences" { $subsection append } +{ $subsection append-as } { $subsection prepend } { $subsection 3append } +{ $subsection 3append-as } { $subsection surround } { $subsection glue } { $subsection concat } @@ -1417,6 +1458,7 @@ ARTICLE: "sequences-combinators" "Sequence combinators" { $subsection map-index } { $subsection accumulate } { $subsection produce } +{ $subsection produce-as } "Filtering:" { $subsection push-if } { $subsection filter } From df7ad34db205028bf3b29b943f4cce02ea849ca6 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Sun, 18 Jan 2009 17:28:36 -0600 Subject: [PATCH 2/2] Credit where credit is due --- basis/unix/authors.txt | 1 + basis/unix/unix.factor | 1 + 2 files changed, 2 insertions(+) diff --git a/basis/unix/authors.txt b/basis/unix/authors.txt index 1901f27a24..e1907c6d91 100644 --- a/basis/unix/authors.txt +++ b/basis/unix/authors.txt @@ -1 +1,2 @@ Slava Pestov +Eduardo Cavazos diff --git a/basis/unix/unix.factor b/basis/unix/unix.factor index 52e7473800..c2b5ad4ea4 100644 --- a/basis/unix/unix.factor +++ b/basis/unix/unix.factor @@ -1,4 +1,5 @@ ! Copyright (C) 2005, 2008 Slava Pestov. +! Copyright (C) 2008 Eduardo Cavazos. ! See http://factorcode.org/license.txt for BSD license. USING: alien alien.c-types alien.syntax kernel libc sequences continuations byte-arrays strings math namespaces