core/collections/slicing.facts

   1 USING: help sequences ;
   2
   3 HELP: head-slice
   4 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "slice" "a slice" } }
   5 { $description "Outputs a virtual sequence sharing storage with the first " { $snippet "n" } " elements of the input sequence." }
   6 { $errors "Throws an error if the index is out of bounds." } ;
   7
   8 HELP: tail-slice
   9 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "slice" "a slice" } }
  10 { $description "Outputs a virtual sequence sharing storage with all elements up to the " { $snippet "n" } "th index of the input sequence." }
  11 { $errors "Throws an error if the index is out of bounds." } ;
  12
  13 HELP: head-slice*
  14 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "slice" "a slice" } }
  15 { $description "Outputs a virtual sequence sharing storage with all elements of " { $snippet "seq" } " until the " { $snippet "n" } "th element from the end. In other words, it outputs a sequence of the first " { $snippet "l-n" } " elements of the input sequence, where " { $snippet "l" } " is its length." }
  16 { $errors "Throws an error if the index is out of bounds." } ;
  17
  18 HELP: tail-slice*
  19 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "slice" "a slice" } }
  20 { $description "Outputs a virtual sequence sharing storage with the last " { $snippet "n" } " elements of the input sequence." }
  21 { $errors "Throws an error if the index is out of bounds." } ;
  22
  23 HELP: subseq
  24 { $values { "m" "a non-negative integer" } { "n" "a non-negative integer" } { "seq" "a sequence" } { "subseq" "a new sequence" } }
  25 { $description "Outputs a new sequence consisting of all elements starting from and including " { $snippet "m" } ", and up to but not including " { $snippet "n" } "." }
  26 { $errors "Throws an error if " { $snippet "m" } " or " { $snippet "n" } " is out of bounds." } ;
  27
  28 HELP: head
  29 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "headseq" "a new sequence" } }
  30 { $description "Outputs a new sequence consisting of the first " { $snippet "n" } " elements of the input sequence." }
  31 { $errors "Throws an error if the index is out of bounds." } ;
  32
  33 HELP: tail
  34 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "tailseq" "a new sequence" } }
  35 { $description "Outputs a new sequence consisting of the input sequence with the first n items removed." }
  36 { $errors "Throws an error if the index is out of bounds." } ;
  37
  38 HELP: head*
  39 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "headseq" "a new sequence" } }
  40 { $description "Outputs a new sequence consisting of all elements of " { $snippet "seq" } " until the " { $snippet "n" } "th element from the end. In other words, it outputs a sequence of the first " { $snippet "l-n" } " elements of the input sequence, where " { $snippet "l" } " is its length." }
  41 { $errors "Throws an error if the index is out of bounds." } ;
  42
  43 HELP: tail*
  44 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "tailseq" "a new sequence" } }
  45 { $description "Outputs a new sequence consisting of the last " { $snippet "n" } " elements of the input sequence." }
  46 { $errors "Throws an error if the index is out of bounds." } ;
  47
  48 HELP: head?
  49 { $values { "seq" "a sequence" } { "begin" "a sequence" } { "?" "a boolean" } }
  50 { $description "Tests if " { $snippet "seq" } " starts with " { $snippet "begin" } ". If " { $snippet "begin" } " is longer than " { $snippet "seq" } ", this word outputs " { $link f } "." } ;
  51
  52 HELP: tail?
  53 { $values { "seq" "a sequence" } { "begin" "a sequence" } { "?" "a boolean" } }
  54 { $description "Tests if " { $snippet "seq" } " ends with " { $snippet "end" } ". If " { $snippet "end" } " is longer than " { $snippet "seq" } ", this word outputs " { $link f } "." } ;
  55
  56 HELP: ?head
  57 { $values { "seq" "a sequence" } { "begin" "a sequence" } { "newseq" "a new sequence" } { "?" "a boolean" } }
  58 { $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 } "." } ;
  59
  60 HELP: ?tail
  61 { $values { "seq" "a sequence" } { "end" "a sequence" } { "newseq" "a new sequence" } { "?" "a boolean" } }
  62 { $description "Tests if " { $snippet "seq" } " ends with " { $snippet "end" } ". 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 } "." } ;
  63
  64 HELP: replace-slice
  65 { $values { "new" "a sequence" } { "seq" "a sequence" } { "m" "a non-negative integer" } { "n" "a non-negative integer" } { "replaced" "a new sequence" } }
  66 { $description "Outputs a new sequence consisting of the elements of " { $snippet "seq" } ", with the range from " { $snippet "m" } " to " { $snippet "n" } " replaced by " { $snippet "new" } "." }
  67 { $errors "Throws an error if " { $snippet "new" } " contains elements whose types are not permissible in sequences of the same class as " { $snippet "seq" } "." } ;
  68
  69 HELP: remove-nth
  70 { $values { "n" "a non-negative integer" } { "seq" "a sequence" } { "newseq" "a new sequence" } }
  71 { $description "Outputs a new sequence with the same elements as " { $snippet "seq" } " except omitting the " { $snippet "n" } "th element." }
  72 { $examples
  73     { $example "2 { + - = * / } remove-nth ." "{ + - * / }" }
  74 } ;
  75
  76 HELP: (cut)
  77 { $values { "n" "a non-negative integer" } { "seq" "a sequence" } { "before" "a sequence" } { "after" "a slice" } }
  78 { $description "Outputs a pair of sequences, where " { $snippet "before" } " consists of the first " { $snippet "n" } " elements of " { $snippet "seq" } " and has the same type, while " { $snippet "after" } " is a slice of the remaining elements." }
  79 { $notes "Unlike " { $link cut } ", the run time of this word is proportional to the length of " { $snippet "before" } ", not " { $snippet "after" } ", so it is suitable for use in an iterative algorithm which cuts successive pieces off a sequence." } ;
  80
  81 HELP: cut
  82 { $values { "n" "a non-negative integer" } { "seq" "a sequence" } { "before" "a sequence" } { "after" "a sequence" } }
  83 { $description "Outputs a pair of sequences, where " { $snippet "before" } " consists of the first " { $snippet "n" } " elements of " { $snippet "seq" } ", while " { $snippet "after" } " holds the remaining elements. Both output sequences have the same type as " { $snippet "seq" } "." }
  84 { $notes "Since this word copies the entire tail of the sequence, it should not be used in a loop. If this is important, consider using " { $link (cut) } " instead, since it returns a slice for the tail instead of copying." } ;
  85
  86 HELP: cut*
  87 { $values { "n" "a non-negative integer" } { "seq" "a sequence" } { "before" "a sequence" } { "after" "a sequence" } }
  88 { $description "Outputs a pair of sequences, where " { $snippet "after" } " consists of the last " { $snippet "n" } " elements of " { $snippet "seq" } ", while " { $snippet "before" } " holds the remaining elements. Both output sequences have the same type as " { $snippet "seq" } "." } ;
  89
  90 HELP: group
  91 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "groups" "a sequence of sequences" } }
  92 { $description "Splits the sequence into groups of " { $snippet "n" } " elements and collects the groups into a new array." }
  93 { $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." } ;
  94
  95 HELP: start*
  96 { $values { "subseq" "a sequence" } { "seq" "a sequence" } { "i" "a start index" } { "n" "a start index" } }
  97 { $description "Outputs the start index of the first contiguous subsequence equal to " { $snippet "subseq" } ", starting the search from the " { $snippet "i" } "th element. If no matching subsequence is found, outputs -1." } ;
  98
  99 HELP: start
 100 { $values { "subseq" "a sequence" } { "seq" "a sequence" } { "n" "a start index" } }
 101 { $description "Outputs the start index of the first contiguous subsequence equal to " { $snippet "subseq" } ", or -1 if no matching subsequence is found." } ;
 102
 103 HELP: subseq?
 104 { $values { "subseq" "a sequence" } { "seq" "a sequence" } { "?" "a boolean" } }
 105 { $description "Tests if " { $snippet "seq" } " contains the elements of " { $snippet "subseq" } " as a contiguous subsequence." } ;
 106
 107 HELP: split1
 108 { $values { "seq" "a sequence" } { "subseq" "a sequence" } { "before" "a new sequence" } { "after" "a new sequence" } }
 109 { $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 } "." } ;
 110
 111 HELP: split*
 112 { $values { "seq" "a sequence" } { "quot" "a quotation with stack effect " { $snippet "( elt -- ? )" } } { "pieces" "a new array" } }
 113 { $description "Splits " { $snippet "seq" } " at each element for which " { $snippet "quot" } " yields a true value, and outputs an array of pieces. The pieces do not include the elements along which the sequence was split." }
 114 { $examples { $example "{ 1 2 3 4 5 6 7 8 } [ 3 mod zero? ] split* ." "{ { 1 2 } { 4 5 } { 7 8 } }" } } ;
 115
 116 HELP: split
 117 { $values { "seq" "a sequence" } { "separators" "a sequence" } { "pieces" "a new array" } }
 118 { $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." }
 119 { $examples { $example "\"hello world-how are you?\" \" -\" split ." "{ \"hello\" \"world\" \"how\" \"are\" \"you?\" }" } } ;
 120
 121 HELP: drop-prefix
 122 { $values { "seq1" "a sequence" } { "seq2" "a sequence" } { "slice1" "a slice" } { "slice2" "a slice" } }
 123 { $description "Outputs a pair of virtual sequences with the common prefix of " { $snippet "seq1" } " and " { $snippet "seq2" } " removed." } ;
 124
 125 HELP: unclip
 126 { $values { "seq" "a sequence" } { "rest" "a sequence" } { "first" "an object" } }
 127 { $description "Outputs a tail sequence and the first element of " { $snippet "seq" } "; the tail sequence consists of all elements of " { $snippet "seq" } " but the first." }
 128 { $examples
 129     { $example "{ 1 2 3 } unclip add ." "{ 2 3 1 }" }
 130 } ;