std.algorithm.searching
| Function Name | Description |
|---|---|
| all | all!"a > 0"([1, 2, 3, 4]) returns true because all elements are positive |
| any | any!"a > 0"([1, 2, -3, -4]) returns true because at least one element is positive |
| balancedParens | balancedParens("((1 + 1) / 2)", '(', ')') returns true because the string has balanced parentheses. |
| boyerMooreFinder | find("hello world", boyerMooreFinder("or")) returns "orld" using the Boyer-Moore algorithm. |
| canFind | canFind("hello world", "or") returns true. |
| count | Counts all elements or elements matching a predicate, specific element or sub-range. count([1, 2, 1]) returns 3, count([1, 2, 1], 1) returns 2 and count!"a < 0"([1, -3, 0]) returns 1. |
| countUntil | countUntil(a, b) returns the number of steps taken in a to reach b; for example, countUntil("hello!", "o") returns 4. |
| commonPrefix | commonPrefix("parakeet", "parachute") returns "para". |
| endsWith | endsWith("rocks", "ks") returns true. |
| extrema | extrema([2, 1, 3, 5, 4]) returns [1, 5]. |
| find | find("hello world", "or") returns "orld" using linear search. (For binary search refer to std.range.SortedRange.) |
| findAdjacent | findAdjacent([1, 2, 3, 3, 4]) returns the subrange starting with two equal adjacent elements, i.e. [3, 3, 4]. |
| findAmong | findAmong("abcd", "qcx") returns "cd" because 'c' is among "qcx". |
| findSkip | If a = "abcde", then findSkip(a, "x") returns false and leaves a unchanged, whereas findSkip(a, "c") advances a to "de" and returns true. |
| findSplit | findSplit("abcdefg", "de") returns a tuple of three ranges "abc", "de", and "fg". |
| findSplitAfter | findSplitAfter("abcdefg", "de") returns a tuple of two ranges "abcde" and "fg". |
| findSplitBefore | findSplitBefore("abcdefg", "de") returns a tuple of two ranges "abc" and "defg". |
| minCount | minCount([2, 1, 1, 4, 1]) returns tuple(1, 3). |
| maxCount | maxCount([2, 4, 1, 4, 1]) returns tuple(4, 2). |
| minElement | Selects the minimal element of a range. minElement([3, 4, 1, 2]) returns 1. |
| maxElement | Selects the maximal element of a range. maxElement([3, 4, 1, 2]) returns 4. |
| minIndex | Index of the minimal element of a range. minIndex([3, 4, 1, 2]) returns 2. |
| maxIndex | Index of the maximal element of a range. maxIndex([3, 4, 1, 2]) returns 1. |
| minPos | minPos([2, 3, 1, 3, 4, 1]) returns the subrange [1, 3, 4, 1], i.e., positions the range at the first occurrence of its minimal element. |
| maxPos | maxPos([2, 3, 1, 3, 4, 1]) returns the subrange [4, 1], i.e., positions the range at the first occurrence of its maximal element. |
| skipOver | Assume a = "blah". Then skipOver(a, "bi") leaves a unchanged and returns false, whereas skipOver(a, "bl") advances a to refer to "ah" and returns true. |
| startsWith | startsWith("hello, world", "hello") returns true. |
| until | Lazily iterates a range until a specific value is found. |
Source std/algorithm/searching.d
- template
all(alias pred = "a") - Checks if all of the elements satisfy pred.Examples:
assert( all!"a & 1"([1, 3, 5, 7, 9])); assert(!all!"a & 1"([1, 2, 3, 5, 7, 9]));
Examples:allcan also be used without a predicate, if its items can be evaluated to true or false in a conditional statement. This can be a convenient way to quickly evaluate that all of the elements of a range are true.int[3] vals = [5, 3, 18]; assert( all(vals[]));
- bool
all(Range)(Rangerange)
if (isInputRange!Range && (__traits(isTemplate, pred) || is(typeof(unaryFun!pred(range.front))))); - Returns true if and only if the input range
rangeis empty or all values found inrangesatisfy the predicate pred. Performs (at most) Ο(range.length) evaluations of pred.
- template
any(alias pred = "a") - Checks if any of the elements satisfies pred. !
anycan be used to verify that none of the elements satisfy pred. This is sometimes called exists in other languages.Examples:import std.ascii : isWhite; assert( all!(any!isWhite)(["a a", "b b"])); assert(!any!(all!isWhite)(["a a", "b b"]));
Examples:anycan also be used without a predicate, if its items can be evaluated to true or false in a conditional statement. !anycan be a convenient way to quickly test that none of the elements of a range evaluate to true.int[3] vals1 = [0, 0, 0]; assert(!any(vals1[])); //none of vals1 evaluate to true int[3] vals2 = [2, 0, 2]; assert( any(vals2[])); assert(!all(vals2[])); int[3] vals3 = [3, 3, 3]; assert( any(vals3[])); assert( all(vals3[]));
- bool
any(Range)(Rangerange)
if (isInputRange!Range && (__traits(isTemplate, pred) || is(typeof(unaryFun!pred(range.front))))); - Returns true if and only if the input range
rangeis non-empty and any value found inrangesatisfies the predicate pred. Performs (at most) Ο(range.length) evaluations of pred.
- bool
balancedParens(Range, E)(Ranger, ElPar, ErPar, size_tmaxNestingLevel= size_t.max)
if (isInputRange!Range && is(typeof(r.front ==lPar))); - Checks whether
rhas "balanced parentheses", i.e. all instances oflParare closed by corresponding instances ofrPar. The parametermaxNestingLevelcontrols the nesting level allowed. The most common uses are the default or 0. In the latter case, no nesting is allowed.Parameters:Range rThe range to check. E lParThe element corresponding with a left (opening) parenthesis. E rParThe element corresponding with a right (closing) parenthesis. size_t maxNestingLevelThe maximum allowed nesting level. Returns:true if the given range has balanced parenthesis within the given maximum nesting level; false otherwise.Examples:auto s = "1 + (2 * (3 + 1 / 2)"; assert(!balancedParens(s, '(', ')')); s = "1 + (2 * (3 + 1) / 2)"; assert(balancedParens(s, '(', ')')); s = "1 + (2 * (3 + 1) / 2)"; assert(!balancedParens(s, '(', ')', 0)); s = "1 + (2 * 3 + 1) / (2 - 5)"; assert(balancedParens(s, '(', ')', 0)); s = "f(x) = ⌈x⌉"; assert(balancedParens(s, '⌈', '⌉'));
- struct
BoyerMooreFinder(alias pred, Range);
BoyerMooreFinder!(binaryFun!pred, Range)boyerMooreFinder(alias pred = "a == b", Range)(Rangeneedle)
if (isRandomAccessRange!Range && hasSlicing!Range || isSomeString!Range); - Sets up Boyer-Moore matching for use with find below. By default, elements are compared for equality.
BoyerMooreFinderallocates GC memory.Parameters:pred Predicate used to compare elements. Range needleA random-access range with length and slicing. Returns:An instance ofBoyerMooreFinderthat can be used with find() to invoke the Boyer-Moore matching algorithm for finding ofneedlein a given haystack.Examples:auto bmFinder = boyerMooreFinder("TG"); string r = "TAGTGCCTGA"; // search for the first match in the haystack r r = bmFinder.beFound(r); writeln(r); // "TGCCTGA" // continue search in haystack r = bmFinder.beFound(r[2 .. $]); writeln(r); // "TGA"
- this(Range
needle); - Range
beFound(Rangehaystack) scope; - @property size_t
length(); - alias
opDollar= length;
- auto
commonPrefix(alias pred = "a == b", R1, R2)(R1r1, R2r2)
if (isForwardRange!R1 && isInputRange!R2 && !isNarrowString!R1 && is(typeof(binaryFun!pred(r1.front,r2.front))));
autocommonPrefix(alias pred, R1, R2)(R1r1, R2r2)
if (isNarrowString!R1 && isInputRange!R2 && is(typeof(binaryFun!pred(r1.front,r2.front))));
autocommonPrefix(R1, R2)(R1r1, R2r2)
if (isNarrowString!R1 && isInputRange!R2 && !isNarrowString!R2 && is(typeof(r1.front ==r2.front)));
autocommonPrefix(R1, R2)(R1r1, R2r2)
if (isNarrowString!R1 && isNarrowString!R2); - Returns the common prefix of two ranges.Parameters:
pred The predicate to use in comparing elements for commonality. Defaults to equality "a == b". R1 r1A forward range of elements. R2 r2An input range of elements. Returns:A slice ofr1which contains the characters that both ranges start with, if the first argument is a string; otherwise, the same as the result of takeExactly(r1, n), where n is the number of elements in the common prefix of both ranges.See Also:Examples:writeln(commonPrefix("hello, world", "hello, there")); // "hello, "
- size_t
count(alias pred = "a == b", Range, E)(Rangehaystack, Eneedle)
if (isInputRange!Range && !isInfinite!Range && is(typeof(binaryFun!pred(haystack.front,needle))));
size_tcount(alias pred = "a == b", R1, R2)(R1haystack, R2needle)
if (isForwardRange!R1 && !isInfinite!R1 && isForwardRange!R2 && is(typeof(binaryFun!pred(haystack.front,needle.front)))); - Counts matches of
needleinhaystack.The first overload counts each element e inhaystackfor which pred(e,needle) is true. pred defaults to equality. Performs Ο(haystack.length) evaluations of pred. The second overload counts the number of timesneedlewas matched inhaystack. pred compares elements in each range. Throws an exception ifneedle.empty is true, as the count of the empty range in any range would be infinite. Overlapped counts are not considered, for examplecount("aaa", "aa") is 1, not 2.Note Regardless of the overload,
countwill not accept infinite ranges forhaystack.Parameters:pred The predicate to compare elements. Range haystackThe range to count. E needleThe element or sub-range to count in haystack.Returns:The number of matches inhaystack.Examples:// count elements in range int[] a = [ 1, 2, 4, 3, 2, 5, 3, 2, 4 ]; writeln(count(a, 2)); // 3 writeln(count!("a > b")(a, 2)); // 5
Examples:import std.uni : toLower; // count range in range writeln(count("abcadfabf", "ab")); // 2 writeln(count("ababab", "abab")); // 1 writeln(count("ababab", "abx")); // 0 // fuzzy count range in range writeln(count!((a, b) => toLower(a) == toLower(b))("AbcAdFaBf", "ab")); // 2
- size_t
count(alias pred, R)(Rhaystack)
if (isInputRange!R && !isInfinite!R && is(typeof(unaryFun!pred(haystack.front))));
size_tcount(R)(Rhaystack)
if (isInputRange!R && !isInfinite!R); - Counts all elements or elements satisfying a predicate in
haystack.The first overload counts each element e inhaystackfor which pred(e) is true. Performs Ο(haystack.length) evaluations of pred. The second overload counts the number of elements in a range. If the given range has the length property, that is returned right away, otherwise performs Ο(haystack.length) to walk the range.Parameters:pred Optional predicate to find elements. R haystackThe range to count. Returns:The number of elements inhaystack(for which pred returned true).Examples:// count elements in range int[] a = [ 1, 2, 4, 3, 2, 5, 3, 2, 4 ]; writeln(count(a)); // 9 // count predicate in range writeln(count!("a > 2")(a)); // 5
- auto
countUntil(alias pred = "a == b", R, Rs...)(Rhaystack, Rsneedles)
if (isForwardRange!R && (Rs.length > 0) && (isForwardRange!(Rs[0]) == isInputRange!(Rs[0])) && allSatisfy!(canTestStartsWith!(pred, R), Rs));
ptrdiff_tcountUntil(alias pred = "a == b", R, N)(Rhaystack, Nneedle)
if (isInputRange!R && is(typeof(binaryFun!pred(haystack.front,needle)) : bool));
ptrdiff_tcountUntil(alias pred, R)(Rhaystack)
if (isInputRange!R && is(typeof(unaryFun!pred(haystack.front)) : bool)); - Counts elements in the given forward range until the given predicate is true for one of the given
needles.Parameters:pred The predicate for determining when to stop counting. R haystackThe input range to be counted. Rs needlesEither a single element, or a forward range of elements, to be evaluated in turn against each element in haystackunder the given predicate.Returns:The number of elements which must be popped from the front ofhaystackbefore reaching an element for which startsWith!pred(haystack,needles) is true. If startsWith!pred(haystack,needles) is not true for any element inhaystack, then -1 is returned. If more than one needle is provided,countUntilwill wrap the result in a tuple similar to Tuple!(ptrdiff_t, "steps", ptrdiff_tneedle)See Also:Examples:writeln(countUntil("hello world", "world")); // 6 writeln(countUntil("hello world", 'r')); // 8 writeln(countUntil("hello world", "programming")); // -1 writeln(countUntil("日本語", "本語")); // 1 writeln(countUntil("日本語", '語')); // 2 writeln(countUntil("日本語", "五")); // -1 writeln(countUntil("日本語", '五')); // -1 writeln(countUntil([0, 7, 12, 22, 9], [12, 22])); // 2 writeln(countUntil([0, 7, 12, 22, 9], 9)); // 4 writeln(countUntil!"a > b"([0, 7, 12, 22, 9], 20)); // 3 // supports multiple needles auto res = "...hello".countUntil("ha", "he"); writeln(res.steps); // 3 writeln(res.needle); // 1 // returns -1 if no needle was found res = "hello".countUntil("ha", "hu"); writeln(res.steps); // -1 writeln(res.needle); // -1
Examples:import std.ascii : isDigit; import std.uni : isWhite; writeln(countUntil!(isWhite)("hello world")); // 5 writeln(countUntil!(isDigit)("hello world")); // -1 writeln(countUntil!"a > 20"([0, 7, 12, 22, 9])); // 3
- uint
endsWith(alias pred = "a == b", Range, Needles...)(RangedoesThisEnd, NeedleswithOneOfThese)
if (isBidirectionalRange!Range && (Needles.length > 1) && allSatisfy!(canTestStartsWith!(pred, Range), Needles));
boolendsWith(alias pred = "a == b", R1, R2)(R1doesThisEnd, R2withThis)
if (isBidirectionalRange!R1 && isBidirectionalRange!R2 && is(typeof(binaryFun!pred(doesThisEnd.back,withThis.back)) : bool));
boolendsWith(alias pred = "a == b", R, E)(RdoesThisEnd, EwithThis)
if (isBidirectionalRange!R && is(typeof(binaryFun!pred(doesThisEnd.back,withThis)) : bool));
boolendsWith(alias pred, R)(RdoesThisEnd)
if (isInputRange!R && ifTestable!(typeof(doesThisEnd.front), unaryFun!pred)); - Checks if the given range ends with (one of) the given needle(s). The reciprocal of startsWith.Parameters:
pred The predicate to use for comparing elements between the range and the needle(s). Range doesThisEndThe bidirectional range to check. Needles withOneOfTheseThe needles to check against, which may be single elements, or bidirectional ranges of elements. R2 withThisThe single element to check. Returns:0 if the needle(s) do not occur at the end of the given range; otherwise the position of the matching needle, that is, 1 if the range ends withwithOneOfThese[0], 2 if it ends withwithOneOfThese[1], and so on. In the case when no needle parameters are given, return true iff back of doesThisStart fulfils predicate pred.Examples:import std.ascii : isAlpha; assert("abc".endsWith!(a => a.isAlpha)); assert("abc".endsWith!isAlpha); assert(!"ab1".endsWith!(a => a.isAlpha)); assert(!"ab1".endsWith!isAlpha); assert(!"".endsWith!(a => a.isAlpha)); import std.algorithm.comparison : among; assert("abc".endsWith!(a => a.among('c', 'd') != 0)); assert(!"abc".endsWith!(a => a.among('a', 'b') != 0)); assert(endsWith("abc", "")); assert(!endsWith("abc", "b")); writeln(endsWith("abc", "a", 'c')); // 2 writeln(endsWith("abc", "c", "a")); // 1 writeln(endsWith("abc", "c", "c")); // 1 writeln(endsWith("abc", "bc", "c")); // 2 writeln(endsWith("abc", "x", "c", "b")); // 2 writeln(endsWith("abc", "x", "aa", "bc")); // 3 writeln(endsWith("abc", "x", "aaa", "sab")); // 0 writeln(endsWith("abc", "x", "aaa", 'c', "sab")); // 3
- InputRange
find(alias pred, InputRange)(InputRangehaystack)
if (isInputRange!InputRange); - Finds an element e of an input range where pred(e) is true.
findbehaves similarly to dropWhile in other languages.- To find the last matching element in a
bidirectional
haystack, callfind!pred(retro(haystack)). See std.range.retro.
Complexity
findperforms Ο(walkLength(haystack)) evaluations of pred.Parameters:pred The predicate to match an element. InputRange haystackThe input range searched in. Returns:haystackadvanced such that the front element satisfies pred. If no such element exists, returns an emptyhaystack.Examples:auto arr = [ 1, 2, 3, 4, 1 ]; writeln(find!("a > 2")(arr)); // [3, 4, 1] // with predicate alias bool pred(int e) => e + 1 > 1.5; writeln(find!(pred)(arr)); // arr
- InputRange
find(alias pred = "a == b", InputRange, Element)(InputRangehaystack, scope Elementneedle)
if (isInputRange!InputRange && is(typeof(binaryFun!pred(haystack.front,needle)) : bool) && !is(typeof(binaryFun!pred(haystack.front,needle.front)) : bool));
R1find(alias pred = "a == b", R1, R2)(R1haystack, scope R2needle)
if (isForwardRange!R1 && isForwardRange!R2 && is(typeof(binaryFun!pred(haystack.front,needle.front)) : bool)); - Finds an individual element in an input range. Elements of
haystackare compared withneedleby using predicate pred with pred(haystack.front,needle). The predicate is passed to std.functional.binaryFun, and can either accept a string, or any callable that can be executed via pred(element, element).Ifhaystackis a forward range,needlecan be a forward range too. In this case startsWith!pred(haystack,needle) is evaluated on each evaluation.Note: To find the first element not matching the needle, use predicate "a != b".Complexity
findperforms Ο(walkLength(haystack)) evaluations of pred. There are specializations that improve performance by taking advantage of bidirectional or random access ranges (where possible).Parameters:pred The predicate for comparing each element with the needle, defaulting to equality "a == b". InputRange haystackThe input range searched in. Element needleThe element searched for. Returns:haystackadvanced such that the front element is the one searched for; that is, until binaryFun!pred(haystack.front,needle) is true. If no such position exists, returns an emptyhaystack.See Also:Examples:import std.range.primitives; auto arr = [1, 2, 4, 4, 4, 4, 5, 6, 9]; writeln(arr.find(4)); // [4, 4, 4, 4, 5, 6, 9] writeln(arr.find(1)); // arr writeln(arr.find(9)); // [9] writeln(arr.find!((e, n) => e > n)(4)); // [5, 6, 9] writeln(arr.find!((e, n) => e < n)(4)); // arr assert(arr.find(0).empty); assert(arr.find(10).empty); assert(arr.find(8).empty); writeln(find("hello, world", ',')); // ", world"
Examples:Case-insensitive find of a stringimport std.range.primitives; import std.uni : toLower; string[] s = ["Hello", "world", "!"]; writeln(s.find!((e, n) => toLower(e) == n)("hello")); // s
Examples:import std.container : SList; import std.range.primitives : empty; import std.typecons : Tuple; assert(find("hello, world", "World").empty); writeln(find("hello, world", "wo")); // "world" writeln([1, 2, 3, 4].find(SList!int(2, 3)[])); // [2, 3, 4] alias C = Tuple!(int, "x", int, "y"); auto a = [C(1,0), C(2,0), C(3,1), C(4,0)]; writeln(a.find!"a.x == b"([2, 3])); // [C(2, 0), C(3, 1), C(4, 0)] writeln(a[1 .. $].find!"a.x == b"([2, 3])); // [C(2, 0), C(3, 1), C(4, 0)]
- Tuple!(Range, size_t)
find(alias pred = "a == b", Range, Needles...)(Rangehaystack, Needlesneedles)
if (Needles.length > 1 && is(typeof(startsWith!pred(haystack,needles)))); - Finds two or more
needlesinto ahaystack. The predicate pred is used throughout to compare elements. By default, elements are compared for equality.Parameters:pred The predicate to use for comparing elements. Range haystackThe target of the search. Must be an input range. If any of needlesis a range with elements comparable to elements inhaystack, thenhaystackmust be a forward range such that the search can backtrack.Needles needlesOne or more items to search for. Each of needlesmust be either comparable to one element inhaystack, or be itself a forward range with elements comparable with elements inhaystack.Returns:A tuple containinghaystackpositioned to match one of the needles and also the 1-based index of the matching element in needles (0 if none ofneedlesmatched, 1 ifneedles[0] matched, 2 ifneedles[1] matched...). The first needle to be found will be the one that matches. If multiple needles are found at the same spot in the range, then the shortest one is the one which matches (if multiple needles of the same length are found at the same spot (e.g "a" and 'a'), then the left-most of them in the argument list matches). The relationship betweenhaystackandneedlessimply means that one can e.g. search for individual ints or arrays of ints in an array of ints. In addition, if elements are individually comparable, searches of heterogeneous types are allowed as well: a double[] can be searched for an int or a short[], and conversely a long can be searched for a float or a double[]. This makes for efficient searches without the need to coerce one side of the comparison into the other's side type. The complexity of the search is Ο(haystack.length * max(needles.length)). (For needles that are individual items, length is considered to be 1.) The strategy used in searching several subranges at once maximizes cache usage by moving inhaystackas few times as possible.Examples:import std.typecons : tuple; int[] a = [ 1, 4, 2, 3 ]; writeln(find(a, 4)); // [4, 2, 3] writeln(find(a, [1, 4])); // [1, 4, 2, 3] writeln(find(a, [1, 3], 4)); // tuple([4, 2, 3], 2) // Mixed types allowed if comparable writeln(find(a, 5, [1.2, 3.5], 2.0)); // tuple([2, 3], 3)
- RandomAccessRange
find(RandomAccessRange, alias pred, InputRange)(RandomAccessRangehaystack, scope BoyerMooreFinder!(pred, InputRange)needle); - Parameters:
RandomAccessRange haystackA random-access range with length and slicing. BoyerMooreFinder!(pred, InputRange) needleA BoyerMooreFinder. Returns:haystackadvanced such thatneedleis a prefix of it (if no such position exists, returnshaystackadvanced to termination).Examples:import std.range.primitives : empty; int[] a = [ -1, 0, 1, 2, 3, 4, 5 ]; int[] b = [ 1, 2, 3 ]; writeln(find(a, boyerMooreFinder(b))); // [1, 2, 3, 4, 5] assert(find(b, boyerMooreFinder(a)).empty);
- template
canFind(alias pred = "a == b") - Convenience function. Like find, but only returns whether or not the search was successful.For more information about pred see find.See Also:std.algorithm.comparison.among for checking a value against multiple arguments.Examples:
const arr = [0, 1, 2, 3]; assert(canFind(arr, 2)); assert(!canFind(arr, 4)); // find one of several needles assert(arr.canFind(3, 2)); assert(arr.canFind(3, 2) == 2); // second needle found writeln(arr.canFind([1, 3], 2)); // 2 assert(canFind(arr, [1, 2], [2, 3])); writeln(canFind(arr, [1, 2], [2, 3])); // 1 assert(canFind(arr, [1, 7], [2, 3])); writeln(canFind(arr, [1, 7], [2, 3])); // 2 assert(!canFind(arr, [1, 3], [2, 4])); writeln(canFind(arr, [1, 3], [2, 4])); // 0
Examples:Example using a custom predicate. Note that the needle appears as the second argument of the predicate.auto words = [ "apple", "beeswax", "cardboard" ]; assert(!canFind(words, "bees")); assert( canFind!((string elem, string needle) => elem.startsWith(needle))(words, "bees"));
Examples:Search for multiple items in an array of items (search for needles in an array of haystacks)string s1 = "aaa111aaa"; string s2 = "aaa222aaa"; string s3 = "aaa333aaa"; string s4 = "aaa444aaa"; const hay = [s1, s2, s3, s4]; assert(hay.canFind!(e => e.canFind("111", "222")));
- bool
canFind(Range)(Rangehaystack)
if (is(typeof(find!pred(haystack)))); - Returns true if and only if pred(e) is true for any value e in the input range range. Performs (at most) Ο(haystack.length) evaluations of pred.
- bool
canFind(Range, Element)(Rangehaystack, scope Elementneedle)
if (is(typeof(find!pred(haystack,needle)))); - Returns true if and only if
needlecan be found in range. Performs Ο(haystack.length) evaluations of pred. - size_t
canFind(Range, Needles...)(Rangehaystack, scope Needlesneedles)
if (Needles.length > 1 && is(typeof(find!pred(haystack,needles)))); - Returns the 1-based index of the first needle found in
haystack. If no needle is found, then 0 is returned.So, if used directly in the condition of an if statement or loop, the result will be true if one of the needles is found and false if none are found, whereas if the result is used elsewhere, it can either be cast to bool for the same effect or used to get which needle was found first without having to deal with the tuple that find returns for the same operation.
- Range
findAdjacent(alias pred = "a == b", Range)(Ranger)
if (isForwardRange!Range); - Advances
runtil it finds the first two adjacent elements a, b that satisfy pred(a, b). Performs Ο(r.length) evaluations of pred.For more information about pred see find.Parameters:pred The predicate to satisfy. Range rA forward range to search in. Returns:radvanced to the first occurrence of two adjacent elements that satisfy the given predicate. If there are no such two elements, returnsradvanced until empty.See Also:Examples:int[] a = [ 11, 10, 10, 9, 8, 8, 7, 8, 9 ]; auto r = findAdjacent(a); writeln(r); // [10, 10, 9, 8, 8, 7, 8, 9] auto p = findAdjacent!("a < b")(a); writeln(p); // [7, 8, 9]
- InputRange
findAmong(alias pred = "a == b", InputRange, ForwardRange)(InputRangeseq, ForwardRangechoices)
if (isInputRange!InputRange && isForwardRange!ForwardRange); - Searches the given range for an element that matches one of the given choices.Advances
seqby callingseq.popFront until either find!(pred)(choices,seq.front) is true, orseqbecomes empty. Performs Ο(seq.length * choices.length) evaluations of pred. For more information about pred see find.Parameters:pred The predicate to use for determining a match. InputRange seqThe input range to search. ForwardRange choicesA forward range of possible choices. Returns:seqadvanced to the first matching element, or until empty if there are no matching elements.See Also:Examples:int[] a = [ -1, 0, 1, 2, 3, 4, 5 ]; int[] b = [ 3, 1, 2 ]; writeln(findAmong(a, b)); // a[2 .. $]
- bool
findSkip(alias pred = "a == b", R1, R2)(ref R1haystack, R2needle)
if (isForwardRange!R1 && isForwardRange!R2 && is(typeof(binaryFun!pred(haystack.front,needle.front))));
size_tfindSkip(alias pred, R1)(ref R1haystack)
if (isForwardRange!R1 && ifTestable!(typeof(haystack.front), unaryFun!pred)); - Finds
needleinhaystackand positionshaystackright after the first occurrence ofneedle.If no needle is provided, thehaystackis advanced as long as pred evaluates to true. Similarly, the haystack is positioned so as pred evaluates to false forhaystack.front. For more information about pred see find.Parameters:R1 haystackThe forward range to search in. R2 needleThe forward range to search for. pred Custom predicate for comparison of haystack and needle Returns:true if the needle was found, in which casehaystackis positioned after the end of the first occurrence ofneedle; otherwise false, leavinghaystackuntouched. If no needle is provided, it returns the number of times pred(haystack.front) returned true.See Also:Examples:import std.range.primitives : empty; // Needle is found; s is replaced by the substring following the first // occurrence of the needle. string s = "abcdef"; assert(findSkip(s, "cd") && s == "ef"); // Needle is not found; s is left untouched. s = "abcdef"; assert(!findSkip(s, "cxd") && s == "abcdef"); // If the needle occurs at the end of the range, the range is left empty. s = "abcdef"; assert(findSkip(s, "def") && s.empty);
Examples:import std.ascii : isWhite; string s = " abc"; assert(findSkip!isWhite(s) && s == "abc"); assert(!findSkip!isWhite(s) && s == "abc"); s = " "; writeln(findSkip!isWhite(s)); // 2
- auto
findSplit(alias pred = "a == b", R1, R2)(R1haystack, R2needle)
if (isForwardRange!R1 && isForwardRange!R2);
autofindSplitBefore(alias pred = "a == b", R1, R2)(R1haystack, R2needle)
if (isForwardRange!R1 && isForwardRange!R2);
autofindSplitAfter(alias pred = "a == b", R1, R2)(R1haystack, R2needle)
if (isForwardRange!R1 && isForwardRange!R2); - These functions find the first occurrence of
needleinhaystackand then splithaystackas follows.findSplitreturns a tuple result containing three ranges.- result[0] is the portion of
haystackbeforeneedle - result[1] is the portion of
haystackthat matchesneedle - result[2] is the portion of
haystackafter the match.
needlewas not found, result[0] comprehendshaystackentirely and result[1] and result[2] are empty.findSplitBeforereturns a tuple result containing two ranges.- result[0] is the portion of
haystackbeforeneedle - result[1] is the balance of
haystackstarting with the match.
needlewas not found, result[0] comprehendshaystackentirely and result[1] is empty.findSplitAfterreturns a tuple result containing two ranges.- result[0] is the portion of
haystackup to and including the match - result[1] is the balance of
haystackstarting after the match.
needlewas not found, result[0] is empty and result[1] ishaystack.In all cases, the concatenation of the returned ranges spans the entire
Ifhaystack.haystackis a random-access range, all three components of the tuple have the same type ashaystack. Otherwise,haystackmust be a forward range and the type of result[0] (and result[1] forfindSplit) is the same as the result of std.range.takeExactly. For more information about pred see find.Parameters:pred Predicate to compare 2 elements. R1 haystackThe forward range to search. R2 needleThe forward range to look for. Returns:A sub-type of std.typecons.Tuple of the split portions ofhaystack(see above for details). This sub-type of Tuple defines opCast!bool, which returns true when the separatingneedlewas found and false otherwise.See Also:Examples:Returning a subtype of std.typecons.Tuple enables the following convenient idiom:// findSplit returns a triplet if (auto split = "dlang-rocks".findSplit("-")) { writeln(split[0]); // "dlang" writeln(split[1]); // "-" writeln(split[2]); // "rocks" } else assert(0); // findSplitBefore returns 2 ranges if (const split = [2, 3, 2, 3, 4, 1].findSplitBefore!"a > b"([2, 2])) { writeln(split[0]); // [2, 3, 2] // [3, 4] each greater than [2, 2] writeln(split[1]); // [3, 4, 1] } else assert(0);
Examples:import std.range.primitives : empty; auto a = "Carl Sagan Memorial Station"; auto r = findSplit(a, "Velikovsky"); import std.typecons : isTuple; static assert(isTuple!(typeof(r.asTuple))); static assert(isTuple!(typeof(r))); assert(!r); writeln(r[0]); // a assert(r[1].empty); assert(r[2].empty); r = findSplit(a, " "); writeln(r[0]); // "Carl" writeln(r[1]); // " " writeln(r[2]); // "Sagan Memorial Station" if (const r1 = findSplitBefore(a, "Sagan")) { assert(r1); writeln(r1[0]); // "Carl " writeln(r1[1]); // "Sagan Memorial Station" } if (const r2 = findSplitAfter(a, "Sagan")) { assert(r2); writeln(r2[0]); // "Carl Sagan" writeln(r2[1]); // " Memorial Station" }
Examples:Use std.range.only to find single elements:import std.range : only; writeln([1, 2, 3, 4].findSplitBefore(only(3))[0]); // [1, 2]
- result[0] is the portion of
- Tuple!(ElementType!Range, size_t)
minCount(alias pred = "a < b", Range)(Rangerange)
if (isInputRange!Range && !isInfinite!Range && is(typeof(binaryFun!pred(range.front,range.front))));
Tuple!(ElementType!Range, size_t)maxCount(alias pred = "a < b", Range)(Rangerange)
if (isInputRange!Range && !isInfinite!Range && is(typeof(binaryFun!pred(range.front,range.front)))); - Computes the minimum (respectively maximum) of
rangealong with its number of occurrences. Formally, the minimum is a value x inrangesuch that pred(a, x) is false for all values a inrange. Conversely, the maximum is a value x inrangesuch that pred(x, a) is false for all values a inrange(note the swapped arguments to pred).These functions may be used for computing arbitrary extrema by choosing pred appropriately. For corrrect functioning, pred must be a strict partial order, i.e. transitive (if pred(a, b) && pred(b, c) then pred(a, c)) and irreflexive (pred(a, a) is false). The trichotomy property of inequality is not required: these algorithms consider elements a and b equal (for the purpose of counting) if pred puts them in the same equivalence class, i.e. !pred(a, b) && !pred(b, a).Parameters:pred The ordering predicate to use to determine the extremum (minimum or maximum). Range rangeThe input range to count. Returns:The minimum, respectively maximum element of a range together with the number it occurs in the range.Limitations If at least one of the arguments is NaN, the result is an unspecified value. See std.algorithm.searching.maxElement for examples on how to cope with NaNs.
Throws:Exception ifrange.empty.See Also:Examples:import std.conv : text; import std.typecons : tuple; int[] a = [ 2, 3, 4, 1, 2, 4, 1, 1, 2 ]; // Minimum is 1 and occurs 3 times writeln(a.minCount); // tuple(1, 3) // Maximum is 4 and occurs 2 times writeln(a.maxCount); // tuple(4, 2)
- auto
minElement(alias map = (a) => a, Range)(Ranger)
if (isInputRange!Range && !isInfinite!Range);
autominElement(alias map = (a) => a, Range, RangeElementType = ElementType!Range)(Ranger, RangeElementTypeseed)
if (isInputRange!Range && !isInfinite!Range && !is(CommonType!(ElementType!Range, RangeElementType) == void)); - Iterates the passed range and returns the minimal element. A custom mapping function can be passed to map. In other languages this is sometimes called argmin.
Complexity O(n) Exactly n - 1 comparisons are needed.
Parameters:map custom accessor for the comparison key Range rrange from which the minimal element will be selected RangeElementType seedcustom seed to use as initial element Precondition If a seed is not given,
rmust not be empty.Returns:The minimal element of the passed-in range.Note If at least one of the arguments is NaN, the result is an unspecified value.
If you want to ignore NaNs, you can use std.algorithm.iteration.filter and std.math.isNaN to remove them, before applying minElement. Add a suitable seed, to avoid error messages if all elements are NaNs:<range>.filter!(a=>!a.isNaN).minElement(<seed>);
If you want to get NaN as a result if a NaN is present in the range, you can use std.algorithm.iteration.fold and std.math.isNaN:<range>.fold!((a,b)=>a.isNaN || b.isNaN ? real.nan : a < b ? a : b);See Also:Examples:import std.range : enumerate; import std.typecons : tuple; writeln([2, 7, 1, 3].minElement); // 1 // allows to get the index of an element too writeln([5, 3, 7, 9].enumerate.minElement!"a.value"); // tuple(1, 3) // any custom accessor can be passed writeln([[0, 4], [1, 2]].minElement!"a[1]"); // [1, 2] // can be seeded int[] arr; writeln(arr.minElement(1)); // 1
- auto
maxElement(alias map = (a) => a, Range)(Ranger)
if (isInputRange!Range && !isInfinite!Range);
automaxElement(alias map = (a) => a, Range, RangeElementType = ElementType!Range)(Ranger, RangeElementTypeseed)
if (isInputRange!Range && !isInfinite!Range && !is(CommonType!(ElementType!Range, RangeElementType) == void)); - Iterates the passed range and returns the maximal element. A custom mapping function can be passed to map. In other languages this is sometimes called argmax.
Complexity O(n) Exactly n - 1 comparisons are needed.
Parameters:map custom accessor for the comparison key Range rrange from which the maximum element will be selected RangeElementType seedcustom seed to use as initial element Precondition If a seed is not given,
rmust not be empty.Returns:The maximal element of the passed-in range.Note If at least one of the arguments is NaN, the result is an unspecified value. See std.algorithm.searching.minElement for examples on how to cope with NaNs.
See Also:Examples:import std.range : enumerate; import std.typecons : tuple; writeln([2, 1, 4, 3].maxElement); // 4 // allows to get the index of an element too writeln([2, 1, 4, 3].enumerate.maxElement!"a.value"); // tuple(2, 4) // any custom accessor can be passed writeln([[0, 4], [1, 2]].maxElement!"a[1]"); // [0, 4] // can be seeded int[] arr; writeln(arr.minElement(1)); // 1
- ElementType!Range[2]
extrema(Range)(Ranger)
if (isInputRange!Range && !isInfinite!Range); - Returns an array of the minimum and maximum element in
r. Performs < 3n/2 comparisons, unlike the naive < 2n.Parameters:Range rThe range to traverse. Examples:writeln(extrema([5, 2, 9, 4, 1])); // [1, 9]
- Range
minPos(alias pred = "a < b", Range)(Rangerange)
if (isForwardRange!Range && !isInfinite!Range && is(typeof(binaryFun!pred(range.front,range.front))));
RangemaxPos(alias pred = "a < b", Range)(Rangerange)
if (isForwardRange!Range && !isInfinite!Range && is(typeof(binaryFun!pred(range.front,range.front)))); - Computes a subrange of
rangestarting at the first occurrence ofrange's minimum (respectively maximum) and with the same ending asrange, or the empty range ifrangeitself is empty.Formally, the minimum is a value x inrangesuch that pred(a, x) is false for all values a inrange. Conversely, the maximum is a value x inrangesuch that pred(x, a) is false for all values a inrange(note the swapped arguments to pred). These functions may be used for computing arbitrary extrema by choosing pred appropriately. For corrrect functioning, pred must be a strict partial order, i.e. transitive (if pred(a, b) && pred(b, c) then pred(a, c)) and irreflexive (pred(a, a) is false).Parameters:pred The ordering predicate to use to determine the extremum (minimum or maximum) element. Range rangeThe forward range to search. Returns:The position of the minimum (respectively maximum) element of forward rangerange, i.e. a subrange ofrangestarting at the position of its smallest (respectively largest) element and with the same ending asrange.Limitations If at least one of the arguments is NaN, the result is an unspecified value. See std.algorithm.searching.maxElement for examples on how to cope with NaNs.
See Also:Examples:int[] a = [ 2, 3, 4, 1, 2, 4, 1, 1, 2 ]; // Minimum is 1 and first occurs in position 3 writeln(a.minPos); // [1, 2, 4, 1, 1, 2] // Maximum is 4 and first occurs in position 2 writeln(a.maxPos); // [4, 1, 2, 4, 1, 1, 2]
- ptrdiff_t
minIndex(alias pred = "a < b", Range)(Rangerange)
if (isInputRange!Range && !isInfinite!Range && is(typeof(binaryFun!pred(range.front,range.front)))); - Computes the index of the first occurrence of
range's minimum element.Parameters:pred The ordering predicate to use to determine the minimum element. Range rangeThe input range to search. Complexity Ο(range.length) Exactly
range.length - 1 comparisons are needed.Returns:The index of the first encounter of the minimum element inrange. If therangeis empty, -1 is returned.Limitations If at least one of the arguments is NaN, the result is an unspecified value. See std.algorithm.searching.maxElement for examples on how to cope with NaNs.
See Also:Examples:int[] a = [2, 3, 4, 1, 2, 4, 1, 1, 2]; // Minimum is 1 and first occurs in position 3 writeln(a.minIndex); // 3 // Get maximum index with minIndex writeln(a.minIndex!"a > b"); // 2 // Range is empty, so return value is -1 int[] b; writeln(b.minIndex); // -1 // Works with more custom types struct Dog { int age; } Dog[] dogs = [Dog(10), Dog(5), Dog(15)]; writeln(dogs.minIndex!"a.age < b.age"); // 1
- ptrdiff_t
maxIndex(alias pred = "a < b", Range)(Rangerange)
if (isInputRange!Range && !isInfinite!Range && is(typeof(binaryFun!pred(range.front,range.front)))); - Computes the index of the first occurrence of
range's maximum element.Complexity Ο(range) Exactly
range.length - 1 comparisons are needed.Parameters:pred The ordering predicate to use to determine the maximum element. Range rangeThe input range to search. Returns:The index of the first encounter of the maximum inrange. If therangeis empty, -1 is returned.Limitations If at least one of the arguments is NaN, the result is an unspecified value. See std.algorithm.searching.maxElement for examples on how to cope with NaNs.
See Also:Examples:// Maximum is 4 and first occurs in position 2 int[] a = [2, 3, 4, 1, 2, 4, 1, 1, 2]; writeln(a.maxIndex); // 2 // Empty range int[] b; writeln(b.maxIndex); // -1 // Works with more custom types struct Dog { int age; } Dog[] dogs = [Dog(10), Dog(15), Dog(5)]; writeln(dogs.maxIndex!"a.age < b.age"); // 1
- template
skipOver(alias pred = (a, b) => a == b) - Skip over the initial portion of the first given range (haystack) that matches any of the additionally given ranges (needles) fully, or if no second range is given skip over the elements that fulfill pred. Do nothing if there is no match.Parameters:
pred The predicate that determines whether elements from each respective range match. Defaults to equality "a == b". Examples:import std.algorithm.comparison : equal; auto s1 = "Hello world"; assert(!skipOver(s1, "Ha")); writeln(s1); // "Hello world" assert(skipOver(s1, "Hell") && s1 == "o world", s1); string[] r1 = ["abc", "def", "hij"]; dstring[] r2 = ["abc"d]; assert(!skipOver!((a, b) => a.equal(b))(r1, ["def"d]), r1[0]); writeln(r1); // ["abc", "def", "hij"] assert(skipOver!((a, b) => a.equal(b))(r1, r2)); writeln(r1); // ["def", "hij"]
Examples:import std.ascii : isWhite; import std.range.primitives : empty; auto s2 = "\t\tvalue"; auto s3 = ""; auto s4 = "\t\t\t"; assert(s2.skipOver!isWhite && s2 == "value"); assert(!s3.skipOver!isWhite); assert(s4.skipOver!isWhite && s3.empty);
Examples:Variadic skipOverauto s = "Hello world"; assert(!skipOver(s, "hello", "HellO")); writeln(s); // "Hello world" // the range is skipped over the longest matching needle is skipped assert(skipOver(s, "foo", "hell", "Hello ")); writeln(s); // "world"
Examples:import std.algorithm.comparison : equal; auto s1 = "Hello world"; assert(!skipOver(s1, 'a')); writeln(s1); // "Hello world" assert(skipOver(s1, 'H') && s1 == "ello world"); string[] r = ["abc", "def", "hij"]; dstring e = "abc"d; assert(!skipOver!((a, b) => a.equal(b))(r, "def"d)); writeln(r); // ["abc", "def", "hij"] assert(skipOver!((a, b) => a.equal(b))(r, e)); writeln(r); // ["def", "hij"] auto s2 = ""; assert(!s2.skipOver('a'));
Examples:Partial instantiationimport std.ascii : isWhite; import std.range.primitives : empty; alias whitespaceSkiper = skipOver!isWhite; auto s2 = "\t\tvalue"; auto s3 = ""; auto s4 = "\t\t\t"; assert(whitespaceSkiper(s2) && s2 == "value"); assert(!whitespaceSkiper(s2)); assert(whitespaceSkiper(s4) && s3.empty);
- bool
skipOver(Haystack, Needles...)(ref Haystackhaystack, Needlesneedles)
if (is(typeof(binaryFun!pred(haystack.front,needles[0].front))) && isForwardRange!Haystack && allSatisfy!(isInputRange, Needles) && !is(CommonType!(staticMap!(ElementType, staticMap!(Unqual, Needles))) == void));
boolskipOver(R)(ref Rr1)
if (isForwardRange!R && ifTestable!(typeof(r1.front), unaryFun!pred));
boolskipOver(R, Es...)(ref Rr, Eses)
if (isInputRange!R && is(typeof(binaryFun!pred(r.front,es[0])))); - Parameters:
Haystack haystackThe forward range to move forward. Needles needlesThe input ranges representing the prefix of r1to skip over.Es esThe element to match. Returns:true if the prefix ofhaystackmatches any range ofneedlesfully or pred evaluates to true, andhaystackhas been advanced to the point past this segment; otherwise false, andhaystackis left in its original position.Note By definition, empty ranges are matched fully and if
needlescontains an empty range,skipOverwill return true.
- uint
startsWith(alias pred = (a, b) => a == b, Range, Needles...)(RangedoesThisStart, NeedleswithOneOfThese)
if (isInputRange!Range && (Needles.length > 1) && allSatisfy!(canTestStartsWith!(pred, Range), Needles));
boolstartsWith(alias pred = "a == b", R1, R2)(R1doesThisStart, R2withThis)
if (isInputRange!R1 && isInputRange!R2 && is(typeof(binaryFun!pred(doesThisStart.front,withThis.front)) : bool));
boolstartsWith(alias pred = "a == b", R, E)(RdoesThisStart, EwithThis)
if (isInputRange!R && is(typeof(binaryFun!pred(doesThisStart.front,withThis)) : bool));
boolstartsWith(alias pred, R)(RdoesThisStart)
if (isInputRange!R && ifTestable!(typeof(doesThisStart.front), unaryFun!pred)); - Checks whether the given input range starts with (one of) the given needle(s) or, if no needles are given, if its front element fulfils predicate pred.For more information about pred see find.Parameters:
pred Predicate to use in comparing the elements of the haystack and the needle(s). Mandatory if no needles are given. Range doesThisStartThe input range to check. Needles withOneOfTheseThe needles against which the range is to be checked, which may be individual elements or input ranges of elements. R2 withThisThe single needle to check, which may be either a single element or an input range of elements. Returns:0 if the needle(s) do not occur at the beginning of the given range; otherwise the position of the matching needle, that is, 1 if the range starts withwithOneOfThese[0], 2 if it starts withwithOneOfThese[1], and so on. In the case wheredoesThisStartstarts with multiple of the ranges or elements inwithOneOfThese, then the shortest one matches (if there are two which match which are of the same length (e.g. "a" and 'a'), then the left-most of them in the argument list matches). In the case when no needle parameters are given, return true iff front ofdoesThisStartfulfils predicate pred.Examples:import std.ascii : isAlpha; assert("abc".startsWith!(a => a.isAlpha)); assert("abc".startsWith!isAlpha); assert(!"1ab".startsWith!(a => a.isAlpha)); assert(!"".startsWith!(a => a.isAlpha)); import std.algorithm.comparison : among; assert("abc".startsWith!(a => a.among('a', 'b') != 0)); assert(!"abc".startsWith!(a => a.among('b', 'c') != 0)); assert(startsWith("abc", "")); assert(startsWith("abc", "a")); assert(!startsWith("abc", "b")); writeln(startsWith("abc", 'a', "b")); // 1 writeln(startsWith("abc", "b", "a")); // 2 writeln(startsWith("abc", "a", "a")); // 1 writeln(startsWith("abc", "ab", "a")); // 2 writeln(startsWith("abc", "x", "a", "b")); // 2 writeln(startsWith("abc", "x", "aa", "ab")); // 3 writeln(startsWith("abc", "x", "aaa", "sab")); // 0 writeln(startsWith("abc", "x", "aaa", "a", "sab")); // 3 import std.typecons : Tuple; alias C = Tuple!(int, "x", int, "y"); assert(startsWith!"a.x == b"([ C(1,1), C(1,2), C(2,2) ], [1, 1])); writeln(startsWith!"a.x == b"([C(1, 1), C(2, 1), C(2, 2)], [1, 1], [1, 2], [1, 3])); // 2
- alias
OpenRight= std.typecons.Flag!"openRight".Flag; - Interval option specifier for until (below) and others.If set to
OpenRight.yes, then the interval is open to the right (last element is not included). Otherwise if set toOpenRight.no, then the interval is closed to the right including the entire sentinel. - Until!(pred, Range, Sentinel)
until(alias pred = "a == b", Range, Sentinel)(Rangerange, Sentinelsentinel, OpenRightopenRight= Yes.openRight)
if (!is(Sentinel == OpenRight));
Until!(pred, Range, void)until(alias pred, Range)(Rangerange, OpenRightopenRight= Yes.openRight);
structUntil(alias pred, Range, Sentinel) if (isInputRange!Range); - Lazily iterates
rangeuntil the element e for which pred(e,sentinel) is true.This is similar to takeWhile in other languages.Parameters:pred Predicate to determine when to stop. Range rangeThe input range to iterate over. Sentinel sentinelThe element to stop at. OpenRight openRightDetermines whether the element for which the given predicate is true should be included in the resulting range (No. openRight), or not (Yes.openRight).Returns:An input range that iterates over the original range's elements, but ends when the specified predicate becomes true. If the original range is a forward range or higher, this range will be a forward range.Examples:import std.algorithm.comparison : equal; import std.typecons : No; int[] a = [ 1, 2, 4, 7, 7, 2, 4, 7, 3, 5]; assert(equal(a.until(7), [1, 2, 4])); assert(equal(a.until(7, No.openRight), [1, 2, 4, 7]));