specialized-vectors: add push-new operation that allocates and returns a new struct...

[factor.git] / basis / specialized-vectors / specialized-vectors-docs.factor

diff --git a/basis/specialized-vectors/specialized-vectors-docs.factor b/basis/specialized-vectors/specialized-vectors-docs.factor
index e54f26ac57de6fd3d342fade449ecb7dd74f972c..bd68a3b5335106171dcf151504e30d7e9922ac6b 100644 (file)
--- a/basis/specialized-vectors/specialized-vectors-docs.factor
+++ b/basis/specialized-vectors/specialized-vectors-docs.factor
@@ -1,4 +1,4 @@
-USING: help.markup help.syntax byte-vectors alien byte-arrays ;
+USING: help.markup help.syntax byte-vectors alien byte-arrays classes.struct ;
 IN: specialized-vectors
 
 HELP: SPECIALIZED-VECTOR:
@@ -23,6 +23,20 @@ ARTICLE: "specialized-vector-words" "Specialized vector words"
 }
 "Behind the scenes, these words are placed in a vocabulary named " { $snippet "specialized-vectors.instances.T" } ", however this vocabulary should not be placed in a " { $link POSTPONE: USING: } " form directly. Instead, always use " { $link POSTPONE: SPECIALIZED-VECTOR: } ". This ensures that the vocabulary can get generated the first time it is needed." ;
 
+HELP: push-new
+{ $values { "vector" "a specialized vector of structs" } { "new" "a new value of the specialized vector's type" } }
+{ $description "Grows " { $snippet "vector" } ", increasing its length by one, and outputs a " { $link struct } " object wrapping the newly allocated storage." }
+{ $notes "This word allows struct objects to be streamed into a struct vector efficiently without excessive copying. The typical Factor idiom for pushing a new object onto a vector, when used with struct vectors, will allocate and copy a temporary struct object:"
+{ $code """foo <struct>
+    5 >>a
+    6 >>b
+foo-vector{ } clone push""" } 
+"By using " { $snippet "push-new" } ", the new struct can be allocated directly from the vector and the intermediate copy can be avoided:"
+{ $code """foo-vector{ } clone push-new
+    5 >>a
+    6 >>b
+    drop""" } } ;
+
 ARTICLE: "specialized-vector-c" "Passing specialized vectors to C functions"
 "Each specialized vector has a " { $slot "underlying" } " slot holding a specialized array, which in turn has an " { $slot "underlying" } " slot holding a " { $link byte-array } " with the raw data. Passing a specialized vector as a parameter to a C function call will automatically extract the underlying data. To get at the underlying data directly, call the " { $link >c-ptr } " word on a specialized vector." ;
 
@@ -38,6 +52,10 @@ $nl
     "specialized-vector-words"
     "specialized-vector-c"
 }
+"This vocabulary also contains special vector operations for making efficient use of specialized vector types:"
+{ $subsections
+    push-new
+}
 "The " { $vocab-link "specialized-arrays" } " vocabulary provides a fixed-length version of this abstraction." ;
 
 ABOUT: "specialized-vectors"