Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

builtin: document when each function was first available and stabilized #22301

Merged
merged 1 commit into from
Jun 22, 2024
Merged

builtin: document when each function was first available and stabilized #22301

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 67 additions & 1 deletion lib/builtin.pm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,10 @@ distinguished boolean value.

This gives an equivalent value to expressions like C<!!1> or C<!0>.

Available starting with Perl 5.36. Since Perl 5.40, it is no longer
experimental and it is included in the 5.40 and higher builtin version
bundles.

=head2 false

$val = false;
Expand All @@ -129,6 +133,10 @@ it to be a distinguished boolean value.

This gives an equivalent value to expressions like C<!!0> or C<!1>.

Available starting with Perl 5.36. Since Perl 5.40, it is no longer
experimental and it is included in the 5.40 and higher builtin version
bundles.

=head2 is_bool

$bool = is_bool($val);
Expand All @@ -144,6 +152,8 @@ or any variable containing one of these results.
This function used to be named C<isbool>. A compatibility alias is provided
currently but will be removed in a later version.

Available starting with Perl 5.36.

=head2 inf

$num = inf;
Expand All @@ -152,6 +162,8 @@ This function is currently B<experimental>.

Returns the floating-point infinity value.

Available starting with Perl 5.40.

=head2 nan

$num = nan;
Expand All @@ -160,6 +172,8 @@ This function is currently B<experimental>.

Returns the floating-point "Not-a-Number" value.

Available starting with Perl 5.40.

=head2 weaken

weaken($ref);
Expand All @@ -169,12 +183,20 @@ count of its referent. If only weakened references to a referent remain, it
will be disposed of, and all remaining weak references to it will have their
value set to C<undef>.

Available starting with Perl 5.36. Since Perl 5.40, it is no longer
experimental and it is included in the 5.40 and higher builtin version
bundles.

=head2 unweaken

unweaken($ref);

Strengthens a reference, undoing the effects of a previous call to L</weaken>.

Available starting with Perl 5.36. Since Perl 5.40, it is no longer
experimental and it is included in the 5.40 and higher builtin version
bundles.

=head2 is_weak

$bool = is_weak($ref);
Expand All @@ -185,13 +207,21 @@ not weak.
This function used to be named C<isweak>. A compatibility alias is provided
currently but will be removed in a later version.

Available starting with Perl 5.36. Since Perl 5.40, it is no longer
experimental and it is included in the 5.40 and higher builtin version
bundles.

=head2 blessed

$str = blessed($ref);

Returns the package name for an object reference, or C<undef> for a
non-reference or reference that is not an object.

Available starting with Perl 5.36. Since Perl 5.40, it is no longer
experimental and it is included in the 5.40 and higher builtin version
bundles.

=head2 refaddr

$num = refaddr($ref);
Expand All @@ -200,6 +230,10 @@ Returns the memory address for a reference, or C<undef> for a non-reference.
This value is not likely to be very useful for pure Perl code, but is handy as
a means to test for referential identity or uniqueness.

Available starting with Perl 5.36. Since Perl 5.40, it is no longer
experimental and it is included in the 5.40 and higher builtin version
bundles.

=head2 reftype

$str = reftype($ref);
Expand All @@ -208,6 +242,10 @@ Returns the basic container type of the referent of a reference, or C<undef>
for a non-reference. This is returned as a string in all-capitals, such as
C<ARRAY> for array references, or C<HASH> for hash references.

Available starting with Perl 5.36. Since Perl 5.40, it is no longer
experimental and it is included in the 5.40 and higher builtin version
bundles.

=head2 created_as_string

$bool = created_as_string($val);
Expand All @@ -231,6 +269,8 @@ strings. For example

if( created_as_string $val ) { ... } # this will not execute

Available starting with Perl 5.36.

=head2 created_as_number

$bool = created_as_number($val);
Expand Down Expand Up @@ -260,6 +300,8 @@ serialisation modules such as JSON encoders or similar situations, where
language interoperability concerns require making a distinction between values
that are fundamentally stringlike versus numberlike in nature.

Available starting with Perl 5.36.

=head2 stringify

$str = stringify($val);
Expand All @@ -282,20 +324,30 @@ overload will return a string that names the underlying container type of
the reference, its memory address, and possibly its class name if it is an
object.

Available starting with Perl 5.40.

=head2 ceil

$num = ceil($num);

Returns the smallest integer value greater than or equal to the given
numerical argument.

Available starting with Perl 5.36. Since Perl 5.40, it is no longer
experimental and it is included in the 5.40 and higher builtin version
bundles.

=head2 floor

$num = floor($num);

Returns the largest integer value less than or equal to the given numerical
argument.

Available starting with Perl 5.36. Since Perl 5.40, it is no longer
experimental and it is included in the 5.40 and higher builtin version
bundles.

=head2 indexed

@ivpairs = indexed(@items)
Expand Down Expand Up @@ -324,6 +376,10 @@ C<foreach> loop syntax; as
In scalar context this function returns the size of the list that it would
otherwise have returned, and provokes a warning in the C<scalar> category.

Available starting with Perl 5.36. Since Perl 5.40, it is no longer
experimental and it is included in the 5.40 and higher builtin version
bundles.

=head2 trim

$stripped = trim($string);
Expand Down Expand Up @@ -351,7 +407,11 @@ C<trim> is equivalent to:

$str =~ s/\A\s+|\s+\z//urg;

For Perl versions where this feature is not available look at the
Available starting with Perl 5.36. Since Perl 5.40, it is no longer
experimental and it is included in the 5.40 and higher builtin version
bundles.

For Perl versions where this function is not available look at the
L<String::Util> module for a comparable implementation.

=head2 is_tainted
Expand All @@ -360,6 +420,8 @@ L<String::Util> module for a comparable implementation.

Returns true when given a tainted variable.

Available starting with Perl 5.38.

=head2 export_lexically

export_lexically($name1, $ref1, $name2, $ref2, ...)
Expand Down Expand Up @@ -391,6 +453,8 @@ This must be called at compile time; which typically means during a C<BEGIN>
block. Usually this would be used as part of an C<import> method of a module,
when invoked as part of a C<use ...> statement.

Available starting with Perl 5.38.

=head2 load_module

load_module($module_name);
Expand All @@ -410,6 +474,8 @@ L<the C<module_true> feature|feature/"The 'module_true' feature">.
C<load_module> can't be used to require a particular version of Perl, nor can
it be given a bareword module name as an argument.

Available starting with Perl 5.40.

=head1 SEE ALSO

L<perlop>, L<perlfunc>, L<Scalar::Util>
Loading