/ 
Syntax-Operator-Identical-0.05
River stage zero No dependents
/ Syntax::Operator::Identical

NAME

Syntax::Operator::Identical - almost certainly a terrible idea; don't use this

SYNOPSIS

You almost certainly don't want to use this.

However, if despite all my warnings you still want to, then on Perl v5.38 or later:

use v5.38;
use Syntax::Operator::Identical;

my $x = ...;
my $y = ...;

if( $x ≡ $y ) {
   say "x and y are identical";
}

Or via Syntax::Keyword::Match on Perl v5.14 or later:

use v5.14;
use Syntax::Keyword::Match;
use Syntax::Operator::Identical;

my $x = ...;

match($x : ≡) {
   case(undef) { say "The value is not defined" }
   case(123)   { say "The value is identical to 123" }
   case("abc") { say "The value is identical to abc" }
}

DESCRIPTION

This module provides an infix operator that implements an identity test between two values, in a way somewhat similar to the now-deprecated smartmatch (~~) operator, or other similar ideas.

It is probably not a good idea to use this operator; it is written largely as a demonstration on how such an operator could be implemented, as well as to illustrate how fragile it is, in particular around the "is it a string or a number?" part of the logic.

Comparison Logic

This operator acts symmetrically; that is, given any pair of values $x and $y, the result of $x ≡ $y will be the same as $y ≡ $x. It uses the following rules:

  • Definedness

    If both values are undef, the operator yields true. Otherwise, if one value is defined and the other is not, it yields false.

  • Booleans (on Perl v5.36 or later)

    If both values are booleans (as according to builtin::isbool), then the operator returns true or false depending on whether they have the same value. Otherwise, if only one is a boolean then it yields false.

  • References

    If both values are references, the operator yields true or false depending on whether they both refer to the same thing. Otherwise, if only one is a reference it returns false.

  • Non-references

    For any other pairs of values, if either value has a numerical part, then a numerical comparison is made as per the == operator, and if that is false then this operator yields false. Then, if either value has a stringy part, then a string comparison is made as per the eq operator, and if that is false then this operator yields false. Because non-defined and reference values have already been considered at this point, at least one of these tests must necessarily be performed.

    At this point, if there are no other reasons to reject it, the operator yields true.

As a consequence of the boolean rule, on Perl v5.36 or later, real boolean values are not identical to either the numfied or stringified values they would yield.

(5 == 5) == 1;   # is true
(5 == 5) ≡  1;   # is false

(5 == 5) eq "1";   # is true
(5 == 5) ≡  "1";   # is false

As a consequence of the reference rule, references are not identical to a numified or stringified copy of themselves.

my $aref = [];

$aref == 0+$aref;   # is true
$aref ≡  0+$aref;   # is false

$aref eq "$aref";   # is true
$aref ≡  "$aref";   # is false

Also as a consequence of the reference rule, any reference to an object is never considered identical to a plain string or number, even if that object overloads the string or number comparison operators in a way that would consider it to be.

As a consequence of the final non-reference rule, comparisons between a mixture of pure-number and pure-string values will be more strict than either the == or eq operator alone would perform. Both operators must consider the values equal for it to pass.

10 == "10.0";   # is true
10 ≡  "10.0";   # is false, because eq says so

OPERATORS

≡, =:=

my $equal = $lhs ≡ $rhs;
my $equal = $lhs =:= $rhs;

Yields true if the two operands are identical, using the rules defined above. The two different spellings are aliases; the latter is simply an ASCII-safe variant to avoid needing to type the ≡ symbol.

≢, !:=

my $unequal = $lhs ≢ $rhs;
my $unequal = $lhs !:= $rhs;

The complement operator to ≡; yielding true where it would yield false, and vice versa. The two different spellings are aliases; the latter is simply an ASCII-safe variant to avoid needing to type the ≢ symbol.

FUNCTIONS

As a convenience, the following functions may be imported which implement the same behaviour as the infix operators, though are accessed via regular function call syntax.

These wrapper functions are implemented using XS::Parse::Infix, and thus have an optimising call-checker attached to them. In most cases, code which calls them should not in fact have the full runtime overhead of a function call because the underlying test operator will get inlined into the calling code at compiletime. In effect, code calling these functions should run with the same performance as code using the infix operators directly.

is_identical

my $equal = is_identical( $lhs, $rhs );

A function version of the ≡ operator.

is_not_identical

my $unequal = is_not_identical( $lhs, $rhs );

A function version of the ≢ operator.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>