NAME

    Syntax::Operator::Equ - equality operators that distinguish undef

SYNOPSIS

    On a suitably-patched perl:

       use Syntax::Operator::Equ;
    
       if($x equ $y) {
          say "x and y are both undef, or both defined and equal strings";
       }
    
       if($i === $j) {
          say "i and j are both undef, or both defined and equal numbers";
       }

    Or, on a standard perl via Syntax::Keyword::Match:

       use v5.14;
       use Syntax::Keyword::Match;
       use Syntax::Operator::Equ;
    
       match($str : equ) {
          case(undef) { say "The variable is not defined" }
          case("")    { say "The variable is defined but is empty" }
          default     { say "The string is non-empty" }
       }

DESCRIPTION

    This module provides infix operators that implement equality tests of
    strings or numbers similar to perl's eq and == operators, except that
    they consider undef to be a distinct value, separate from the empty
    string or the number zero.

    These operators do not warn when either or both operands are undef.
    They yield true if both operands are undef, false if exactly one
    operand is, or otherwise behave the same as the regular string or
    number equality tests if both operands are defined.

    Current versions of perl do not directly support custom infix
    operators. The documentation of XS::Parse::Infix describes the
    situation, with reference to a branch experimenting with this new
    feature. This module is therefore almost entirely useless on standard
    perl builds. While the regular parser does not support custom infix
    operators, they are supported via XS::Parse::Infix and hence
    XS::Parse::Keyword, and so custom keywords which attempt to parse
    operator syntax may be able to use it. One such module is
    Syntax::Keyword::Match; see the SYNOPSIS example given above.

OPERATORS

 equ

       my $equal = $lhs equ $rhs;

    Yields true if both operands are undef, or if both are defined and
    contain equal string values. Yields false if given exactly one undef,
    or two unequal strings.

 ===

       my $equal = $lhs === $rhs;

    Yields true if both operands are undef, or if both are defined and
    contain equal numerical values. Yields false if given exactly one
    undef, or two unequal numbers.

    Note that while this operator will not cause warnings about
    uninitialized values, it can still warn if given defined stringy values
    that are not valid as numbers.

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_strequ

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

    A function version of the "equ" stringy operator.

 is_numequ

       my $equal = is_numequ( $lhs, $rgh );

    A function version of the "===" numerical operator.

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>