This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Note that STR_WITH_LEN() is unorthodox
authorKarl Williamson <khw@cpan.org>
Sat, 31 Aug 2019 20:45:25 +0000 (14:45 -0600)
committerKarl Williamson <khw@cpan.org>
Tue, 3 Sep 2019 03:52:12 +0000 (21:52 -0600)
Now that we have the 'u' flag for macros, this one returns
a pair of values, so should be marked as such.

handy.h

diff --git a/handy.h b/handy.h
index 895456f..dc08ef3 100644 (file)
--- a/handy.h
+++ b/handy.h
@@ -370,14 +370,22 @@ a string/length pair.
 =cut
 */
 
-/* concatenating with "" ensures that only literal strings are accepted as
- * argument */
-#define STR_WITH_LEN(s)  ("" s ""), (sizeof(s)-1)
+/*
+=head1 Handy Values
 
-/* note that STR_WITH_LEN() can't be used as argument to macros or functions
- * that under some configurations might be macros, which means that it requires
- * the full Perl_xxx(aTHX_ ...) form for any API calls where it's used.
- */
+=for apidoc Amu|pair|STR_WITH_LEN|"literal string"
+
+Returns two comma separated tokens of the input literal string, and its length.
+This is convenience macro which helps out in some API calls.
+Note that it can't be used as an argument to macros or functions that under
+some configurations might be macros, which means that it requires the full
+Perl_xxx(aTHX_ ...) form for any API calls where it's used.
+
+=cut
+*/
+
+
+#define STR_WITH_LEN(s)  ("" s ""), (sizeof(s)-1)
 
 /* STR_WITH_LEN() shortcuts */
 #define newSVpvs(str) Perl_newSVpvn(aTHX_ STR_WITH_LEN(str))