basis/specialized-vectors/specialized-vectors-docs.factor

   1 USING: alien byte-arrays classes.struct help.markup help.syntax ;
   2 IN: specialized-vectors
   3
   4 HELP: SPECIALIZED-VECTOR:
   5 { $syntax "SPECIALIZED-VECTOR: type" }
   6 { $values { "type" "a C type" } }
   7 { $description "Brings a specialized vector for holding values of " { $snippet "type" } " into the vocabulary search path. The generated words are documented in " { $link "specialized-vector-words" } "." } ;
   8
   9 HELP: SPECIALIZED-VECTORS:
  10 { $syntax "SPECIALIZED-VECTORS: type type type ... ;" }
  11 { $values { "type" "a C type" } }
  12 { $description "Brings a set of specialized vectors for holding values of each " { $snippet "type" } " into the vocabulary search path. The generated words are documented in " { $link "specialized-vector-words" } "." } ;
  13
  14 { POSTPONE: SPECIALIZED-VECTOR: POSTPONE: SPECIALIZED-VECTORS: } related-words
  15
  16 ARTICLE: "specialized-vector-words" "Specialized vector words"
  17 "The " { $link POSTPONE: SPECIALIZED-VECTOR: } " parsing word generates the specialized vector type if it hasn't been generated already, and adds the following words to the vocabulary search path, where " { $snippet "T" } " is the C type in question:"
  18 { $table
  19     { { $snippet "T-vector" } { "The class of vectors with elements of type " { $snippet "T" } } }
  20     { { $snippet "<T-vector>" } { "Constructor for vectors with elements of type " { $snippet "T" } "; stack effect " { $snippet "( len -- vector )" } } }
  21     { { $snippet ">T-vector" } { "Converts a sequence into a specialized vector of type " { $snippet "T" } "; stack effect " { $snippet "( seq -- vector )" } } }
  22     { { $snippet "T-vector{" } { "Literal syntax, consists of a series of values terminated by " { $snippet "}" } } }
  23 }
  24 "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." ;
  25
  26 HELP: push-new
  27 { $values { "vector" "a specialized vector of structs" } { "new" "a new value of the specialized vector's type" } }
  28 { $description "Grows " { $snippet "vector" } ", increasing its length by one, and outputs a " { $link struct } " object wrapping the newly allocated storage." }
  29 { $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:"
  30 { $code "foo <struct>
  31     5 >>a
  32     6 >>b
  33 foo-vector{ } clone push" }
  34 "By using " { $snippet "push-new" } ", the new struct can be allocated directly from the vector and the intermediate copy can be avoided:"
  35 { $code "foo-vector{ } clone push-new
  36     5 >>a
  37     6 >>b
  38     drop" } } ;
  39
  40 ARTICLE: "specialized-vector-c" "Passing specialized vectors to C functions"
  41 "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." ;
  42
  43 ARTICLE: "specialized-vectors" "Specialized vectors"
  44 "The " { $vocab-link "specialized-vectors" } " vocabulary implements resizable sequence types for storing machine values in a space-efficient manner without boxing."
  45 $nl
  46 "A specialized vector type needs to be generated for each element type. This is done with parsing words:"
  47 { $subsections
  48     POSTPONE: SPECIALIZED-VECTOR:
  49     POSTPONE: SPECIALIZED-VECTORS:
  50 }
  51 { $subsections
  52     "specialized-vector-words"
  53     "specialized-vector-c"
  54 }
  55 "This vocabulary also contains special vector operations for making efficient use of specialized vector types:"
  56 { $subsections
  57     push-new
  58 }
  59 "The " { $vocab-link "specialized-arrays" } " vocabulary provides a fixed-length version of this abstraction." ;
  60
  61 ABOUT: "specialized-vectors"