.\" Automatically generated by Pod::Man 4.14 (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
..
.\" 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 >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 "Misc 3pm"
.TH Misc 3pm "2023-06-17" "perl v5.36.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"
PDL::IO::Misc \- misc IO routines for PDL
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Some basic I/O functionality: \s-1FITS,\s0 tables, byte-swapping
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use PDL::IO::Misc;
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "bswap2"
.IX Subsection "bswap2"
.Vb 1
\&  Signature: (x(); )
.Ve
.PP
Swaps pairs of bytes in argument x()
.PP
bswap2 does not process bad values.
It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
.SS "bswap4"
.IX Subsection "bswap4"
.Vb 1
\&  Signature: (x(); )
.Ve
.PP
Swaps quads of bytes in argument x()
.PP
bswap4 does not process bad values.
It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
.SS "bswap8"
.IX Subsection "bswap8"
.Vb 1
\&  Signature: (x(); )
.Ve
.PP
Swaps octets of bytes in argument x()
.PP
bswap8 does not process bad values.
It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
.SS "rcols"
.IX Subsection "rcols"
Read specified \s-1ASCII\s0 cols from a file into ndarrays and perl
arrays (also see \*(L"rgrep\*(R").
.PP
.Vb 5
\&  Usage:
\&    ($x,$y,...) = rcols( *HANDLE|"filename", { EXCLUDE => \*(Aq/^!/\*(Aq }, $col1, $col2, ... )
\&             $x = rcols( *HANDLE|"filename", { EXCLUDE => \*(Aq/^!/\*(Aq }, [] )
\&    ($x,$y,...) = rcols( *HANDLE|"filename", $col1, $col2, ..., { EXCLUDE => \*(Aq/^!/\*(Aq } )
\&    ($x,$y,...) = rcols( *HANDLE|"filename", "/foo/", $col1, $col2, ... )
.Ve
.PP
For each column number specified, a 1D output \s-1PDL\s0 will be
generated.  Anonymous arrays of column numbers generate
2D output ndarrays with dim0 for the column data and dim1
equal to the number of columns in the anonymous array(s).
.PP
An empty anonymous array as column specification will
produce a single output data ndarray with \fBdim\fR\|(1) equal
to the number of columns available.
.PP
There are two calling conventions \- the old version, where a
pattern can be specified after the filename/handle, and the
new version where options are given as as hash reference.
This reference can be given as either the second or last
argument.
.PP
The default behaviour is to ignore lines beginning with
a # character and lines that only consist of whitespace.
Options exist to only read from lines that match, or do
not match, supplied patterns, and to set the types of the
created ndarrays.
.PP
Can take file name or *HANDLE, and if no explicit column
numbers are specified, all are assumed. For the allowed types,
see \*(L"Datatype_conversions\*(R" in PDL::Core.
.PP
Options (case insensitive):
.PP
.Vb 2
\&  EXCLUDE or IGNORE
\&  \- ignore lines matching this pattern (default B<\*(Aq/^#/\*(Aq>).
\&  
\&  INCLUDE or KEEP
\&  \- only use lines which match this pattern (default B<\*(Aq\*(Aq>).
\&  
\&  LINES   
\&  \- a string pattern specifying which line numbers to use.
\&  Line numbers start at 0 and the syntax is \*(Aqa:b:c\*(Aq to use
\&  every c\*(Aqth matching line between a and b (default B<\*(Aq\*(Aq>).
\&  
\&  DEFTYPE
\&  \- default data type for stored data (if not specified, use the type 
\&  stored in C<$PDL::IO::Misc::deftype>, which starts off as B<double>).
\&  
\&  TYPES
\&  \- reference to an array of data types, one element for each column 
\&  to be read in.  Any missing columns use the DEFTYPE value (default B<[]>).
\&  
\&  COLSEP
\&  \- splits on this string/pattern/qr{} between columns of data. Defaults to
\&  $PDL::IO::Misc::defcolsep.
\&  
\&  PERLCOLS
\&  \- an array of column numbers which are to be read into perl arrays
\&  rather than ndarrays.  Any columns not specified in the explicit list
\&  of columns to read will be returned after the explicit columns.
\&  (default B<undef>).
\&
\&  COLIDS
\&  \- if defined to an array reference, it will be assigned the column
\&  ID values obtained by splitting the first line of the file in the
\&  identical fashion to the column data.
\&
\&  CHUNKSIZE
\&  \- the number of input data elements to batch together before appending
\&  to each output data ndarray (Default value is 100).  If CHUNKSIZE is
\&  greater than the number of lines of data to read, the entire file is
\&  slurped in, lines split, and perl lists of column data are generated.
\&  At the end, effectively pdl(@column_data) produces any result ndarrays.
\&
\&  VERBOSE
\&  \- be verbose about IO processing (default C<$PDL::vebose>)
.Ve
.PP
For example:
.PP
.Vb 3
\&  $x      = PDL\->rcols \*(Aqfile1\*(Aq;         # file1 has only one column of data
\&  $x      = PDL\->rcols \*(Aqfile2\*(Aq, [];     # file2 can have multiple columns, still 1 ndarray output
\&                                        # (empty array ref spec means all possible data fields)
\&
\&  ($x,$y) = rcols \*(Aqtable.csv\*(Aq, { COLSEP => \*(Aq,\*(Aq };  # read CSV data file
\&  ($x,$y) = rcols *STDOUT;  # default separator for lines like \*(Aq32 24\*(Aq
\&
\&  # read in lines containing the string foo, where the first
\&  # example also ignores lines that begin with a # character.
\&  ($x,$y,$z) = rcols \*(Aqfile2\*(Aq, 0,4,5, { INCLUDE => \*(Aq/foo/\*(Aq };
\&  ($x,$y,$z) = rcols \*(Aqfile2\*(Aq, 0,4,5, { INCLUDE => \*(Aq/foo/\*(Aq, EXCLUDE => \*(Aq\*(Aq };
\&
\&  # ignore the first 27 lines of the file, reading in as ushort\*(Aqs
\&  ($x,$y) = rcols \*(Aqfile3\*(Aq, { LINES => \*(Aq27:\-1\*(Aq, DEFTYPE => ushort };
\&  ($x,$y) = rcols \*(Aqfile3\*(Aq, { LINES => \*(Aq27:\*(Aq, TYPES => [ ushort, ushort ] };
\&
\&  # read in the first column as a perl array and the next two as ndarrays
\&  # with the perl column returned after the ndarray outputs
\&  ($x,$y,$name) = rcols \*(Aqfile4\*(Aq, 1, 2   , { PERLCOLS => [ 0 ] };
\&  printf "Number of names read in = %d\en", 1 + $#$name;
\&
\&  # read in the first column as a perl array and the next two as ndarrays
\&  # with PERLCOLS changing the type of the first returned value to perl list ref
\&  ($name,$x,$y) = rcols \*(Aqfile4\*(Aq, 0, 1, 2, { PERLCOLS => [ 0 ] };
\&
\&  # read in the first column as a perl array returned first followed by the
\&  # the next two data columns in the file as a single Nx2 ndarray 
\&  ($name,$xy) = rcols \*(Aqfile4\*(Aq, 0, [1, 2], { PERLCOLS => [ 0 ] };
\&
\&  NOTES:
\&
\&  1. Quotes are required on patterns or use the qr{} quote regexp syntax.
\&  
\&  2. Columns are separated by whitespace by default, use the COLSEP option
\&     separator to specify an alternate split pattern or string or specify an
\&     alternate default separator by setting C<$PDL::IO::Misc::defcolsep> .
\&  
\&  3. Legacy support is present to use C<$PDL::IO::Misc::colsep> to set the
\&     column separator but C<$PDL::IO::Misc::colsep> is not defined by default.
\&     If you set the variable to a defined value it will get picked up.
\&  
\&  4. LINES => \*(Aq\-1:0:3\*(Aq may not work as you expect, since lines are skipped
\&     when read in, then the whole array reversed.
\&
\&  5. For consistency with wcols and rcols 1D usage, column data is loaded
\&     into the rows of the pdls (i.e., dim(0) is the elements read per column
\&     in the file and dim(1) is the number of columns of data read.
.Ve
.SS "wcols"
.IX Subsection "wcols"
.Vb 1
\&  Write ASCII columns into file from 1D or 2D ndarrays and/or 1D listrefs efficiently.
.Ve
.PP
Can take file name or *HANDLE, and if no file/filehandle is given defaults to \s-1STDOUT.\s0
.PP
.Vb 1
\&  Options (case insensitive):
\&
\&    HEADER \- prints this string before the data. If the string
\&             is not terminated by a newline, one is added. (default B<\*(Aq\*(Aq>).
\&
\&    COLSEP \- prints this string between columns of data. Defaults to
\&             $PDL::IO::Misc::defcolsep.
\&
\&    FORMAT \- A printf\-style format string that is cycled through
\&             column output for user controlled formatting.
.Ve
.PP
.Vb 2
\& Usage: wcols $data1, $data2, $data3,..., *HANDLE|"outfile", [\e%options];  # or
\&        wcols $format_string, $data1, $data2, $data3,..., *HANDLE|"outfile", [\e%options];
\&
\&   where the $dataN args are either 1D ndarrays, 1D perl array refs,
\&   or 2D ndarrays (as might be returned from rcols() with the [] column
\&   syntax and/or using the PERLCOLS option).  dim(0) of all ndarrays
\&   written must be the same size.  The printf\-style $format_string,
\&   if given, overrides any FORMAT key settings in the option hash.
.Ve
.PP
e.g.,
.PP
.Vb 4
\&  $x = random(4); $y = ones(4);
\&  wcols $x, $y+2, \*(Aqfoo.dat\*(Aq;
\&  wcols $x, $y+2, *STDERR;
\&  wcols $x, $y+2, \*(Aq|wc\*(Aq;
\&
\&  $x = sequence(3); $y = zeros(3); $c = random(3);
\&  wcols $x,$y,$c; # Orthogonal version of \*(Aqprint $x,$y,$c\*(Aq :\-)
\&
\&  wcols "%10.3f", $x,$y; # Formatted
\&  wcols "%10.3f %10.5g", $x,$y; # Individual column formatting
\&
\&  $x = sequence(3); $y = zeros(3); $units = [ \*(Aqm/sec\*(Aq, \*(Aqkg\*(Aq, \*(AqMPH\*(Aq ];
\&  wcols $x,$y, { HEADER => "#   x   y" };
\&  wcols $x,$y, { Header => "#   x   y", Colsep => \*(Aq, \*(Aq };  # case insensitive option names!
\&  wcols " %4.1f  %4.1f  %s",$x,$y,$units, { header => "# Day  Time  Units" };
\&
\&  $a52 = sequence(5,2); $y = ones(5); $c = [ 1, 2, 4 ];
\&  wcols $a52;         # now can write out 2D pdls (2 columns data in output)
\&  wcols $y, $a52, $c  # ...and mix and match with 1D listrefs as well
\&
\&  NOTES:
\&
\&  1. Columns are separated by whitespace by default, use
\&     C<$PDL::IO::Misc::defcolsep> to modify the default value or
\&     the COLSEP option
\&
\&  2. Support for the C<$PDL::IO::Misc::colsep> global value
\&     of PDL\-2.4.6 and earlier is maintained but the initial value
\&     of the global is undef until you set it.  The value will be
\&     then be picked up and used as if defcolsep were specified.
\&
\&  3. Dim 0 corresponds to the column data dimension for both
\&     rcols and wcols.  This makes wcols the reverse operation
\&     of rcols.
.Ve
.SS "swcols"
.IX Subsection "swcols"
generate string list from \f(CW\*(C`sprintf\*(C'\fR format specifier and a list of ndarrays
.PP
\&\f(CW\*(C`swcols\*(C'\fR takes an (optional) format specifier of the printf
sort and a list of 1D ndarrays as input. It returns a perl
array (or array reference if called in scalar context)
where each element of the array is the string generated by
printing the corresponding element of the ndarray(s) using
the format specified. If no format is specified it uses the
default print format.
.PP
.Vb 2
\& Usage: @str = swcols format, pdl1,pdl2,pdl3,...;
\&    or  $str = swcols format, pdl1,pdl2,pdl3,...;
.Ve
.SS "rgrep"
.IX Subsection "rgrep"
.Vb 1
\&  Read columns into ndarrays using full regexp pattern matching.
\&  
\&
\&  Options:
\&  
\&  UNDEFINED: This option determines what will be done for undefined 
\&  values. For instance when reading a comma\-separated file of the type 
\&  C<1,2,,4> where the C<,,> indicates a missing value. 
\&  
\&  The default value is to assign C<$PDL::undefval> to undefined values,
\&  but if C<UNDEFINED> is set this is used instead. This would normally 
\&  be set to a number, but if it is set to C<Bad> and PDL is compiled
\&  with Badvalue support (see L<PDL::Bad/>) then undefined values are set to
\&  the appropriate badvalue and the column is marked as bad.
\&  
\&  DEFTYPE: Sets the default type of the columns \- see the documentation for
\&   L</rcols()>
\&  
\&  TYPES:   A reference to a Perl array with types for each column \- see 
\&  the documentation for L</rcols()>
\&  
\&  BUFFERSIZE: The number of lines to extend the ndarray by. It might speed
\&  up the reading a little bit by setting this to the number of lines in the
\&  file, but in general L</rasc()> is a better choice
.Ve
.PP
Usage
.PP
.Vb 1
\& ($x,$y,...) = rgrep(sub, *HANDLE|"filename")
.Ve
.PP
e.g.
.PP
.Vb 1
\& ($x,$y) = rgrep {/Foo (.*) Bar (.*) Mumble/} $file;
.Ve
.PP
i.e. the vectors \f(CW$x\fR and \f(CW$y\fR get the progressive values
of \f(CW$1\fR, \f(CW$2\fR etc.
.SS "isbigendian"
.IX Subsection "isbigendian"
.Vb 1
\&  Determine endianness of machine \- returns 0 or 1 accordingly
.Ve
.SS "rasc"
.IX Subsection "rasc"
.Vb 2
\&  Simple function to slurp in ASCII numbers quite quickly,
\&  although error handling is marginal (to nonexistent).
.Ve
.PP
.Vb 1
\&  $pdl\->rasc("filename"|FILEHANDLE [,$noElements]);
\&
\&      Where:
\&        filename is the name of the ASCII file to read or open file handle
\&        $noElements is the optional number of elements in the file to read.
\&            (If not present, all of the file will be read to fill up $pdl).
\&        $pdl can be of type float or double (for more precision).
.Ve
.PP
.Vb 6
\&  #  (test.num is an ascii file with 20 numbers. One number per line.)
\&  $in = PDL\->null;
\&  $num = 20;
\&  $in\->rasc(\*(Aqtest.num\*(Aq,20);
\&  $imm = zeroes(float,20,2);
\&  $imm\->rasc(\*(Aqtest.num\*(Aq);
.Ve
.SS "rcube"
.IX Subsection "rcube"
.Vb 1
\& Read list of files directly into a large data cube (for efficiency)
.Ve
.PP
.Vb 1
\& $cube = rcube \e&reader_function, @files;
.Ve
.PP
.Vb 1
\& $cube = rcube \e&rfits, glob("*.fits");
.Ve
.PP
This \s-1IO\s0 function allows direct reading of files into a large data cube,
Obviously one could use \fBcat()\fR but this is more memory efficient.
.PP
The reading function (e.g. rfits, readfraw) (passed as a reference)
and files are the arguments.
.PP
The cube is created as the same X,Y dims and datatype as the first
image specified. The Z dim is simply the number of images.
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (C) Karl Glazebrook 1997, Craig DeForest 2001,
2003, and Chris Marshall 2010. All rights reserved. There is
no warranty. You are allowed to redistribute this software
/ documentation under certain conditions. For details, see
the file \s-1COPYING\s0 in the \s-1PDL\s0 distribution. If this file is
separated from the \s-1PDL\s0 distribution, the copyright notice
should be included in the file.