.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Syntax::Operator::Equ 3pm"
.TH Syntax::Operator::Equ 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
"Syntax::Operator::Equ" \- equality operators that distinguish "undef"
.SH SYNOPSIS
.IX Header "SYNOPSIS"
On Perl v5.38 or later:
.PP
.Vb 2
\&   use v5.38;
\&   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";
\&   }
.Ve
.PP
Or via Syntax::Keyword::Match on Perl v5.14 or later:
.PP
.Vb 3
\&   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" }
\&   }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides infix operators that implement equality tests of strings
or numbers similar to perl's \f(CW\*(C`eq\*(C'\fR and \f(CW\*(C`==\*(C'\fR operators, except that they
consider \f(CW\*(C`undef\*(C'\fR to be a distinct value, separate from the empty string or
the number zero.
.PP
These operators do not warn when either or both operands are \f(CW\*(C`undef\*(C'\fR. They
yield true if both operands are \f(CW\*(C`undef\*(C'\fR, false if exactly one operand is, or
otherwise behave the same as the regular string or number equality tests if
both operands are defined.
.PP
Support for custom infix operators was added in the Perl 5.37.x development
cycle and is available from development release v5.37.7 onwards, and therefore
in Perl v5.38 onwards. The documentation of XS::Parse::Infix
describes the situation in more detail.
.PP
While Perl versions before this do not support custom infix operators, they
can still be used via \f(CW\*(C`XS::Parse::Infix\*(C'\fR and hence XS::Parse::Keyword.
Custom keywords which attempt to parse operator syntax may be able to use
these. One such module is Syntax::Keyword::Match; see the SYNOPSIS example
given above.
.SH OPERATORS
.IX Header "OPERATORS"
.SS equ
.IX Subsection "equ"
.Vb 1
\&   my $equal = $lhs equ $rhs;
.Ve
.PP
Yields true if both operands are \f(CW\*(C`undef\*(C'\fR, or if both are defined and contain
equal string values. Yields false if given exactly one \f(CW\*(C`undef\*(C'\fR, or two
unequal strings.
.SS ===
.IX Subsection "==="
.Vb 1
\&   my $equal = $lhs === $rhs;
.Ve
.PP
Yields true if both operands are \f(CW\*(C`undef\*(C'\fR, or if both are defined and contain
equal numerical values. Yields false if given exactly one \f(CW\*(C`undef\*(C'\fR, or two
unequal numbers.
.PP
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.
.SH FUNCTIONS
.IX Header "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.
.PP
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.
.SS is_strequ
.IX Subsection "is_strequ"
.Vb 1
\&   my $equal = is_strequ( $lhs, $rhs );
.Ve
.PP
A function version of the "equ" stringy operator.
.SS is_numequ
.IX Subsection "is_numequ"
.Vb 1
\&   my $equal = is_numequ( $lhs, $rgh );
.Ve
.PP
A function version of the "===" numerical operator.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP \(bu 4
Syntax::Operator::Eqr \- string equality and regexp match operator
.SH AUTHOR
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>