From 964327de67db2952e4e37287cd09884c485294df Mon Sep 17 00:00:00 2001
From: Joe Groff <joe@victoria.(none)>
Date: Tue, 8 Jun 2010 13:15:04 -0700
Subject: [PATCH] specialized-vectors: add push-new operation that allocates
 and returns a new struct on the end of a specialized vector

---
 .../specialized-vectors-docs.factor           | 20 ++++++++++++++++++-
 .../specialized-vectors.factor                |  4 ++++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/basis/specialized-vectors/specialized-vectors-docs.factor b/basis/specialized-vectors/specialized-vectors-docs.factor
index e54f26ac57..bd68a3b533 100644
--- 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"
diff --git a/basis/specialized-vectors/specialized-vectors.factor b/basis/specialized-vectors/specialized-vectors.factor
index 3352c226d8..fd36121df1 100644
--- a/basis/specialized-vectors/specialized-vectors.factor
+++ b/basis/specialized-vectors/specialized-vectors.factor
@@ -5,6 +5,7 @@ compiler.units functors growable kernel lexer math namespaces
 parser prettyprint.custom sequences specialized-arrays
 specialized-arrays.private strings vocabs vocabs.parser
 vocabs.generated fry make ;
+FROM: sequences.private => nth-unsafe ;
 QUALIFIED: vectors.functor
 IN: specialized-vectors
 
@@ -50,6 +51,9 @@ INSTANCE: V growable
 
 PRIVATE>
 
+: push-new ( vector -- new )
+    [ length ] keep ensure nth-unsafe ; inline
+
 : define-vector-vocab ( type -- vocab )
     underlying-type
     [ specialized-vector-vocab ] [ '[ _ define-vector ] ] bi
-- 
2.34.1