NAME

       PDL::Char -- PDL subclass which allows reading and writing of fixed-length character
       strings as byte PDLs

SYNOPSIS

        use PDL;
        use PDL::Char;

        my $pchar = PDL::Char->new( [['abc', 'def', 'ghi'],['jkl', 'mno', 'pqr']] );

        $pchar->setstr(1,0,'foo');

        print $pchar; # 'string' bound to "", perl stringify function
        # Prints:
        # [
        #  ['abc' 'foo' 'ghi']
        #  ['jkl' 'mno' 'pqr']
        # ]

        print $pchar->atstr(2,0);
        # Prints:
        # ghi

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.

       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.

       This module is in particular useful for writing NetCDF files that include character data
       using the PDL::NetCDF module.

FUNCTIONS

   new
       Function to create a byte PDL from a string, list of strings, list of list of strings,
       etc.

        # create a new PDL::Char from a perl array of strings
        $strpdl = PDL::Char->new( ['abc', 'def', 'ghij'] );

        # Convert a PDL of type 'byte' to a PDL::Char
        $strpdl1 = PDL::Char->new (sequence (byte, 4, 5)+99);

        $pdlchar3d = PDL::Char->new([['abc','def','ghi'],['jkl', 'mno', 'pqr']]);

   string
       Function to print a character PDL (created by 'char') in a pretty format.

        $char = PDL::Char->new( [['abc', 'def', 'ghi'], ['jkl', 'mno', 'pqr']] );
        print $char; # 'string' bound to "", perl stringify function
        # Prints:
        # [
        #  ['abc' 'def' 'ghi']
        #  ['jkl' 'mno' 'pqr']
        # ]

        # 'string' is overloaded to the "" operator, so:
        # print $char;
        # should have the same effect.

   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.

       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.

        $char = PDL::Char->new( [['abc', 'def', 'ghi'], ['jkl', 'mno', 'pqr']] );
        $char->setstr(0,1, 'foobar');
        print $char; # 'string' bound to "", perl stringify function
        # Prints:
        # [
        #  ['abc' 'def' 'ghi']
        #  ['foo' 'mno' 'pqr']
        # ]
        $char->setstr(2,1, 'f');
        print $char; # 'string' bound to "", perl stringify function
        # Prints:
        # [
        #  ['abc' 'def' 'ghi']
        #  ['foo' 'mno' 'f']      -> note that this 'f' is stored "f\0\0"
        # ]

   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.

        $char = PDL::Char->new( [['abc', 'def', 'ghi'], ['jkl', 'mno', 'pqr']] );
        print $char->atstr(0,1);
        # Prints:
        # jkl