Function std.algorithm.comparison.cmp
Performs a lexicographical comparison on two
input ranges.
Iterating r1
and r2
in lockstep, cmp
compares each element
e1
of r1
with the corresponding element e2
in r2
. If one
of the ranges has been finished, cmp
returns a negative value
if r1
has fewer elements than r2
, a positive value if r1
has more elements than r2
, and 0
if the ranges have the same
number of elements.
auto cmp(R1, R2)
(
R1 r1,
R2 r2
)
if (isInputRange!R1 && isInputRange!R2);
int cmp(alias pred, R1, R2)
(
R1 r1,
R2 r2
)
if (isInputRange!R1 && isInputRange!R2);
If the ranges are strings, cmp
performs UTF decoding
appropriately and compares the ranges one code point at a time.
A custom predicate may be specified, in which case cmp
performs
a three-way lexicographical comparison using pred
. Otherwise
the elements are compared using opCmp
.
Parameters
Name | Description |
---|---|
pred | Predicate used for comparison. Without a predicate
specified the ordering implied by opCmp is used. |
r1 | The first range. |
r2 | The second range. |
Returns
0
if the ranges compare equal. A negative value if r1
is a prefix of r2
or
the first differing element of r1
is less than the corresponding element of r2
according to pred
. A positive value if r2
is a prefix of r1
or the first
differing element of r2
is less than the corresponding element of r1
according to pred
.
Note
An earlier version of the documentation incorrectly stated that -1
is the
only negative value returned and 1
is the only positive value returned.
Whether that is true depends on the types being compared.
Example
int result;
result = cmp("abc", "abc");
writeln(result); // 0
result = cmp("", "");
writeln(result); // 0
result = cmp("abc", "abcd");
assert(result < 0);
result = cmp("abcd", "abc");
assert(result > 0);
result = cmp("abc"d, "abd");
assert(result < 0);
result = cmp("bbc", "abc"w);
assert(result > 0);
result = cmp("aaa", "aaaa"d);
assert(result < 0);
result = cmp("aaaa", "aaa"d);
assert(result > 0);
result = cmp("aaa", "aaa"d);
writeln(result); // 0
result = cmp("aaa"d, "aaa"d);
writeln(result); // 0
result = cmp(cast(int[])[], cast(int[])[]);
writeln(result); // 0
result = cmp([1, 2, 3], [1, 2, 3]);
writeln(result); // 0
result = cmp([1, 3, 2], [1, 2, 3]);
assert(result > 0);
result = cmp([1, 2, 3], [1L, 2, 3, 4]);
assert(result < 0);
result = cmp([1L, 2, 3], [1, 2]);
assert(result > 0);
Example
Example predicate that compares individual elements in reverse lexical order
int result;
result = cmp!"a > b"("abc", "abc");
writeln(result); // 0
result = cmp!"a > b"("", "");
writeln(result); // 0
result = cmp!"a > b"("abc", "abcd");
assert(result < 0);
result = cmp!"a > b"("abcd", "abc");
assert(result > 0);
result = cmp!"a > b"("abc"d, "abd");
assert(result > 0);
result = cmp!"a > b"("bbc", "abc"w);
assert(result < 0);
result = cmp!"a > b"("aaa", "aaaa"d);
assert(result < 0);
result = cmp!"a > b"("aaaa", "aaa"d);
assert(result > 0);
result = cmp!"a > b"("aaa", "aaa"d);
writeln(result); // 0
result = cmp("aaa"d, "aaa"d);
writeln(result); // 0
result = cmp!"a > b"(cast(int[])[], cast(int[])[]);
writeln(result); // 0
result = cmp!"a > b"([1, 2, 3], [1, 2, 3]);
writeln(result); // 0
result = cmp!"a > b"([1, 3, 2], [1, 2, 3]);
assert(result < 0);
result = cmp!"a > b"([1, 2, 3], [1L, 2, 3, 4]);
assert(result < 0);
result = cmp!"a > b"([1L, 2, 3], [1, 2]);
assert(result > 0);