Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 205 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/Tie::Array.3perl b/upstream/archlinux/man3/Tie::Array.3perl
new file mode 100644
index 00000000..6663fdc9
--- /dev/null
+++ b/upstream/archlinux/man3/Tie::Array.3perl
@@ -0,0 +1,205 @@
+.\" -*- 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 "Tie::Array 3perl"
+.TH Tie::Array 3perl 2024-02-11 "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
+Tie::Array \- base class for tied arrays
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 3
+\&    package Tie::NewArray;
+\&    use Tie::Array;
+\&    @ISA = (\*(AqTie::Array\*(Aq);
+\&
+\&    # mandatory methods
+\&    sub TIEARRAY { ... }
+\&    sub FETCH { ... }
+\&    sub FETCHSIZE { ... }
+\&
+\&    sub STORE { ... }       # mandatory if elements writeable
+\&    sub STORESIZE { ... }   # mandatory if elements can be added/deleted
+\&    sub EXISTS { ... }      # mandatory if exists() expected to work
+\&    sub DELETE { ... }      # mandatory if delete() expected to work
+\&
+\&    # optional methods \- for efficiency
+\&    sub CLEAR { ... }
+\&    sub PUSH { ... }
+\&    sub POP { ... }
+\&    sub SHIFT { ... }
+\&    sub UNSHIFT { ... }
+\&    sub SPLICE { ... }
+\&    sub EXTEND { ... }
+\&    sub DESTROY { ... }
+\&
+\&    package Tie::NewStdArray;
+\&    use Tie::Array;
+\&
+\&    @ISA = (\*(AqTie::StdArray\*(Aq);
+\&
+\&    # all methods provided by default
+\&
+\&    package main;
+\&
+\&    $object = tie @somearray,\*(AqTie::NewArray\*(Aq;
+\&    $object = tie @somearray,\*(AqTie::StdArray\*(Aq;
+\&    $object = tie @somearray,\*(AqTie::NewStdArray\*(Aq;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This module provides methods for array-tying classes. See
+perltie for a list of the functions required in order to tie an array
+to a package. The basic \fBTie::Array\fR package provides stub \f(CW\*(C`DESTROY\*(C'\fR,
+and \f(CW\*(C`EXTEND\*(C'\fR methods that do nothing, stub \f(CW\*(C`DELETE\*(C'\fR and \f(CW\*(C`EXISTS\*(C'\fR
+methods that \fBcroak()\fR if the \fBdelete()\fR or \fBexists()\fR builtins are ever called
+on the tied array, and implementations of \f(CW\*(C`PUSH\*(C'\fR, \f(CW\*(C`POP\*(C'\fR, \f(CW\*(C`SHIFT\*(C'\fR,
+\&\f(CW\*(C`UNSHIFT\*(C'\fR, \f(CW\*(C`SPLICE\*(C'\fR and \f(CW\*(C`CLEAR\*(C'\fR in terms of basic \f(CW\*(C`FETCH\*(C'\fR, \f(CW\*(C`STORE\*(C'\fR,
+\&\f(CW\*(C`FETCHSIZE\*(C'\fR, \f(CW\*(C`STORESIZE\*(C'\fR.
+.PP
+The \fBTie::StdArray\fR package provides efficient methods required for tied arrays
+which are implemented as blessed references to an "inner" perl array.
+It inherits from \fBTie::Array\fR, and should cause tied arrays to behave exactly
+like standard arrays, allowing for selective overloading of methods.
+.PP
+For developers wishing to write their own tied arrays, the required methods
+are briefly defined below. See the perltie section for more detailed
+descriptive, as well as example code:
+.IP "TIEARRAY classname, LIST" 4
+.IX Item "TIEARRAY classname, LIST"
+The class method is invoked by the command \f(CW\*(C`tie @array, classname\*(C'\fR. Associates
+an array instance with the specified class. \f(CW\*(C`LIST\*(C'\fR would represent
+additional arguments (along the lines of AnyDBM_File and compatriots) needed
+to complete the association. The method should return an object of a class which
+provides the methods below.
+.IP "STORE this, index, value" 4
+.IX Item "STORE this, index, value"
+Store datum \fIvalue\fR into \fIindex\fR for the tied array associated with
+object \fIthis\fR. If this makes the array larger then
+class's mapping of \f(CW\*(C`undef\*(C'\fR should be returned for new positions.
+.IP "FETCH this, index" 4
+.IX Item "FETCH this, index"
+Retrieve the datum in \fIindex\fR for the tied array associated with
+object \fIthis\fR.
+.IP "FETCHSIZE this" 4
+.IX Item "FETCHSIZE this"
+Returns the total number of items in the tied array associated with
+object \fIthis\fR. (Equivalent to \f(CWscalar(@array)\fR).
+.IP "STORESIZE this, count" 4
+.IX Item "STORESIZE this, count"
+Sets the total number of items in the tied array associated with
+object \fIthis\fR to be \fIcount\fR. If this makes the array larger then
+class's mapping of \f(CW\*(C`undef\*(C'\fR should be returned for new positions.
+If the array becomes smaller then entries beyond count should be
+deleted.
+.IP "EXTEND this, count" 4
+.IX Item "EXTEND this, count"
+Informative call that array is likely to grow to have \fIcount\fR entries.
+Can be used to optimize allocation. This method need do nothing.
+.IP "EXISTS this, key" 4
+.IX Item "EXISTS this, key"
+Verify that the element at index \fIkey\fR exists in the tied array \fIthis\fR.
+.Sp
+The \fBTie::Array\fR implementation is a stub that simply croaks.
+.IP "DELETE this, key" 4
+.IX Item "DELETE this, key"
+Delete the element at index \fIkey\fR from the tied array \fIthis\fR.
+.Sp
+The \fBTie::Array\fR implementation is a stub that simply croaks.
+.IP "CLEAR this" 4
+.IX Item "CLEAR this"
+Clear (remove, delete, ...) all values from the tied array associated with
+object \fIthis\fR.
+.IP "DESTROY this" 4
+.IX Item "DESTROY this"
+Normal object destructor method.
+.IP "PUSH this, LIST" 4
+.IX Item "PUSH this, LIST"
+Append elements of LIST to the array.
+.IP "POP this" 4
+.IX Item "POP this"
+Remove last element of the array and return it.
+.IP "SHIFT this" 4
+.IX Item "SHIFT this"
+Remove the first element of the array (shifting other elements down)
+and return it.
+.IP "UNSHIFT this, LIST" 4
+.IX Item "UNSHIFT this, LIST"
+Insert LIST elements at the beginning of the array, moving existing elements
+up to make room.
+.IP "SPLICE this, offset, length, LIST" 4
+.IX Item "SPLICE this, offset, length, LIST"
+Perform the equivalent of \f(CW\*(C`splice\*(C'\fR on the array.
+.Sp
+\&\fIoffset\fR is optional and defaults to zero, negative values count back
+from the end of the array.
+.Sp
+\&\fIlength\fR is optional and defaults to rest of the array.
+.Sp
+\&\fILIST\fR may be empty.
+.Sp
+Returns a list of the original \fIlength\fR elements at \fIoffset\fR.
+.SH CAVEATS
+.IX Header "CAVEATS"
+There is no support at present for tied \f(CW@ISA\fR. There is a potential conflict
+between magic entries needed to notice setting of \f(CW@ISA\fR, and those needed to
+implement 'tie'.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Nick Ing-Simmons <nik@tiuk.ti.com>