.\" -*- 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 "Char 3pm"
.TH Char 3pm 2024-04-25 "perl v5.38.2" "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::Char \-\- PDL subclass which allows reading and writing of fixed\-length character strings as byte PDLs
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& use PDL;
\& use PDL::Char;
\&
\& my $pchar = PDL::Char\->new( [[\*(Aqabc\*(Aq, \*(Aqdef\*(Aq, \*(Aqghi\*(Aq],[\*(Aqjkl\*(Aq, \*(Aqmno\*(Aq, \*(Aqpqr\*(Aq]] );
\& 
\& $pchar\->setstr(1,0,\*(Aqfoo\*(Aq);
\& 
\& print $pchar; # \*(Aqstring\*(Aq bound to "", perl stringify function
\& # Prints:
\& # [
\& #  [\*(Aqabc\*(Aq \*(Aqfoo\*(Aq \*(Aqghi\*(Aq]
\& #  [\*(Aqjkl\*(Aq \*(Aqmno\*(Aq \*(Aqpqr\*(Aq]
\& # ]
\&
\& print $pchar\->atstr(2,0);
\& # Prints:
\& # ghi
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This subclass of PDL allows one to manipulate PDLs of 'byte' type as if they were made of fixed
length strings, not just numbers.
.PP
This type of behavior is useful when you want to work with character grids.  The indexing is done
on a string level and not a character level for the 'setstr' and 'atstr' commands.
.PP
This module is in particular useful for writing NetCDF files that include character data using the
PDL::NetCDF module.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS new
.IX Subsection "new"
Function to create a byte PDL from a string, list of strings, list of list of strings, etc.
.PP
.Vb 2
\& # create a new PDL::Char from a perl array of strings
\& $strpdl = PDL::Char\->new( [\*(Aqabc\*(Aq, \*(Aqdef\*(Aq, \*(Aqghij\*(Aq] );  
\&
\& # Convert a PDL of type \*(Aqbyte\*(Aq to a PDL::Char
\& $strpdl1 = PDL::Char\->new (sequence (byte, 4, 5)+99);
.Ve
.PP
.Vb 1
\& $pdlchar3d = PDL::Char\->new([[\*(Aqabc\*(Aq,\*(Aqdef\*(Aq,\*(Aqghi\*(Aq],[\*(Aqjkl\*(Aq, \*(Aqmno\*(Aq, \*(Aqpqr\*(Aq]]);
.Ve
.SS string
.IX Subsection "string"
Function to print a character PDL (created by 'char') in a pretty format.
.PP
.Vb 7
\& $char = PDL::Char\->new( [[\*(Aqabc\*(Aq, \*(Aqdef\*(Aq, \*(Aqghi\*(Aq], [\*(Aqjkl\*(Aq, \*(Aqmno\*(Aq, \*(Aqpqr\*(Aq]] );
\& print $char; # \*(Aqstring\*(Aq bound to "", perl stringify function
\& # Prints:
\& # [
\& #  [\*(Aqabc\*(Aq \*(Aqdef\*(Aq \*(Aqghi\*(Aq]
\& #  [\*(Aqjkl\*(Aq \*(Aqmno\*(Aq \*(Aqpqr\*(Aq]
\& # ]
\&
\& # \*(Aqstring\*(Aq is overloaded to the "" operator, so:
\& # print $char;
\& # should have the same effect.
.Ve
.SS setstr
.IX Subsection "setstr"
Function to set one string value in a character PDL.  The input position is 
the position of the string, not a character in the string.  The first dimension
is assumed to be the length of the string.
.PP
The input string will be null-padded if the string is shorter than the first
dimension of the PDL.  It will be truncated if it is longer.
.PP
.Vb 10
\& $char = PDL::Char\->new( [[\*(Aqabc\*(Aq, \*(Aqdef\*(Aq, \*(Aqghi\*(Aq], [\*(Aqjkl\*(Aq, \*(Aqmno\*(Aq, \*(Aqpqr\*(Aq]] );
\& $char\->setstr(0,1, \*(Aqfoobar\*(Aq);
\& print $char; # \*(Aqstring\*(Aq bound to "", perl stringify function
\& # Prints:
\& # [
\& #  [\*(Aqabc\*(Aq \*(Aqdef\*(Aq \*(Aqghi\*(Aq]
\& #  [\*(Aqfoo\*(Aq \*(Aqmno\*(Aq \*(Aqpqr\*(Aq]
\& # ]
\& $char\->setstr(2,1, \*(Aqf\*(Aq);
\& print $char; # \*(Aqstring\*(Aq bound to "", perl stringify function
\& # Prints:
\& # [
\& #  [\*(Aqabc\*(Aq \*(Aqdef\*(Aq \*(Aqghi\*(Aq]
\& #  [\*(Aqfoo\*(Aq \*(Aqmno\*(Aq \*(Aqf\*(Aq]      \-> note that this \*(Aqf\*(Aq is stored "f\e0\e0"
\& # ]
.Ve
.SS atstr
.IX Subsection "atstr"
Function to fetch one string value from a PDL::Char type PDL, given a position within the PDL.
The input position of the string, not a character in the string.  The length of the input
string is the implied first dimension.
.PP
.Vb 4
\& $char = PDL::Char\->new( [[\*(Aqabc\*(Aq, \*(Aqdef\*(Aq, \*(Aqghi\*(Aq], [\*(Aqjkl\*(Aq, \*(Aqmno\*(Aq, \*(Aqpqr\*(Aq]] );
\& print $char\->atstr(0,1);
\& # Prints:
\& # jkl
.Ve