NAME
Scalar::Cmp - Compare two scalars
VERSION
This document describes version 0.003 of Scalar::Cmp (from Perl
distribution Scalar-Cmp), released on 2021-09-07.
SYNOPSIS
use Scalar::Cmp qw(cmp_scalar cmpnum_scalar cmpstrornum_scalar);
# undef
say cmp_scalar(undef, undef); # => 0
say cmp_scalar(undef, 1); # => -1
# references
say cmp_scalar(1, []); # => 2
say cmp_scalar([], 1); # => 2
say cmp_scalar([], []); # => 2
my $r = []; say cmp_scalar($r, $r); # => 0
# cmp_scalar always uses cmp (mnemonic: "cmp" operator)
say cmpstr_scalar("1.0", 1); # => 1
# cmpnum_scalar always uses <=>
say cmpnum_scalar("1.0", 1); # => 0
say cmpnum_scalar("a", "0"); # => 0, but emit warnings
# cmpstrornum_scalar uses <=> if both scalars look like number, or cmp otherwise
say cmpstrornum_scalar(1, 1); # => 0
say cmpstrornum_scalar(1, 2); # => -1
say cmpstrornum_scalar(2, 1); # => -1
say cmpstrornum_scalar("1.0", 1); # => 0
say cmpstrornum_scalar("a", "0"); # => 1
DESCRIPTION
This module provides "cmp_scalar" (and "cmpnum_scalar" and
"cmpstrornum_scalar" which are convenient routines to compare two scalar
values (ii.e. check if they are the same, or find out who is "greater
than" the other). The routines can handle "undef" and references, so you
don't have to manually check for these.
The routines return -1, 0, 1 like Perl's "cmp" and "<=>" operators, but
also possibly 2 when the two scalars are different but there is no
sensible notion of which one is larger than the other (e.g. 1 vs "[1]").
The following is the rule:
1. Defined value is greater than undef.
cmp_scalar(undef, 0); # => -1
2. undef is the same as itself.
cmp_scalar(undef, undef); # => 0
Note: This might not be what you want if you expect "undef" to act
like "NULL" in relational databases, where "NULL" is not equal to
itself.
2. References cannot be compared with non-references.
cmp_scalar(1, []); # => 2
cmp_scalar([], 1); # => 2
3. A reference is only the same as itself, otherwise it cannot be
compared.
cmp_scalar([], []); # => 2
my $ary = [];
cmp_scalar($ary, $ary); # => 0, same "address"
4. Non-references are compared with "cmp" or "<=>"
"cmp_scalar" always uses "cmp". "cmpnum_scalar" always uses "<=>".
"cmpstrornum_scalar" uses "<=>" if both scalars look like number, or
"cmp" otherwise.
FUNCTIONS
cmp_scalar
cmpnum_scalar
cmpstrornum_scalar
HOMEPAGE
Please visit the project's homepage at
.
SOURCE
Source repository is at .
SEE ALSO
The Perl's "cmp" and "<=>" operators.
Data::Cmp which uses similar comparison rules but recurse into array and
hash elements.
Syntax::Operator::Equ introduces several operators/functions which also
have a rule to equate two undefs.
AUTHOR
perlancar
CONTRIBUTING
To contribute, you can send patches by email/via RT, or send pull
requests on GitHub.
Most of the time, you don't need to build the distribution yourself. You
can simply modify the code, then test via:
% prove -l
If you want to build the distribution (e.g. to try to install it locally
on your system), you can install Dist::Zilla,
Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two
other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional
steps required beyond that are considered a bug and can be reported to
me.
COPYRIGHT AND LICENSE
This software is copyright (c) 2021 by perlancar .
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
BUGS
Please report any bugs or feature requests on the bugtracker website
When submitting a bug or request, please include a test-file or a patch
to an existing test-file that illustrates the bug or desired feature.