Change name of ibcmp to foldEQ

As discussed on p5p, ibcmp has different semantics from other cmp
functions in that it is a binary instead of ternary function.  It is
less confusing then to have a name that implies true/false.

There are three functions affected: ibcmp, ibcmp_locale and ibcmp_utf8.
ibcmp is actually equivalent to foldNE, but for the same reason that things
like 'unless' and 'until' are cautioned against, I changed the functions
to foldEQ, so that the existing names, like ibcmp_utf8 are defined as
macros as being the complement of foldEQ.

This patch also changes the one file where turning ibcmp into a macro
causes problems.  It changes it to use the new name.  It also documents
for the first time ibcmp, ibcmp_locale and their new names.

1 files changed, 10 insertions, 0 deletions

diff --git a/utf8.h b/utf8.h
index b0cfedf9e1..8e6d4e0687 100644
--- a/utf8.h
+++ b/utf8.h
@@ -20,6 +20,16 @@
 #define uvuni_to_utf8(d, uv)		uvuni_to_utf8_flags(d, uv, 0)
 #define is_utf8_string_loc(s, len, ep)	is_utf8_string_loclen(s, len, ep, 0)
 
+/*
+=for apidoc ibcmp_utf8
+
+This is a synonym for (! foldEQ_utf8())
+
+=cut
+*/
+#define ibcmp_utf8(s1, pe1, l1, u1, s2, pe2, l2, u2) \
+		    cBOOL(! foldEQ_utf8(s1, pe1, l1, u1, s2, pe2, l2, u2))
+
 #ifdef EBCDIC
 /* The equivalent of these macros but implementing UTF-EBCDIC
    are in the following header file: