2 files changed, 151 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)
diff --git a/testcases-cons b/testcases-cons
index 99c150b..d95dbef 100644
--- a/testcases-cons
+++ b/testcases-cons
@@ -338,3 +338,39 @@ nil 0 1 -1.3 "abc" "a\"bc"
 abc "abc" #U
 (1 . 2) (1) (1 2 . 3)
 ((1) (2 . 3) 4 5)
+--
+23:
+$cppawk '
+#include <cons.h>
+
+BEGIN {
+  print equal("", undef), equal(0, 0), equal(-1, -1), equal("", "")
+  print equal("", "a"), equal(0, 1), equal(-1, 1), equal("Tabc", "xyz")
+  print equal("1", "1.0"), equal(box("abc"), "abc")
+  print equal(box(undef), box(undef))
+  print equal(cons("1", "2"), cons("1.0", "2.0"))
+  print equal(cons("1", "3"), cons("1.0", "2.0"))
+  print equal(cons("3", "2"), cons("1.0", "2.0"))
+  print equal(cons("1a", "2a"), cons("1b", "2b"))
+  print "brk"
+  print equal(box_str(1.0), 1.0)
+  print equal(box_str(1.0), box_str("1"))
+  print equal(box_str(1.0), box_str(1.0))
+  print equal(box_str(1.0), "1.0")
+  print equal("1.0", box_str(1.0))
+}'
+:
+1 1 1 1
+0 0 0 0
+1 1
+1
+1
+0
+0
+1
+brk
+1
+1
+1
+0
+0