basis/sequences/unrolled/unrolled-docs.factor

   1 ! Copyright (C) 2010 Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax math sequences sequences.private ;
   4 IN: sequences.unrolled
   5
   6 HELP: unrolled-collect
   7 { $values
   8     { "n" integer } { "quot" { $quotation ( n -- value ) } } { "into" sequence }
   9 }
  10 { $description "Unrolled version of " { $link collect } ". " { $snippet "n" } " must be a compile-time constant." } ;
  11
  12 HELP: unrolled-each
  13 { $values
  14     { "seq" sequence } { "len" integer } { "quot" { $quotation ( x -- ) } }
  15 }
  16 { $description "Unrolled version of " { $link each } " that iterates over the first " { $snippet "len" } " elements of " { $snippet "seq" } ". " { $snippet "len" } " must be a compile-time constant. If " { $snippet "seq" } " has fewer than " { $snippet "len" } " elements, raises an " { $link unrolled-bounds-error } "." } ;
  17
  18 HELP: unrolled-2each
  19 { $values
  20     { "xseq" sequence } { "yseq" sequence } { "len" integer } { "quot" { $quotation ( x y -- ) } }
  21 }
  22 { $description "Unrolled version of " { $link 2each } " that iterates over the first " { $snippet "len" } " elements of " { $snippet "xseq" } " and " { $snippet "yseq" } ". " { $snippet "len" } " must be a compile-time constant. If " { $snippet "seq" } " has fewer than " { $snippet "len" } " elements, raises an " { $link unrolled-bounds-error } "." } ;
  23
  24 HELP: unrolled-each-index
  25 { $values
  26     { "seq" sequence } { "len" integer } { "quot" { $quotation ( x i -- ) } }
  27 }
  28 { $description "Unrolled version of " { $link each-index } " that iterates over the first " { $snippet "len" } " elements of " { $snippet "seq" } ". " { $snippet "len" } " must be a compile-time constant. If " { $snippet "seq" } " has fewer than " { $snippet "len" } " elements, raises an " { $link unrolled-bounds-error } "." } ;
  29
  30 HELP: unrolled-each-integer
  31 { $values
  32     { "n" integer } { "quot" { $quotation ( i -- ) } }
  33 }
  34 { $description "Unrolled version of " { $link each-integer } ". " { $snippet "n" } " must be a compile-time constant." } ;
  35
  36 HELP: unrolled-map
  37 { $values
  38     { "seq" sequence } { "len" integer } { "quot" { $quotation ( x -- newx ) } }
  39     { "newseq" sequence }
  40 }
  41 { $description "Unrolled version of " { $link map } " that maps over the first " { $snippet "len" } " elements of " { $snippet "seq" } ". " { $snippet "len" } " must be a compile-time constant. If " { $snippet "seq" } " has fewer than " { $snippet "len" } " elements, raises an " { $link unrolled-bounds-error } "." } ;
  42
  43 HELP: unrolled-map-as
  44 { $values
  45     { "seq" sequence } { "len" integer } { "quot" { $quotation ( x -- newx ) } } { "exemplar" sequence }
  46     { "newseq" sequence }
  47 }
  48 { $description "Unrolled version of " { $link map-as } " that maps over the first " { $snippet "len" } " elements of " { $snippet "seq" } ". " { $snippet "len" } " must be a compile-time constant. If " { $snippet "seq" } " has fewer than " { $snippet "len" } " elements, raises an " { $link unrolled-bounds-error } "." } ;
  49
  50 HELP: unrolled-2map
  51 { $values
  52     { "xseq" sequence } { "yseq" sequence } { "len" integer } { "quot" { $quotation ( x y -- newx ) } } { "newseq" sequence }
  53 }
  54 { $description "Unrolled version of " { $link 2map } " that iterates over the first " { $snippet "len" } " elements of " { $snippet "xseq" } " and " { $snippet "yseq" } ". " { $snippet "len" } " must be a compile-time constant. If " { $snippet "seq" } " has fewer than " { $snippet "len" } " elements, raises an " { $link unrolled-bounds-error } "." } ;
  55
  56 HELP: unrolled-2map-as
  57 { $values
  58     { "xseq" sequence } { "yseq" sequence } { "len" integer } { "quot" { $quotation ( x y -- newx ) } } { "exemplar" sequence } { "newseq" sequence }
  59 }
  60 { $description "Unrolled version of " { $link 2map-as } " that iterates over the first " { $snippet "len" } " elements of " { $snippet "xseq" } " and " { $snippet "yseq" } ". " { $snippet "len" } " must be a compile-time constant. If " { $snippet "seq" } " has fewer than " { $snippet "len" } " elements, raises an " { $link unrolled-bounds-error } "." } ;
  61
  62 HELP: unrolled-map-index
  63 { $values
  64     { "seq" sequence } { "len" integer } { "quot" { $quotation ( x i -- newx ) } }
  65     { "newseq" sequence }
  66 }
  67 { $description "Unrolled version of " { $link map-index } " that maps over the first " { $snippet "len" } " elements of " { $snippet "seq" } ". " { $snippet "len" } " must be a compile-time constant. If " { $snippet "seq" } " has fewer than " { $snippet "len" } " elements, raises an " { $link unrolled-bounds-error } "." } ;
  68
  69 HELP: unrolled-map-integers
  70 { $values
  71     { "n" integer } { "quot" { $quotation ( n -- value ) } } { "exemplar" sequence } { "newseq" sequence }
  72 }
  73 { $description "Unrolled version of " { $link map-integers } ". " { $snippet "n" } " must be a compile-time constant." } ;
  74
  75 ARTICLE: "sequences.unrolled" "Unrolled sequence iteration combinators"
  76 "The " { $vocab-link "sequences.unrolled" } " vocabulary provides versions of some of the " { $link "sequences-combinators" } " that unroll their loops, that is, expand to a constant number of repetitions of a quotation rather than an explicit loop. These unrolled combinators all require a constant integer value to indicate the number of unrolled iterations to perform."
  77 $nl
  78 "Unrolled versions of high-level iteration combinators:"
  79 { $subsections
  80     unrolled-each
  81     unrolled-each-index
  82     unrolled-2each
  83     unrolled-map
  84     unrolled-map-index
  85     unrolled-map-as
  86     unrolled-2map
  87     unrolled-2map-as
  88 }
  89 "Unrolled versions of low-level iteration combinators:"
  90 { $subsections
  91     unrolled-each-integer
  92     unrolled-map-integers
  93     unrolled-collect
  94 } ;
  95
  96 ABOUT: "sequences.unrolled"