factor: trim using lists

[factor.git] / basis / db / tuples / tuples-docs.factor

diff --git a/basis/db/tuples/tuples-docs.factor b/basis/db/tuples/tuples-docs.factor
index bf467991f5f7a2e69c74e7ddd24de8a49447c4e5..dd4837adae6194930c866cd028804b504794c864 100644 (file)
--- a/basis/db/tuples/tuples-docs.factor
+++ b/basis/db/tuples/tuples-docs.factor
@@ -1,7 +1,8 @@
 ! Copyright (C) 2008 Doug Coleman.
+! Copyright (C) 2018 Alexander Ilin.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: classes help.markup help.syntax io.streams.string kernel
-quotations sequences strings math db.types db.tuples.private db ;
+USING: classes db db.tuples.private db.types help.markup
+help.syntax kernel math quotations sequences strings ;
 IN: db.tuples
 
 HELP: random-id-generator
@@ -138,7 +139,18 @@ HELP: delete-tuples
 { $description "Uses the " { $snippet "tuple" } " as an exemplar object and deletes any objects that have the same slots set. If a slot is not " { $link f } ", then it is used to generate an SQL statement that deletes tuples." }
 { $warning "This word will delete your data." } ;
 
-{ insert-tuple update-tuple update-tuples delete-tuples } related-words
+HELP: reject-tuples
+{ $values
+     { "query/tuple" tuple }
+     { "quot" { $quotation ( tuple -- ? ) } } }
+{ $description "An SQL query is constructed from the slots of the exemplar tuple that are not " { $link f } ". The " { $snippet "quot" } " is applied to each tuple from the database that matches the query, and if it returns a true value, the row is deleted from the database."
+$nl
+"The word is equivalent to the following code:"
+{ $code "query/tuple select-tuples quot filter [ delete-tuples ] each" }
+"The difference is that " { $snippet "reject-tuples" } " handles query results one by one, thus avoiding the overhead of allocating the intermediate array of tuples, which " { $link select-tuples } " would do. This is important when processing large amounts of data in limited memory." }
+{ $warning "This word will delete your data." } ;
+
+{ insert-tuple update-tuple update-tuples delete-tuples reject-tuples } related-words
 
 HELP: each-tuple
 { $values
@@ -199,7 +211,10 @@ ARTICLE: "db-tuples-words" "High-level tuple/database words"
     update-tuples
 }
 "Deleting tuples:"
-{ $subsections delete-tuples }
+{ $subsections
+    delete-tuples
+    reject-tuples
+}
 "Querying tuples:"
 { $subsections
     each-tuple
@@ -231,7 +246,7 @@ ARTICLE: "db-tuples-tutorial" "Tuple database tutorial"
 "Let's make a tuple and store it in a database. To follow along, click on each code example and run it in the listener. If you forget to run an example, just start at the top and run them all again in order." $nl
 "We're going to store books in this tutorial."
 { $code "TUPLE: book id title author date-published edition cover-price condition ;" }
-"The title, author, and publisher should be strings; the date-published a timestamp; the edition an integer; the cover-price a float. These are the Factor types for which we will need to look up the corresponding " { $link "db.types" } ". " $nl
+"The title, author, and publisher should be strings; the date-published a timestamp; the edition an integer; the cover-price a float. These are the Factor types for which we will need to look up the corresponding " { $link "db.types" } "." $nl
 "To actually bind the tuple slots to the database types, we'll use " { $link define-persistent } "."
 { $code
 "USING: db.tuples db.types ;