core/splitting/splitting-docs.factor

   1 USING: help.markup help.syntax kernel sequences strings ;
   2 IN: splitting
   3
   4 ARTICLE: "sequences-split" "Splitting sequences"
   5 "Splitting sequences at occurrences of subsequences:"
   6 { $subsections
   7     ?head
   8     ?head-slice
   9     ?tail
  10     ?tail-slice
  11     split1
  12     split1-slice
  13     split1-when
  14     split1-when-slice
  15     split1-last
  16     split1-last-slice
  17     split
  18     split-indices
  19     split-slice
  20     split-when
  21     split-when-slice
  22 }
  23 "Splitting a string into lines:"
  24 { $subsections lines }
  25 "Replacing subsequences with another subsequence:"
  26 { $subsections replace } ;
  27
  28 ABOUT: "sequences-split"
  29
  30 HELP: split1
  31 { $values { "seq" sequence } { "subseq" sequence } { "before" "a new sequence" } { "after" "a new sequence" } }
  32 { $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 } "." } ;
  33
  34 HELP: split1-slice
  35 { $values { "seq" sequence } { "subseq" sequence } { "before-slice" slice } { "after-slice" slice } }
  36 { $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 } "." } ;
  37
  38 HELP: split1-when
  39 { $values { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } { "before" "a new sequence" } { "after" "a new sequence" } }
  40 { $description "Splits " { $snippet "seq" } " at the first occurrence of an element for which " { $snippet "quot" } " gives a true output and outputs the pieces before and after the split." } ;
  41
  42 HELP: split1-when-slice
  43 { $values { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } { "before-slice" slice } { "after-slice" slice } }
  44 { $description "Splits " { $snippet "seq" } " at the first occurrence of an element for which " { $snippet "quot" } " gives a true output 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 } "." } ;
  45
  46 HELP: split1-last
  47 { $values { "seq" sequence } { "subseq" sequence } { "before" "a new sequence" } { "after" "a new sequence" } }
  48 { $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 } "." } ;
  49
  50 HELP: split1-last-slice
  51 { $values { "seq" sequence } { "subseq" sequence } { "before-slice" slice } { "after-slice" slice } }
  52 { $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 } "." } ;
  53
  54 { split1 split1-slice split1-last split1-last-slice } related-words
  55
  56 HELP: split-when
  57 { $values { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } { "pieces" "a new array" } }
  58 { $description "Splits " { $snippet "seq" } " at each occurrence of an element for which " { $snippet "quot" } " gives a true output and outputs an array of pieces. The pieces do not include the elements along which the sequence was split." }
  59 { $examples { $example "USING: ascii kernel prettyprint splitting ;" "\"hello,world-how.are:you\" [ letter? not ] split-when ." "{ \"hello\" \"world\" \"how\" \"are\" \"you\" }" } } ;
  60
  61 HELP: split-when-slice
  62 { $values { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } { "pieces" "a new array" } }
  63 { $description "Splits " { $snippet "seq" } " at each occurrence of an element for which " { $snippet "quot" } " gives a true output and outputs an array of pieces as " { $link slice } "s. The pieces do not include the elements along which the sequence was split." } ;
  64
  65 HELP: split-indices
  66 { $values { "seq" sequence } { "indices" sequence } { "pieces" "a new array" } }
  67 { $description "Splits a sequence at the given indices." }
  68 { $examples
  69   { $example
  70     "USING: prettyprint splitting ;"
  71     "\"hello world\" { 3 6 } split-indices ."
  72     "{ \"hel\" \"lo \" \"world\" }"
  73   }
  74 } ;
  75
  76 HELP: split
  77 { $values { "seq" sequence } { "separators" sequence } { "pieces" "a new array" } }
  78 { $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." }
  79 { $examples { $example "USING: prettyprint splitting ;" "\"hello world-how are you?\" \" -\" split ." "{ \"hello\" \"world\" \"how\" \"are\" \"you?\" }" } } ;
  80
  81 HELP: ?head
  82 { $values { "seq" sequence } { "begin" sequence } { "newseq" "a new sequence" } { "?" boolean } }
  83 { $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 } "." } ;
  84
  85 HELP: ?head-slice
  86 { $values { "seq" sequence } { "begin" sequence } { "newseq" slice } { "?" boolean } }
  87 { $description "Like " { $link ?head } ", except the resulting sequence is a " { $link slice } "." } ;
  88
  89 HELP: ?tail
  90 { $values { "seq" sequence } { "end" sequence } { "newseq" "a new sequence" } { "?" boolean } }
  91 { $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 } "." } ;
  92
  93 HELP: ?tail-slice
  94 { $values { "seq" sequence } { "end" sequence } { "newseq" slice } { "?" boolean } }
  95 { $description "Like " { $link ?tail } ", except the resulting sequence is a " { $link slice } "." } ;
  96
  97 HELP: lines
  98 { $values { "seq" sequence } { "seq'" { $sequence string } } }
  99 { $description "Splits a string along line breaks." }
 100 { $examples
 101     { $example "USING: prettyprint splitting ;" "\"Hello\\r\\nworld\\n\" lines ." "{ \"Hello\" \"world\" }" }
 102 } ;
 103
 104 HELP: replace
 105 { $values { "seq" sequence } { "old" sequence } { "new" sequence } { "new-seq" sequence } }
 106 { $description "Replaces every occurrence of " { $snippet "old" } " with " { $snippet "new" } " in the " { $snippet "seq" } "." }
 107 { $examples
 108     { $example "USING: io splitting ;"
 109                "\"cool example is cool\" \"cool\" \"silly\" replace print"
 110                "silly example is silly"
 111     }
 112 } ;