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 #22170, and includes several corrections.
  • Loading branch information
khwilliamson committed Apr 30, 2024
1 parent 404e97f commit e5f58f2
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
Expand Up @@ -183,6 +183,22 @@ itself on Windows or Cygwin.

=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
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 e5f58f2

Please sign in to comment.