basis/sequences/windowed/windowed-docs.factor

   1 ! Copyright (C) 2012 Doug Coleman.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel math sequences ;
   4 IN: sequences.windowed
   5
   6 HELP: <windowed-sequence>
   7 { $values
   8     { "sequence" sequence } { "n" sequence }
   9     { "windowed-sequence" windowed-sequence }
  10 }
  11 { $description "Create a new windowed sequence of window size " { $snippet "n" } " over " { $snippet "sequence" } "." } ;
  12
  13 HELP: in-bound
  14 { $values
  15     { "n" integer } { "sequence" sequence }
  16     { "n'" integer }
  17 }
  18 { $description "Clamps an integer from 0 to the sequence length." } ;
  19
  20 HELP: in-bounds
  21 { $values
  22     { "a" sequence } { "b" sequence } { "sequence" sequence }
  23     { "a'" sequence } { "b'" sequence }
  24 }
  25 { $description "Clamps two integers from 0 to the sequence length. While not in bounds for calling " { $link nth } ", these integers are in bounds for calling " { $link <slice> } "." } ;
  26
  27 ARTICLE: "sequences.windowed" "Windowed sequences"
  28
  29 "The " { $vocab-link "sequences.windowed" } " vocabulary provides a read-only virtual sequence whose elements are slices of length " { $snippet "n" } " from the current element looking backwards, inclusive of the current element. Slices may be less than " { $snippet "n" } " elements in length, especially at the head of the sequence, where the first slice will be of length 1." $nl
  30 "Windowed sequences support " { $link nth } " and " { $link length } " from the " { $link "sequence-protocol" } "." $nl
  31 "Creating a windowed sequence:"
  32 { $subsections <windowed-sequence> }
  33 "Helper words for creating bounds-checked slices:"
  34 { $subsections in-bound in-bounds } ;
  35
  36 ABOUT: "sequences.windowed"