core/splitting/splitting-docs.factor

   1 USING: help.markup help.syntax sequences strings ;
   2 IN: splitting
   3
   4 ARTICLE: "sequences-split" "Splitting sequences"
   5 "Splitting sequences at occurrences of subsequences:"
   6 { $subsection ?head }
   7 { $subsection ?head-slice }
   8 { $subsection ?tail }
   9 { $subsection ?tail-slice }
  10 { $subsection split1 }
  11 { $subsection split }
  12 "Grouping elements:"
  13 { $subsection group }
  14 "A virtual sequence for grouping elements:"
  15 { $subsection groups }
  16 { $subsection <groups> }
  17 { $subsection <sliced-groups> }
  18 "Splitting a string into lines:"
  19 { $subsection string-lines } ;
  20
  21 ABOUT: "sequences-split"
  22
  23 HELP: split1
  24 { $values { "seq" "a sequence" } { "subseq" "a sequence" } { "before" "a new sequence" } { "after" "a new sequence" } }
  25 { $description "Splits " { $snippet "seq" } " at the first occurrence of " { $snippet "subseq" } ", and outputs the pieces before and after the split. If " { $snippet "subseq" } " does not occur in " { $snippet "seq" } ", then " { $snippet "before" } " is just " { $snippet "seq" } " and " { $snippet "after" } " is " { $link f } "." } ;
  26
  27 HELP: last-split1
  28 { $values { "seq" "a sequence" } { "subseq" "a sequence" } { "before" "a new sequence" } { "after" "a new sequence" } }
  29 { $description "Splits " { $snippet "seq" } " at the last occurrence of " { $snippet "subseq" } ", and outputs the pieces before and after the split. If " { $snippet "subseq" } " does not occur in " { $snippet "seq" } ", then " { $snippet "before" } " is just " { $snippet "seq" } " and " { $snippet "after" } " is " { $link f } "." } ;
  30
  31 { split1 last-split1 } related-words
  32
  33 HELP: split
  34 { $values { "seq" "a sequence" } { "separators" "a sequence" } { "pieces" "a new array" } }
  35 { $description "Splits " { $snippet "seq" } " at each occurrence of an element of " { $snippet "separators" } ", and outputs an array of pieces. The pieces do not include the elements along which the sequence was split." }
  36 { $examples { $example "USE: splitting" "\"hello world-how are you?\" \" -\" split ." "{ \"hello\" \"world\" \"how\" \"are\" \"you?\" }" } } ;
  37
  38 HELP: groups
  39 { $class-description "Instances are virtual sequences whose elements are fixed-length subsequences or slices of an underlying sequence. Groups are mutable and resizable if the underlying sequence is mutable and resizable, respectively."
  40 $nl
  41 "New groups are created by calling " { $link <groups> } " and " { $link <sliced-groups> } "." }
  42 { $see-also group } ;
  43
  44 HELP: group
  45 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "array" "a sequence of sequences" } }
  46 { $description "Splits the sequence into groups of " { $snippet "n" } " elements and collects the groups into a new array." }
  47 { $notes "If the sequence length is not a multiple of " { $snippet "n" } ", the final subsequence in the list will be shorter than " { $snippet "n" } " elements." } ;
  48
  49 HELP: <groups>
  50 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "groups" groups } }
  51 { $description "Outputs a virtual sequence whose elements are subsequences consisting of groups of " { $snippet "n" } " elements from the underlying sequence." }
  52 { $examples
  53     { $example
  54         "USE: splitting"
  55         "9 >array 3 <groups> dup reverse-here concat >array ." "{ 6 7 8 3 4 5 0 1 2 }"
  56     }
  57 } ;
  58
  59 HELP: <sliced-groups>
  60 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "groups" groups } }
  61 { $description "Outputs a virtual sequence whose elements are slices consisting of groups of " { $snippet "n" } " elements from the underlying sequence." }
  62 { $examples
  63     { $example
  64         "USE: splitting"
  65         "9 >array 3 <sliced-groups>"
  66         "dup [ reverse-here ] each concat >array ."
  67         "{ 2 1 0 5 4 3 8 7 6 }"
  68     }
  69 } ;
  70
  71 { group <groups> <sliced-groups> } related-words
  72
  73 HELP: ?head
  74 { $values { "seq" "a sequence" } { "begin" "a sequence" } { "newseq" "a new sequence" } { "?" "a boolean" } }
  75 { $description "Tests if " { $snippet "seq" } " starts with " { $snippet "begin" } ". If there is a match, outputs the subrange of " { $snippet "seq" } " excluding " { $snippet "begin" } ", and " { $link t } ". If there is no match, outputs " { $snippet "seq" } " and " { $link f } "." } ;
  76
  77 HELP: ?head-slice
  78 { $values { "seq" "a sequence" } { "begin" "a sequence" } { "newseq" slice } { "?" "a boolean" } }
  79 { $description "Like " { $link ?head } ", except the resulting sequence is a " { $link slice } "." } ;
  80
  81 HELP: ?tail
  82 { $values { "seq" "a sequence" } { "end" "a sequence" } { "newseq" "a new sequence" } { "?" "a boolean" } }
  83 { $description "Tests if " { $snippet "seq" } " ends with " { $snippet "end" } ". If there is a match, outputs the subrange of " { $snippet "seq" } " excluding " { $snippet "end" } ", and " { $link t } ". If there is no match, outputs " { $snippet "seq" } " and " { $link f } "." } ;
  84
  85 HELP: ?tail-slice
  86 { $values { "seq" "a sequence" } { "end" "a sequence" } { "newseq" slice } { "?" "a boolean" } }
  87 { $description "Like " { $link ?tail } ", except the resulting sequence is a " { $link slice } "." } ;
  88
  89 HELP: string-lines
  90 { $values { "str" string } { "seq" "a sequence of strings" } }
  91 { $description "Splits a string along line breaks." }
  92 { $examples
  93     { $example "USE: splitting" "\"Hello\\r\\nworld\\n\" string-lines ." "{ \"Hello\" \"world\" \"\" }" }
  94 } ;