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 split1-slice }
  12 { $subsection split1-last }
  13 { $subsection split1-last-slice }
  14 { $subsection split }
  15 "Splitting a string into lines:"
  16 { $subsection string-lines } ;
  17
  18 ABOUT: "sequences-split"
  19
  20 HELP: split1
  21 { $values { "seq" "a sequence" } { "subseq" "a sequence" } { "before" "a new sequence" } { "after" "a new sequence" } }
  22 { $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 } "." } ;
  23
  24 HELP: split1-slice
  25 { $values { "seq" "a sequence" } { "subseq" "a sequence" } { "before-slice" slice } { "after-slice" slice } }
  26 { $description "Splits " { $snippet "seq" } " at the first occurrence of " { $snippet "subseq" } ", and outputs the pieces before and after the split as slices. If " { $snippet "subseq" } " does not occur in " { $snippet "seq" } ", then " { $snippet "before" } " is just " { $snippet "seq" } " and " { $snippet "after" } " is " { $link f } "." } ;
  27
  28 HELP: split1-last
  29 { $values { "seq" "a sequence" } { "subseq" "a sequence" } { "before" "a new sequence" } { "after" "a new sequence" } }
  30 { $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 } "." } ;
  31
  32 HELP: split1-last-slice
  33 { $values { "seq" "a sequence" } { "subseq" "a sequence" } { "before-slice" slice } { "after-slice" slice } }
  34 { $description "Splits " { $snippet "seq" } " at the last occurrence of " { $snippet "subseq" } ", and outputs the pieces before and after the split as slices. If " { $snippet "subseq" } " does not occur in " { $snippet "seq" } ", then " { $snippet "before" } " is just " { $snippet "seq" } " and " { $snippet "after" } " is " { $link f } "." } ;
  35
  36 { split1 split1-slice split1-last split1-last-slice } related-words
  37
  38 HELP: split
  39 { $values { "seq" "a sequence" } { "separators" "a sequence" } { "pieces" "a new array" } }
  40 { $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." }
  41 { $examples { $example "USING: prettyprint splitting ;" "\"hello world-how are you?\" \" -\" split ." "{ \"hello\" \"world\" \"how\" \"are\" \"you?\" }" } } ;
  42
  43 HELP: ?head
  44 { $values { "seq" "a sequence" } { "begin" "a sequence" } { "newseq" "a new sequence" } { "?" "a boolean" } }
  45 { $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 } "." } ;
  46
  47 HELP: ?head-slice
  48 { $values { "seq" "a sequence" } { "begin" "a sequence" } { "newseq" slice } { "?" "a boolean" } }
  49 { $description "Like " { $link ?head } ", except the resulting sequence is a " { $link slice } "." } ;
  50
  51 HELP: ?tail
  52 { $values { "seq" "a sequence" } { "end" "a sequence" } { "newseq" "a new sequence" } { "?" "a boolean" } }
  53 { $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 } "." } ;
  54
  55 HELP: ?tail-slice
  56 { $values { "seq" "a sequence" } { "end" "a sequence" } { "newseq" slice } { "?" "a boolean" } }
  57 { $description "Like " { $link ?tail } ", except the resulting sequence is a " { $link slice } "." } ;
  58
  59 HELP: string-lines
  60 { $values { "str" string } { "seq" "a sequence of strings" } }
  61 { $description "Splits a string along line breaks." }
  62 { $examples
  63     { $example "USING: prettyprint splitting ;" "\"Hello\\r\\nworld\\n\" string-lines ." "{ \"Hello\" \"world\" \"\" }" }
  64 } ;