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);