/ 
Array-2D-0.001_001
River stage zero No dependents
/ README.md

NAME

Array:2D - Methods for simple array-of-arrays data structures

VERSION

This documentation refers to version 0.001_001

NOTICE

This is alpha software. Method names and behaviors are subject to change. The test suite has significant omissions.

SYNOPSIS

use Array::2D;
my $array2d = Array::2D->new( [ qw/a b c/ ] , [ qw/w x y/ ] );

# $array2d contains

#     a  b  c
#     w  x  y

$array2d->push_col (qw/d z/);

#     a  b  c  d
#     w  x  y  z

say $array2d->[0][1];
# prints "b"

DESCRIPTION

Array::2D is a module that adds useful methods to Perl's standard array of arrays ("AoA") data structure, as described in Perl's perldsc documentation and Perl's perllol documentation. That is, an array that contains other arrays:

[ 
  [ 1, 2, 3 ] , 
  [ 4, 5, 6 ] ,
]

Most of the time, it's good practice to avoid having programs that use a module know about the internal construction of an object. However, this module is not like that. It exists purely to give methods to a standard construction in Perl, and will never change the data structure to include anything else. Therefore, it is perfectly reasonable to use the normal reference syntax to access items inside the array. A construction like $array2d->[0][1] for accessing a single element, or @{$array2d} to get the list of rows, is perfectly acceptable. This module exists because the reference-based implementation of multidimensional arrays in Perl makes it difficult to access, for example, a single column, or a two-dimensional slice, without writing lots of extra code.

Array::2D uses "row" for the first dimension, and "column" or "col" for the second dimension. This does mean that the order of (row, column) is the opposite of the usual (x,y) algebraic order.

Because this object is just an array of arrays, most of the methods referring to rows are here mainly for completeness, and aren't much more useful than the native Perl construction (e.g., $array2d->last_row() is just a slower way of doing $#{$array2d}.) They will also typically be much slower.

On the other hand, most of the methods referring to columns are useful, since there's no simple way of fetching a column or columns in Perl.

PADDING

Because it is intended that the structure can be altered by standard Perl constructions, there is no guarantee that the object is either completely padded out so that every value within the structure's height and width has a value (undefined or not), alternatively completely pruned so that there are as few undefined values as possible. The only padding that must exist is padding to ensure that the row and column indexes are correct for all defined values.

Other Perl code could change the padding state at any time, or leave it in an intermediate state (where some padding exists, but the padding is not complete).

For example, the following would be valid:

$array2d = [
 [ undef, 1, 2 ],
      3  ],
 [    4,  6, ],
];

The columns would be returned as (undef, 3, 4), (1, undef, 6), and (2).

There are methods to set padding -- the prune() method will eliminate padding, and the pad method will pad out the array to the highest row and column with a defined value.

Methods that retrieve data will prune the data before returning it.

Methods that delete rows or columns (del_*, shift_*, pop_*, and in void context, slice) will prune not only the returned data but also the array itself.

METHODS

Some general notes:

BASIC CONSTRUCTOR METHODS

CONSTRUCTOR METHODS THAT READ FILES

COPYING AND REARRANGING ARRAYS

DIMENSIONS OF THE ARRAY

READING ELEMENTS, ROWS, COLUMNS, SLICES

SETTING ELEMENTS, ROWS, COLUMNS, SLICES

None of these methods return anything. At some point it might be worthwhile to have them return the old values of whatever they changed (when not called in void context), but they don't do that yet.

INSERTING ROWS AND COLUMNS

All these methods return the new number of either rows or columns.

RETRIEVING AND DELETING ROWS AND COLUMNS

ADDING OR REMOVING PADDING

Padding, here, means empty values beyond the last defined value of each column or row. What counts as "empty" depends on the method being used.

MODIFYING EACH ELEMENT

Each of these methods alters the original array in void context. If not in void context, creates a new Array::2D object and returns the object.

TRANSFORMING ARRAYS INTO OTHER STRUCTURES

TABULATING INTO COLUMNAR OUTPUT

If the Unicode::GCString|Unicode::GCString module can be loaded, its columns method will be used to determine the width of each character. This will treat composed accented characters and double-width Asian characters correctly.

Otherwise, Array::2D will use Perl's length function.

SERIALIZING AND OUTPUT TO FILES

DIAGNOSTICS

ERRORS

WARNINGS

TO DO

This is just a list of things that would be nice -- there's no current plan to implement these.

SEE ALSO

The Data::Table module on CPAN provides a more conventionally opaque object that does many of the same things as this module, and also a lot more.

DEPENDENCIES

AUTHOR

Aaron Priven apriven@actransit.org

COPYRIGHT & LICENSE

Copyright 2015, 2017

This program is free software; you can redistribute it and/or modify it under the terms of either:

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.