NAME

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

SYNOPSIS

 use PDLA;
 use PDLA::Char;

 my $pchar = PDLA::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 PDLA allows one to manipulate PDLAs 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 charactar 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 PDLA::NetCDF module.

FUNCTIONS

new

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

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

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

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

string

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

 $char = PDLA::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 PDLA. 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 PDLA. It will be truncated if it is longer.

 $char = PDLA::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 PDLA::Char type PDLA, given a position within the PDLA. The input position of the string, not a character in the string. The length of the input string is the implied first dimension.

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