Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 409 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/builtin.3perl b/upstream/debian-unstable/man3/builtin.3perl
new file mode 100644
index 00000000..494087f2
--- /dev/null
+++ b/upstream/debian-unstable/man3/builtin.3perl
@@ -0,0 +1,409 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "builtin 3perl"
+.TH builtin 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+builtin \- Perl pragma to import built\-in utility functions
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 11
+\&    use builtin qw(
+\&        true false is_bool
+\&        weaken unweaken is_weak
+\&        blessed refaddr reftype
+\&        created_as_string created_as_number
+\&        ceil floor
+\&        indexed
+\&        trim
+\&        is_tainted
+\&        export_lexically
+\&    );
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl provides several utility functions in the \f(CW\*(C`builtin\*(C'\fR package. These are
+plain functions, and look and behave just like regular user-defined functions
+do. They do not provide new syntax or require special parsing. These functions
+are always present in the interpreter and can be called at any time by their
+fully-qualified names. By default they are not available as short names, but
+can be requested for convenience.
+.PP
+Individual named functions can be imported by listing them as import
+parameters on the \f(CW\*(C`use\*(C'\fR statement for this pragma.
+.PP
+The overall \f(CW\*(C`builtin\*(C'\fR mechanism, as well as every individual function it
+provides, are currently \fBexperimental\fR.
+.PP
+\&\fBWarning\fR:  At present, the entire \f(CW\*(C`builtin\*(C'\fR namespace is experimental.
+Calling functions in it will trigger warnings of the \f(CW\*(C`experimental::builtin\*(C'\fR
+category.
+.SS "Lexical Import"
+.IX Subsection "Lexical Import"
+This pragma module creates \fIlexical\fR aliases in the currently-compiling scope
+to these builtin functions. This is similar to the lexical effect of other
+pragmas such as strict and feature.
+.PP
+.Vb 3
+\&    sub classify
+\&    {
+\&        my $val = shift;
+\&
+\&        use builtin \*(Aqis_bool\*(Aq;
+\&        return is_bool($val) ? "boolean" : "not a boolean";
+\&    }
+\&
+\&    # the is_bool() function is no longer visible here
+\&    # but may still be called by builtin::is_bool()
+.Ve
+.PP
+Because these functions are imported lexically, rather than by package
+symbols, the user does not need to take any special measures to ensure they
+don't accidentally appear as object methods from a class.
+.PP
+.Vb 4
+\&    package An::Object::Class {
+\&        use builtin \*(Aqtrue\*(Aq, \*(Aqfalse\*(Aq;
+\&        ...
+\&    }
+\&
+\&    # does not appear as a method
+\&    An::Object::Class\->true;
+\&
+\&    # Can\*(Aqt locate object method "true" via package "An::Object::Class"
+\&    #   at ...
+.Ve
+.SH FUNCTIONS
+.IX Header "FUNCTIONS"
+.SS true
+.IX Subsection "true"
+.Vb 1
+\&    $val = true;
+.Ve
+.PP
+Returns the boolean truth value. While any scalar value can be tested for
+truth and most defined, non-empty and non-zero values are considered "true"
+by perl, this one is special in that "is_bool" considers it to be a
+distinguished boolean value.
+.PP
+This gives an equivalent value to expressions like \f(CW\*(C`!!1\*(C'\fR or \f(CW\*(C`!0\*(C'\fR.
+.SS false
+.IX Subsection "false"
+.Vb 1
+\&    $val = false;
+.Ve
+.PP
+Returns the boolean fiction value. While any non-true scalar value is
+considered "false" by perl, this one is special in that "is_bool" considers
+it to be a distinguished boolean value.
+.PP
+This gives an equivalent value to expressions like \f(CW\*(C`!!0\*(C'\fR or \f(CW\*(C`!1\*(C'\fR.
+.SS is_bool
+.IX Subsection "is_bool"
+.Vb 1
+\&    $bool = is_bool($val);
+.Ve
+.PP
+Returns true when given a distinguished boolean value, or false if not. A
+distinguished boolean value is the result of any boolean-returning builtin
+function (such as \f(CW\*(C`true\*(C'\fR or \f(CW\*(C`is_bool\*(C'\fR itself), boolean-returning operator
+(such as the \f(CW\*(C`eq\*(C'\fR or \f(CW\*(C`==\*(C'\fR comparison tests or the \f(CW\*(C`!\*(C'\fR negation operator),
+or any variable containing one of these results.
+.PP
+This function used to be named \f(CW\*(C`isbool\*(C'\fR. A compatibility alias is provided
+currently but will be removed in a later version.
+.SS weaken
+.IX Subsection "weaken"
+.Vb 1
+\&    weaken($ref);
+.Ve
+.PP
+Weakens a reference. A weakened reference does not contribute to the reference
+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 \f(CW\*(C`undef\*(C'\fR.
+.SS unweaken
+.IX Subsection "unweaken"
+.Vb 1
+\&    unweaken($ref);
+.Ve
+.PP
+Strengthens a reference, undoing the effects of a previous call to "weaken".
+.SS is_weak
+.IX Subsection "is_weak"
+.Vb 1
+\&    $bool = is_weak($ref);
+.Ve
+.PP
+Returns true when given a weakened reference, or false if not a reference or
+not weak.
+.PP
+This function used to be named \f(CW\*(C`isweak\*(C'\fR. A compatibility alias is provided
+currently but will be removed in a later version.
+.SS blessed
+.IX Subsection "blessed"
+.Vb 1
+\&    $str = blessed($ref);
+.Ve
+.PP
+Returns the package name for an object reference, or \f(CW\*(C`undef\*(C'\fR for a
+non-reference or reference that is not an object.
+.SS refaddr
+.IX Subsection "refaddr"
+.Vb 1
+\&    $num = refaddr($ref);
+.Ve
+.PP
+Returns the memory address for a reference, or \f(CW\*(C`undef\*(C'\fR 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.
+.SS reftype
+.IX Subsection "reftype"
+.Vb 1
+\&    $str = reftype($ref);
+.Ve
+.PP
+Returns the basic container type of the referent of a reference, or \f(CW\*(C`undef\*(C'\fR
+for a non-reference. This is returned as a string in all-capitals, such as
+\&\f(CW\*(C`ARRAY\*(C'\fR for array references, or \f(CW\*(C`HASH\*(C'\fR for hash references.
+.SS created_as_string
+.IX Subsection "created_as_string"
+.Vb 1
+\&    $bool = created_as_string($val);
+.Ve
+.PP
+Returns a boolean representing if the argument value was originally created as
+a string. It will return true for any scalar expression whose most recent
+assignment or modification was of a string-like nature \- such as assignment
+from a string literal, or the result of a string operation such as
+concatenation or regexp. It will return false for references (including any
+object), numbers, booleans and undef.
+.PP
+It is unlikely that you will want to use this for regular data validation
+within Perl, as it will not return true for regular numbers that are still
+perfectly usable as strings, nor for any object reference \- especially objects
+that overload the stringification operator in an attempt to behave more like
+strings. For example
+.PP
+.Vb 1
+\&    my $val = URI\->new( "https://metacpan.org/" );
+\&
+\&    if( created_as_string $val ) { ... }    # this will not execute
+.Ve
+.SS created_as_number
+.IX Subsection "created_as_number"
+.Vb 1
+\&    $bool = created_as_number($val);
+.Ve
+.PP
+Returns a boolean representing if the argument value was originally created as
+a number. It will return true for any scalar expression whose most recent
+assignment or modification was of a numerical nature \- such as assignment from
+a number literal, or the result of a numerical operation such as addition. It
+will return false for references (including any object), strings, booleans and
+undef.
+.PP
+It is unlikely that you will want to use this for regular data validation
+within Perl, as it will not return true for regular strings of decimal digits
+that are still perfectly usable as numbers, nor for any object reference \-
+especially objects that overload the numification operator in an attempt to
+behave more like numbers. For example
+.PP
+.Vb 1
+\&    my $val = Math::BigInt\->new( 123 );
+\&
+\&    if( created_as_number $val ) { ... }    # this will not execute
+.Ve
+.PP
+While most Perl code should operate on scalar values without needing to know
+their creation history, these two functions are intended to be used by data
+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.
+.SS ceil
+.IX Subsection "ceil"
+.Vb 1
+\&    $num = ceil($num);
+.Ve
+.PP
+Returns the smallest integer value greater than or equal to the given
+numerical argument.
+.SS floor
+.IX Subsection "floor"
+.Vb 1
+\&    $num = floor($num);
+.Ve
+.PP
+Returns the largest integer value less than or equal to the given numerical
+argument.
+.SS indexed
+.IX Subsection "indexed"
+.Vb 1
+\&    @ivpairs = indexed(@items)
+.Ve
+.PP
+Returns an even-sized list of number/value pairs, where each pair is formed
+of a number giving an index in the original list followed by the value at that
+position in it.  I.e. returns a list twice the size of the original, being
+equal to
+.PP
+.Vb 1
+\&    (0, $items[0], 1, $items[1], 2, $items[2], ...)
+.Ve
+.PP
+Note that unlike the core \f(CW\*(C`values\*(C'\fR function, this function returns copies of
+its original arguments, not aliases to them. Any modifications of these copies
+are \fInot\fR reflected in modifications to the original.
+.PP
+.Vb 2
+\&    my @x = ...;
+\&    $_++ for indexed @x;  # The @x array remains unaffected
+.Ve
+.PP
+This function is primarily intended to be useful combined with multi-variable
+\&\f(CW\*(C`foreach\*(C'\fR loop syntax; as
+.PP
+.Vb 3
+\&    foreach my ($index, $value) (indexed LIST) {
+\&        ...
+\&    }
+.Ve
+.PP
+In scalar context this function returns the size of the list that it would
+otherwise have returned, and provokes a warning in the \f(CW\*(C`scalar\*(C'\fR category.
+.SS trim
+.IX Subsection "trim"
+.Vb 1
+\&    $stripped = trim($string);
+.Ve
+.PP
+Returns the input string with whitespace stripped from the beginning
+and end. \fBtrim()\fR will remove these characters:
+.PP
+" ", an ordinary space.
+.PP
+"\et", a tab.
+.PP
+"\en", a new line (line feed).
+.PP
+"\er", a carriage return.
+.PP
+and all other Unicode characters that are flagged as whitespace.
+A complete list is in "Whitespace" in perlrecharclass.
+.PP
+.Vb 4
+\&    $var = "  Hello world   ";            # "Hello world"
+\&    $var = "\et\et\etHello world";           # "Hello world"
+\&    $var = "Hello world\en";               # "Hello world"
+\&    $var = "\ex{2028}Hello world\ex{3000}"; # "Hello world"
+.Ve
+.PP
+\&\f(CW\*(C`trim\*(C'\fR is equivalent to:
+.PP
+.Vb 1
+\&    $str =~ s/\eA\es+|\es+\ez//urg;
+.Ve
+.PP
+For Perl versions where this feature is not available look at the
+String::Util module for a comparable implementation.
+.SS is_tainted
+.IX Subsection "is_tainted"
+.Vb 1
+\&    $bool = is_tainted($var);
+.Ve
+.PP
+Returns true when given a tainted variable.
+.SS export_lexically
+.IX Subsection "export_lexically"
+.Vb 1
+\&    export_lexically($name1, $ref1, $name2, $ref2, ...)
+.Ve
+.PP
+Exports new lexical names into the scope currently being compiled. Names given
+by the first of each pair of values will refer to the corresponding item whose
+reference is given by the second. Types of item that are permitted are
+subroutines, and scalar, array, and hash variables. If the item is a
+subroutine, the name may optionally be prefixed with the \f(CW\*(C`&\*(C'\fR sigil, but for
+convenience it doesn't have to. For items that are variables the sigil is
+required, and must match the type of the variable.
+.PP
+.Vb 2
+\&    export_lexically func    => \e&func,
+\&                     \*(Aq&func\*(Aq => \e&func;  # same as above
+\&
+\&    export_lexically \*(Aq$scalar\*(Aq => \emy $var;
+.Ve
+.PP
+
+.PP
+.Vb 3
+\&    # The following are not permitted
+\&    export_lexically \*(Aq$var\*(Aq => \e@arr;   # sigil does not match
+\&    export_lexically name => \e$scalar;  # implied \*(Aq&\*(Aq sigil does not match
+\&
+\&    export_lexically \*(Aq*name\*(Aq => \e*globref;  # globrefs are not supported
+.Ve
+.PP
+This must be called at compile time; which typically means during a \f(CW\*(C`BEGIN\*(C'\fR
+block. Usually this would be used as part of an \f(CW\*(C`import\*(C'\fR method of a module,
+when invoked as part of a \f(CW\*(C`use ...\*(C'\fR statement.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlop, perlfunc, Scalar::Util