basis/sequences/unrolled/unrolled-docs.factor

   1 ! Copyright (C) 2010 Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: assocs help.markup help.syntax kernel math quotations sequences
   4 sequences.private ;
   5 IN: sequences.unrolled
   6
   7 HELP: unrolled-collect
   8 { $values
   9     { "n" integer } { "quot" { $quotation ( n -- value ) } } { "into" sequence }
  10 }
  11 { $description "Unrolled version of " { $link collect } ". " { $snippet "n" } " must be a compile-time constant." } ;
  12
  13 HELP: unrolled-each
  14 { $values
  15     { "seq" sequence } { "len" integer } { "quot" { $quotation ( x -- ) } }
  16 }
  17 { $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 } "." } ;
  18
  19 HELP: unrolled-2each
  20 { $values
  21     { "xseq" sequence } { "yseq" sequence } { "len" integer } { "quot" { $quotation ( x y -- ) } }
  22 }
  23 { $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 } "." } ;
  24
  25 HELP: unrolled-each-index
  26 { $values
  27     { "seq" sequence } { "len" integer } { "quot" { $quotation ( x i -- ) } }
  28 }
  29 { $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 } "." } ;
  30
  31 HELP: unrolled-each-integer
  32 { $values
  33     { "n" integer } { "quot" { $quotation ( i -- ) } }
  34 }
  35 { $description "Unrolled version of " { $link each-integer } ". " { $snippet "n" } " must be a compile-time constant." } ;
  36
  37 HELP: unrolled-map
  38 { $values
  39     { "seq" sequence } { "len" integer } { "quot" { $quotation ( x -- newx ) } }
  40     { "newseq" sequence }
  41 }
  42 { $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 } "." } ;
  43
  44 HELP: unrolled-map-as
  45 { $values
  46     { "seq" sequence } { "len" integer } { "quot" { $quotation ( x -- newx ) } } { "exemplar" sequence }
  47     { "newseq" sequence }
  48 }
  49 { $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 } "." } ;
  50
  51 HELP: unrolled-2map
  52 { $values
  53     { "xseq" sequence } { "yseq" sequence } { "len" integer } { "quot" { $quotation ( x y -- newx ) } } { "newseq" sequence }
  54 }
  55 { $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 } "." } ;
  56
  57 HELP: unrolled-2map-as
  58 { $values
  59     { "xseq" sequence } { "yseq" sequence } { "len" integer } { "quot" { $quotation ( x y -- newx ) } } { "exemplar" sequence } { "newseq" sequence }
  60 }
  61 { $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 } "." } ;
  62
  63 HELP: unrolled-map-index
  64 { $values
  65     { "seq" sequence } { "len" integer } { "quot" { $quotation ( x i -- newx ) } }
  66     { "newseq" sequence }
  67 }
  68 { $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 } "." } ;
  69
  70 HELP: unrolled-map-integers
  71 { $values
  72     { "n" integer } { "quot" { $quotation ( n -- value ) } } { "exemplar" sequence } { "newseq" sequence }
  73 }
  74 { $description "Unrolled version of " { $link map-integers } ". " { $snippet "n" } " must be a compile-time constant." } ;
  75
  76 ARTICLE: "sequences.unrolled" "Unrolled sequence iteration combinators"
  77 "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."
  78 $nl
  79 "Unrolled versions of high-level iteration combinators:"
  80 { $subsections
  81     unrolled-each
  82     unrolled-each-index
  83     unrolled-2each
  84     unrolled-map
  85     unrolled-map-index
  86     unrolled-map-as
  87     unrolled-2map
  88     unrolled-2map-as
  89 }
  90 "Unrolled versions of low-level iteration combinators:"
  91 { $subsections
  92     unrolled-each-integer
  93     unrolled-map-integers
  94     unrolled-collect
  95 } ;
  96
  97 ABOUT: "sequences.unrolled"