-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:
}
"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." ;
"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"
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
PRIVATE>
+: push-new ( vector -- new )
+ [ length ] keep ensure nth-unsafe ; inline
+
: define-vector-vocab ( type -- vocab )
underlying-type
[ specialized-vector-vocab ] [ '[ _ define-vector ] ] bi