Skip to content

Commit

Permalink
Update pod for Perl_form() and kin
Browse files Browse the repository at this point in the history
This fixes GH Perl#22170, and includes several corrections.
  • Loading branch information
khwilliamson committed Apr 30, 2024
1 parent ed87f92 commit 6691533
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 7 deletions.
16 changes: 16 additions & 0 deletions pod/perldelta.pod
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,22 @@ XXX Description of the change here

=back

=head3 L<perlapi/form>

=over 4

=item *

Corrected the documentation for C<Perl_form>, C<form_nocontext>, and
C<vform>, which claimed that any later call to one of them will destroy
the previous returns from any. This hasn't been true since 5.6.0,
except it does remain true if these are called during global
destruction. With that caveat, the return of each of these is a fresh
string in a temporary that will automatically be freed by a call to
L<perlapi/C<FREETMPS>> or at at places such as statement boundaries.

=back

=head1 Diagnostics

The following additions or changes have been made to diagnostic output,
Expand Down
21 changes: 14 additions & 7 deletions util.c
Original file line number Diff line number Diff line change
Expand Up @@ -1419,22 +1419,29 @@ Perl_form_nocontext(const char* pat, ...)
These take a sprintf-style format pattern and conventional
(non-SV) arguments and return the formatted string.
(char *) Perl_form(pTHX_ const char* pat, ...)
(char *) Perl_form(aTHX_ const char* pat, ...)
can be used any place a string (char *) is required:
They can be used any place a string (char *) is required:
char * s = Perl_form("%d.%d",major,minor);
char * s = form_nocontext("%d.%d", major, minor);
They use a single (per-thread) private buffer so if you want to format several
strings you must explicitly copy the earlier strings away (and free the copies
when you are done).
They each return a temporary that will be freed "soon", automatically by the
system, at the same time that SVs operated on by C<L</sv_2mortal>> are freed.
Use the result immediately, or copy to a stable place for longer retention.
This is contrary to the incorrect previous documentation of these that claimed
that the return was a single per-thread buffer. That was (and is) actually
true only when these are called during global destruction.
The two forms differ only in that C<form_nocontext> does not take a thread
context (C<aTHX>) parameter, so is used in situations where the caller doesn't
already have the thread context.
C<L</vform>> is the same except the arguments are an encapsulated argument list.
=for apidoc vform
Like C<L</form>> but but the arguments are an encapsulated argument list.
Like C<L</form>> except the arguments are an encapsulated argument list.
=cut
*/
Expand Down

0 comments on commit 6691533

Please sign in to comment.