1 files changed, 115 insertions, 0 deletions
diff --git a/cppawk-cons.1 b/cppawk-cons.1
index dcf413f..d670b2f 100644
--- a/cppawk-cons.1
+++ b/cppawk-cons.1
@@ -888,6 +888,121 @@ function favors the last of these.
   (nil . 1)
 .ft R
 
+.SS Function \fIequal\fP
+.bk
+.B Syntax:
+
+.ft B
+  equal(x, y)
+.ft R
+
+.B Description
+The
+.B equal
+function compares two objects
+.I x
+and
+.IR y ,
+returning 1 to indicate that they are
+the same, otherwise 0. This function's notion of sameness is different
+from that of the
+.B ==
+operator.
+
+If
+.I x
+and
+.I y
+are equal under the
+.B ==
+operator,
+.B equal
+returns 1;
+.B equal
+never contradicts a positive result from the Awk equality operator.
+
+However, some values found to be different by the
+.B ==
+operator are nevertheless same according to
+.BR equal ,
+in the following ways.
+
+.IP 1.
+If
+.I x
+and
+.I y
+are both numeric, then they are compared numerically, even if
+they are character strings. While this may seem to be the same as Awk equality,
+it is not the case.  This rule is applied regardless of the origin of
+.I x
+and
+.IR y .
+Concretely:
+
+.ft B
+  ("1" == "1.0") => 0
+.ft R
+
+but:
+
+.ft B
+  equal("1", "1.0") => 1
+.ft R
+
+There are situations in which Awk
+.B ==
+appears to have the behavior of
+.B equal
+on two inputs, for instance:
+
+.ft B
+  awk '{ print $1 == $2 }'
+.ft R
+
+will print 1 when a record with the fields
+.B 1
+and
+.B 1.0
+is processed. This is because at input time, Awk classifies such
+inputs as being numeric strings, attaching that to their type
+information, and two numeric strings are compared as numbers.
+Loosely speaking, the
+.B equal
+function compares two strings as numbers if they would be numeric
+strings if they were input as Awk fields.
+
+.IP 2.
+A box string is
+.B equal
+to an unboxed string of the same content, even though their Awk
+representation is different. In implementation terms:
+
+.ft B
+  equal("Tabc", "abc") => 1
+.ft R
+
+.IP 3.
+If
+.I x
+and
+.I y
+are both cons cells, then
+.B equal
+considers them to be the same if, recursively,
+.BI car( x )
+is
+.B equal
+to
+.BI car( y )
+and
+.BI cdr( x )
+is
+.B equal
+to
+.BI cdr( y )
+.PP
+
 .SH "SEE ALSO"
 
 cppawk(1)