This is a live mirror of the Perl 5 development currently hosted at
perlapi: Document some functions
authorKarl Williamson <>
Thu, 7 May 2015 02:42:15 +0000 (20:42 -0600)
committerKarl Williamson <>
Thu, 7 May 2015 23:32:47 +0000 (17:32 -0600)
These are mentioned in some other pods.  It's best to bring them into
perlapi, and refer to them from the other pods.


diff --git a/handy.h b/handy.h
index 89055c5..3e6fd52 100644 (file)
--- a/handy.h
+++ b/handy.h
@@ -449,6 +449,16 @@ Test two strings to see if they are equal.  The C<len> parameter indicates
 the number of bytes to compare.  Returns true or false.  (A wrapper for
+=for apidoc Am|bool|memEQ|char* s1|char* s2|STRLEN len
+Test two buffers (which may contain embedded C<NUL> characters, to see if they
+are equal.  The C<len> parameter indicates the number of bytes to compare.
+Returns zero if equal, or non-zero if non-equal.
+=for apidoc Am|bool|memNE|char* s1|char* s2|STRLEN len
+Test two buffers (which may contain embedded C<NUL> characters, to see if they
+are not equal.  The C<len> parameter indicates the number of bytes to compare.
+Returns zero if non-equal, or non-zero if equal.
diff --git a/utf8.h b/utf8.h
index 2c1acd2..594d1b0 100644 (file)
--- a/utf8.h
+++ b/utf8.h
@@ -324,6 +324,16 @@ Perl's extended UTF-8 means we can have start bytes up to FF.
 /* Number of bytes a code point occupies in UTF-8. */
+=for apidoc Am|STRLEN|UVCHR_SKIP|UV cp
+returns the number of bytes required to represent the code point C<cp> when
+encoded as UTF-8.  C<cp> is a native (ASCII or EBCDIC) code point if less than
+255; a Unicode code point otherwise.
+ */
 /* Most code which says UNISKIP is really thinking in terms of native code
  * points (0-255) plus all those beyond.  This is an imprecise term, but having
  * it means existing code continues to work.  For precision, use UVCHR_SKIP,
@@ -343,8 +353,14 @@ Perl's extended UTF-8 means we can have start bytes up to FF.
 /* Should never be used, and be deprecated */
-/* How many bytes in the UTF-8 encoded character whose first (perhaps only)
- * byte is pointed to by 's' */
+=for apidoc Am|STRLEN|UTF8SKIP|char* s
+returns the number of bytes in the UTF-8 encoded character whose first (perhaps
+only) byte is pointed to by C<s>.
+ */
 #define UTF8SKIP(s) PL_utf8skip[*(const U8*)(s)]
 /* Is the byte 'c' the same character when encoded in UTF-8 as when not.  This
@@ -430,6 +446,18 @@ Perl's extended UTF-8 means we can have start bytes up to FF.
 #define IN_BYTES (CopHINTS_get(PL_curcop) & HINT_BYTES)
+=for apidoc Am|bool|DO_UTF8|SV* sv
+Returns a bool giving whether or not the PV in C<sv> is to be treated as being
+encoded in UTF-8.
+You should use this I<after> a call to C<SvPV()> or one of its variants, in
+case any call to string overloading updates the internal UTF-8 encoding flag.
 #define DO_UTF8(sv) (SvUTF8(sv) && !IN_BYTES)
 #define IN_UNI_8_BIT \
            (((CopHINTS_get(PL_curcop) & (HINT_UNI_8_BIT))                       \