.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Array::PrintCols 3"
.TH Array::PrintCols 3 "2015-08-21" "perl v5.22.0" "User Contributed Perl Documentation"
.\" 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"
Array::PrintCols \- Print or format array elements in vertically sorted columns.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\f(CW\*(C`use Array::PrintCols;\*(C'\fR
.PP
\&\f(CW\*(C`print_cols \e@\f(CIarray\f(CW;\*(C'\fR
.PP
\&\f(CW\*(C`print_cols \e@\f(CIarray\f(CW, $\f(CIcolspec\f(CW;\*(C'\fR
.PP
\&\f(CW\*(C`print_cols \e@\f(CIarray\f(CW, $\f(CIcolspec\f(CW, $\f(CItotal_width\f(CW;\*(C'\fR
.PP
\&\f(CW\*(C`print_cols \e@\f(CIarray\f(CW, $\f(CIcolspec\f(CW, $\f(CItotal_width\f(CW, $\f(CIindent\f(CW;\*(C'\fR
.PP
.Vb 1
\&             \e@I<array> may also be an ARRAYREF, HASH, or HASHREF.
.Ve
.PP
$\fIoutput\fR = \f(CW\*(C`format_cols\*(C'\fR <same arguments as \f(CW\*(C`print_cols\*(C'\fR>;
.PP
\&\f(CW\*(C`$Array::PrintCols::PreSorted = 0;\*(C'\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module exports two subroutine names: \f(CW\*(C`print_cols\*(C'\fR and
\&\f(CW\*(C`format_cols\*(C'\fR.
.PP
The \f(CW\*(C`print_cols\*(C'\fR subroutine prints the items of \f(CW\*(C`@\f(CIarray\f(CW\*(C'\fR in
multiple, alphabetically & vertically sorted columns.  In the case
of the first argument being a \s-1HASH\s0 or \s-1HASHREF,\s0 only the keys of
the hash are considered.
.PP
One, two, or three optional arguments may be given to
\&\f(CW\*(C`print_cols\*(C'\fR to control the width and number of the columns, the
total width of the output, and indentation.  Reasonable defaults
apply in the absence of the optional arguments (or when given as
the empty string or zero).  Generally, the minimum width column is
used when possible.
.PP
If \f(CW\*(C`$\f(CIcolspec\f(CW\*(C'\fR is given as a non-negative number, it is treated
as the minimum width of the column; the actual width will be the
maximum of this value and the lengths of all array items.
.PP
If \f(CW\*(C`$\f(CIcolspec\f(CW\*(C'\fR is given as a negative number, its absolute
value value is used to determine the total number of columns.
However, it cannot exceed the total number of columns possible
based on the maximum length of all the array elements.
.PP
If a third argument is supplied, it is used as the total width of
the output.  The default for this value is the value of the
environment variable \f(CW$ENV{\*(AqCOLUMNS\*(Aq}\fR, if defined, or 80.
.PP
If the fourth argument is given, it is used as the indent for all
lines printed, which subtracts from the total width of the output.
This value defaults to zero (ie: no indention of the output).
.PP
The variable \f(CW$Array::PrintCols::PreSorted\fR controls whether or
not the \f(CW\*(C`print_cols\*(C'\fR subroutine will expect its array argument to
already be sorted.  If this variable is nil or zero, \f(CW\*(C`print_cols\*(C'\fR
will cause print out a sorted \fIcopy\fR of the input array.
.PP
The routine \f(CW\*(C`format_cols\*(C'\fR is called exactly like \f(CW\*(C`print_cols\*(C'\fR
but returns the formatted result as a string, rather than printing
it.  \f(CW\*(C`print_cols\*(C'\fR actually invokes \f(CW\*(C`format_cols\*(C'\fR, which does 
the real work.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 1
\&    use Array::PrintCols;
\&
\&    @commands = sort qw( use list put get set quit help server );
\&
\&    # print in three columns with an indention of 1.
\&    print_cols \e@commands, \-3, 0, 1;
\&
\&    # print the formatted result data to the result file
\&    print RESULTFILE format_cols(\e@result_data);
.Ve
.SH "REPOSITORY"
.IX Header "REPOSITORY"
<https://github.com/aks/array\-printcols>
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (C) 1996\-2014  Alan K. Stebbens <aks@stebbens.org>
.PP
This program is free software: you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE. \s0 See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
.SH "BUGS"
.IX Header "BUGS"
Perl will not default intervening empty arguments; instead, use zero or the
empty-string ('').