basis/struct-arrays/struct-arrays-docs.factor

   1 IN: struct-arrays
   2 USING: classes.struct help.markup help.syntax alien strings math multiline ;
   3
   4 HELP: struct-array
   5 { $class-description "The class of C struct and union arrays."
   6 $nl
   7 "The " { $slot "underlying" } " slot holds a " { $link c-ptr } " with the raw data. This pointer can be passed to C functions." } ;
   8
   9 HELP: <struct-array>
  10 { $values { "length" integer } { "struct-class" struct-class } { "struct-array" struct-array } }
  11 { $description "Creates a new array for holding values of the specified struct type." } ;
  12
  13 HELP: <direct-struct-array>
  14 { $values { "alien" c-ptr } { "length" integer } { "struct-class" struct-class } { "struct-array" struct-array } }
  15 { $description "Creates a new array for holding values of the specified C type, backed by the memory at " { $snippet "alien" } "." } ;
  16
  17 HELP: struct-array-on
  18 { $values { "struct" struct } { "length" integer } { "struct-array" struct-array } }
  19 { $description "Create a new array for holding values of " { $snippet "struct" } "'s C type, backed by the memory starting at " { $snippet "struct" } "'s address." }
  20 { $examples
  21 "This word is useful with the FFI. When a C function has a pointer to a struct as its return type (or a C callback has a struct pointer as an argument type), Factor automatically wraps the pointer in a " { $link struct } " object. If the pointer actually references an array of objects, this word will convert the struct object to a struct array object:"
  22 { $code <" USING: alien.syntax classes.struct struct-arrays ;
  23 IN: scratchpad
  24
  25 STRUCT: zim { zang int } { zung int } ;
  26
  27 FUNCTION: zim* zingle ( ) ; ! Returns a pointer to 20 zims
  28
  29 zingle 20 struct-array-on "> }
  30 } ;
  31
  32 HELP: struct-array{
  33 { $syntax "struct-array{ class value value value ... }" }
  34 { $description "Literal syntax for a " { $link struct-array } " containing structs of the given " { $link struct } " class." } ;
  35
  36 HELP: struct-array@
  37 { $syntax "struct-array@ class alien length" }
  38 { $description "Literal syntax for a " { $link struct-array } " at a particular memory address. The prettyprinter uses this syntax when the memory backing a struct array object is invalid. This syntax should not generally be used in source code." } ;
  39
  40 { POSTPONE: struct-array{ POSTPONE: struct-array@ } related-words
  41
  42 ARTICLE: "struct-arrays" "C struct and union arrays"
  43 "The " { $vocab-link "struct-arrays" } " vocabulary implements arrays specialized for holding C struct and union values."
  44 { $subsection struct-array }
  45 { $subsection <struct-array> }
  46 { $subsection <direct-struct-array> }
  47 { $subsection struct-array-on }
  48 "Struct arrays have literal syntax:"
  49 { $subsection POSTPONE: struct-array{ } ;
  50
  51 ABOUT: "struct-arrays"