Arrays : Overview

AJAX - Javascript Function Library

AJAX : Overview | Reference | Quick Start | Examples | Download

Arrays : Overview | Reference | Download

The Cyclomedia Array Javascript Library is intended to provide a complete suite of 2d-array manipulation functions for use in client-side scripting. These should be very useful in AJAX scripts that handle and serialise tabular data to/from the server, for example. They should also be useful anywhere you want to present the user with an interactive spreadsheet or datagrid type interface.

In order to keep this library modular and lightweight no new 2d-Array object type is created and the existing Javascript Array object is not extended. Instead they are presented as "C-Style" functions where the first parameter is (usually) the 2d-Array you wish to manipulate.

The 2d-Array object is itself merely an array-of arrays. Where the top-level array is a collection of Rows and each row is a collection of Cells. A cell at row 4, column 6 will be accessed as follows (note the zero-basing, as standard):

	CellContents = My2dArray[3][5];

Versions

1.0.0 : 2007-01-12 - Initial release, only developed and tested on IE6, feedback needed!

There is version info embedded in the library in two variables:

	var array_release_version = "1.0.0";
	var array_release_date    = "2007-01-12";

Usage

Download the script and place it in a suitable location on your web server. You can then include it in any HTML pages that use it in the standard way:

	<script type="text/javascript" src="cyclomedia_2d_arrays.js"></script>

The functions themselves use one or two standard Javascript 1.5 Array prototypes, if you are targetting platforms that don't fully support these, such as IE5 then you should include the array prototype script found at 4umi.com or a similar library. Ideally your script should check support for array.concat and array.copy and degrade gracefully if they are not available.

Namespace

There is a fake namespace in the script whereby every function name begins with "array_", if this is likely to clash with any functions or global variables in your own applications then run a search and replace, changing it to "array2d_" for example, but i'd reccomend keeping the underscore.

Misc Notes

Many functions have subtle overloads, you can pass -1 in for row and col counts in places, for example, this example will resize the array to 8 cols wide but the row count will remain unchanged:

	array_resize( arr , 0 , 0 , -1 , 8 , "" );

Further desirable functions can be made up of compound statements using existing functions. For example, this will copy out the entire second column of the 2d array into a new 1d array:

	var a1d = array_col_shift( array_reg_copy( a2d , 0 , 1 , -1 , 1 ) );

Sub regions of large arrays can be manipulated by calling array_reg_copy, modifying the resulting sub-array and calling array_reg_paste to replace the original region.

One thing notable by it's absence is sorting, this is for one very good reason: everyone has their own favourite sorting routines, however i may be compelled to add sorting at a later date if the demand is there.

Also missing and needed by any sorting routing are simple row and col swapping functions, these are in the current 1.1.0 beta, which is as yet unreleased.