-USING: assocs arrays generic.single help.markup help.syntax kernel
+USING: arrays generic.single help.markup help.syntax kernel
layouts math math.order quotations sequences.private vectors ;
IN: sequences
}
} ;
+HELP: >slice<
+{ $values
+ { "slice" slice }
+ { "from" integer } { "to" integer } { "seq" sequence }
+}
+{ $description "Sets up the stack for iteration with slots from a " { $link slice } ". Used with iteration in words such as " { $link sequence-operator } "." } ;
+
+HELP: >underlying<
+{ $values
+ { "slice/seq" object }
+ { "i" integer } { "n" integer }
+}
+{ $description "Sets up the stack for iteration with slots from a " { $link sequence } ". Used with iteration in words such as " { $link sequence-operator } "." } ;
+
HELP: slice
{ $class-description "A virtual sequence which presents a subrange of the elements of an underlying sequence. New instances can be created by calling " { $link <slice> } ". Convenience words are also provided for creating slices where one endpoint is the start or end of the sequence; see " { $link "sequences-slices" } " for a list."
$nl
{ tail-slice tail-slice* } related-words
+HELP: head-to-index
+{ $values
+ { "seq" sequence } { "to" integer }
+ { "zero" object }
+}
+{ $description "Sets up the stack for the " { $link head } " word." } ;
+
HELP: head
{ $values { "seq" sequence } { "n" "a non-negative integer" } { "headseq" "a new sequence" } }
{ $description "Outputs a new sequence consisting of the first " { $snippet "n" } " elements of the input sequence." }
}
"When a sequence may not have enough elements:"
{ $example "USING: sequences prettyprint ;"
- "{ 1 2 } 5 short head ."
+ "{ 1 2 } 5 index-or-length head ."
"{ 1 2 }"
}
}
{ $errors "Throws an error if the index is out of bounds." } ;
+HELP: index-to-tail
+{ $values
+ { "seq" sequence } { "from" integer }
+ { "length" object }
+}
+{ $description "Sets up the stack for the " { $link tail } " word." } ;
+
HELP: tail
{ $values { "seq" sequence } { "n" "a non-negative integer" } { "tailseq" "a new sequence" } }
{ $description "Outputs a new sequence consisting of the input sequence with the first " { $snippet "n" } " items removed." }
}
"When a sequence may not have enough elements:"
{ $example "USING: sequences prettyprint ;"
- "{ 1 2 } 5 short tail ."
+ "{ 1 2 } 5 index-or-length tail ."
"{ }"
}
}
}
"When a sequence may not have enough elements:"
{ $example "USING: sequences prettyprint ;"
- "{ 1 2 } 5 short head* ."
+ "{ 1 2 } 5 index-or-length head* ."
"{ }"
}
}
}
"When a sequence may not have enough elements:"
{ $example "USING: sequences prettyprint ;"
- "{ 1 2 } 5 short tail* ."
+ "{ 1 2 } 5 index-or-length tail* ."
"{ 1 2 }"
}
}
{ $values { "seq" sequence } { "n" "a non-negative integer" } { "before" sequence } { "after" sequence } }
{ $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" } "." } ;
-HELP: subseq-start-from
-{ $values { "subseq" sequence } { "seq" sequence } { "n" "a start index" } { "i" "a start index" } }
+HELP: subseq-starts-at?
+{ $values { "i" "a start index" } { "seq" sequence } { "subseq" sequence } { "?" boolean } }
+{ $description "Outputs " { $snippet "t" } " if the subseq starts at the " { $snippet "i" } "th element or outputs " { $link f } " if the sequence is not at that position." } ;
+
+HELP: subseq-index
+{ $values { "seq" sequence } { "subseq" sequence } { "i/f" "a start index or " { $snippet "f" } } }
{ $description "Outputs the start index of the first contiguous subsequence equal to " { $snippet "subseq" } ", starting the search from the " { $snippet "n" } "th element. If no matching subsequence is found, outputs " { $link f } "." } ;
+HELP: subseq-index-from
+{ $values { "n" "a start index" } { "seq" sequence } { "subseq" sequence } { "i/f" "a start index or " { $snippet "f" } } }
+{ $description "Outputs the start index of the first contiguous subsequence equal to " { $snippet "subseq" } ", starting the search from the " { $snippet "n" } "th element. If no matching subsequence is found, outputs " { $link f } "." } ;
+
+HELP: subseq-start-from
+{ $values
+ { "subseq" object } { "seq" sequence } { "n" integer }
+ { "i/f" { $maybe integer } }
+}
+{ $description "Outputs the start index of the first contiguous subsequence equal to " { $snippet "subseq" } ", or " { $link f } " if no matching subsequence is found starting from " { $snippet "n" } "." } ;
+
HELP: subseq-start
-{ $values { "subseq" sequence } { "seq" sequence } { "i" "a start index" } }
+{ $values { "subseq" sequence } { "seq" sequence } { "i/f" "a start index or " { $snippet "f" } } }
{ $description "Outputs the start index of the first contiguous subsequence equal to " { $snippet "subseq" } ", or " { $link f } " if no matching subsequence is found." } ;
HELP: subseq?
{ $values { "subseq" sequence } { "seq" sequence } { "?" boolean } }
{ $description "Tests if " { $snippet "seq" } " contains the elements of " { $snippet "subseq" } " as a contiguous subsequence." } ;
+HELP: subseq-of?
+{ $values { "seq" sequence } { "subseq" sequence } { "?" boolean } }
+{ $description "Tests if " { $snippet "seq" } " contains the elements of " { $snippet "subseq" } " as a contiguous subsequence." } ;
+
HELP: drop-prefix
{ $values { "seq1" sequence } { "seq2" sequence } { "slice1" "a slice" } { "slice2" "a slice" } }
{ $description "Outputs a pair of virtual sequences with the common prefix of " { $snippet "seq1" } " and " { $snippet "seq2" } " removed." } ;
HELP: infimum
{ $values { "seq" sequence } { "elt" object } }
{ $description "Outputs the least element of " { $snippet "seq" } "." }
+{ $examples
+ "Example:"
+ { $example "USING: sequences prettyprint ;"
+ "{ 1 2 3 4 5 } infimum ."
+ "1"
+ }
+ "Example:"
+ { $example "USING: sequences prettyprint ;"
+ "{ \"c\" \"b\" \"a\" } infimum ."
+ "\"a\""
+ }
+}
+{ $errors "Throws an error if the sequence is empty." } ;
+
+HELP: infimum-by
+{ $values
+ { "seq" sequence } { "quot" quotation }
+ { "elt" object }
+}
+{ $description "Outputs the least element of " { $snippet "seq" } " according to the " { $snippet "quot" } "." }
+{ $examples
+ "Example:"
+ { $example "USING: sequences prettyprint ;"
+ "{ { 1 2 } { 1 2 3 } { 1 2 3 4 } } [ length ] infimum-by ."
+ "{ 1 2 }"
+ }
+}
{ $errors "Throws an error if the sequence is empty." } ;
HELP: supremum
{ $values { "seq" sequence } { "elt" object } }
{ $description "Outputs the greatest element of " { $snippet "seq" } "." }
+{ $examples
+ "Example:"
+ { $example "USING: sequences prettyprint ;"
+ "{ 1 2 3 4 5 } supremum ."
+ "5"
+ }
+ "Example:"
+ { $example "USING: sequences prettyprint ;"
+ "{ \"c\" \"b\" \"a\" } supremum ."
+ "\"c\""
+ }
+}
{ $errors "Throws an error if the sequence is empty." } ;
-{ min max supremum infimum } related-words
+HELP: supremum-by
+{ $values
+ { "seq" sequence } { "quot" quotation }
+ { "elt" object }
+}
+{ $description "Outputs the greatest element of " { $snippet "seq" } " according to the " { $snippet "quot" } "." }
+{ $examples
+ "Example:"
+ { $example "USING: sequences prettyprint ;"
+ "{ { 1 2 } { 1 2 3 } { 1 2 3 4 } } [ length ] supremum-by ."
+ "{ 1 2 3 4 }"
+ }
+}
+{ $errors "Throws an error if the sequence is empty." } ;
+
+{ min max infimum infimum-by supremum supremum-by } related-words
HELP: shortest
{ $values { "seqs" sequence } { "elt" object } }
{ $description "Like " { $snippet "map sum" } ", but without creating an intermediate sequence." }
{ $examples
{ $example
- "USING: math math.ranges sequences prettyprint ;"
- "100 [1,b] [ sq ] map-sum ."
+ "USING: math ranges sequences prettyprint ;"
+ "100 [1..b] [ sq ] map-sum ."
"338350"
}
} ;
{ $description "Efficiently returns the number of elements that the predicate quotation matches." }
{ $examples
{ $example
- "USING: math math.ranges sequences prettyprint ;"
- "100 [1,b] [ even? ] count ."
+ "USING: math ranges sequences prettyprint ;"
+ "100 [1..b] [ even? ] count ."
"50"
}
} ;
{ "newhash" integer } }
{ $description "An implementation word that computes a running hashcode of a sequence using some bit-twiddling. The resulting hashcode is always a fixnum." } ;
-HELP: short
+HELP: index-or-length
{ $values
{ "seq" sequence } { "n" integer } { "n'" integer } }
{ $description "Returns the input sequence and its length or " { $snippet "n" } ", whichever is less." }
{ $examples { $example "USING: sequences kernel prettyprint ;"
- "\"abcd\" 3 short [ . ] bi@"
+ "\"abcd\" 3 index-or-length [ . ] bi@"
"\"abcd\"\n3"
} } ;
$nl
"Combinators that produce new sequences, such as " { $link map } ", will output an array if the input is an instance of " { $link <iota> } "."
$nl
-"More elaborate counted loops can be performed with " { $link "math.ranges" } "." ;
+"More elaborate counted loops can be performed with " { $link "ranges" } "." ;
ARTICLE: "sequences-if" "Control flow with sequences"
"To reduce the boilerplate of checking if a sequence is empty, several combinators are provided."
"Testing if a sequence contains an object:"
{ $subsections member? member-eq? }
"Testing if a sequence contains a subsequence:"
-{ $subsections head? tail? subseq? } ;
+{ $subsections head? tail? subseq? subseq-of? } ;
ARTICLE: "sequences-search" "Searching sequences"
"Finding the index of an element:"
last-index-from
}
"Finding the start of a subsequence:"
-{ $subsections subseq-start subseq-start-from }
+{ $subsections
+ subseq-start
+ subseq-start-from
+ subseq-index
+ subseq-index-from
+ subseq-starts-at?
+}
"Finding the index of an element satisfying a predicate:"
{ $subsections
find
"Using sequences for looping:"
{ $subsections
"sequences-integers"
- "math.ranges"
+ "ranges"
}
"Using sequences for control flow:"
{ $subsections "sequences-if" }
projects / factor.git / blobdiff