This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlapi: Document NATIVE_to_foo, converse functions
authorKarl Williamson <khw@cpan.org>
Mon, 5 Aug 2019 00:00:01 +0000 (18:00 -0600)
committerKarl Williamson <khw@cpan.org>
Tue, 3 Sep 2019 03:52:10 +0000 (21:52 -0600)
utf8.h

diff --git a/utf8.h b/utf8.h
index 88e74de..8ab27f5 100644 (file)
--- a/utf8.h
+++ b/utf8.h
@@ -150,8 +150,51 @@ END_EXTERN_C
 #define PERL_SMALL_MACRO_BUFFER
 #endif
 
-/* Native character to/from iso-8859-1.  Are the identity functions on ASCII
- * platforms */
+/*
+
+=for apidoc Am|U8|NATIVE_TO_LATIN1|U8 ch
+
+Returns the Latin-1 (including ASCII and control characters) equivalent of the
+input native code point given by C<ch>.  Thus, C<NATIVE_TO_LATIN1(193)> on
+EBCDIC platforms returns 65.  These each represent the character C<"A"> on
+their respective platforms.  On ASCII platforms no conversion is needed, so
+this macro expands to just its input, adding no time nor space requirements to
+the implementation.
+
+For conversion of code points potentially larger than will fit in a character,
+use L</NATIVE_TO_UNI>.
+
+=for apidoc Am|U8|LATIN1_TO_NATIVE|U8 ch
+
+Returns the native  equivalent of the input Latin-1 code point (including ASCII
+and control characters) given by C<ch>.  Thus, C<LATIN1_TO_NATIVE(66)> on
+EBCDIC platforms returns 194.  These each represent the character C<"B"> on
+their respective platforms.  On ASCII platforms no conversion is needed, so
+this macro expands to just its input, adding no time nor space requirements to
+the implementation.
+
+For conversion of code points potentially larger than will fit in a character,
+use L</UNI_TO_NATIVE>.
+
+=for apidoc Am|UV|NATIVE_TO_UNI|UV ch
+
+Returns the Unicode  equivalent of the input native code point given by C<ch>.
+Thus, C<NATIVE_TO_UNI(195)> on EBCDIC platforms returns 67.  These each
+represent the character C<"C"> on their respective platforms.  On ASCII
+platforms no conversion is needed, so this macro expands to just its input,
+adding no time nor space requirements to the implementation.
+
+=for apidoc Am|UV|UNI_TO_NATIVE|UV ch
+
+Returns the native  equivalent of the input Unicode code point  given by C<ch>.
+Thus, C<UNI_TO_NATIVE(68)> on EBCDIC platforms returns 196.  These each
+represent the character C<"D"> on their respective platforms.  On ASCII
+platforms no conversion is needed, so this macro expands to just its input,
+adding no time nor space requirements to the implementation.
+
+=cut
+*/
+
 #ifdef PERL_SMALL_MACRO_BUFFER
 #define NATIVE_TO_LATIN1(ch)     ((U8)(ch))
 #define LATIN1_TO_NATIVE(ch)     ((U8)(ch))
@@ -174,7 +217,6 @@ END_EXTERN_C
 #define I8_TO_NATIVE_UTF8(ch) (__ASSERT_(FITS_IN_8_BITS(ch)) ((U8) (ch)))
 #endif
 
-/* Transforms in wide UV chars */
 #define UNI_TO_NATIVE(ch)        ((UV) (ch))
 #define NATIVE_TO_UNI(ch)        ((UV) (ch))