CYCLOMEDIA

array_new

	a2DArray = array_new( iNumRows , iNumCols , sCellContents )
	a2DArray = array_new( aRowCells , iNumCols [, null] )
	a2DArray = array_new( iNumRows , aColCells [, null] )
		

Creates a new 2D array, with three overloads.

The first, default, constructor allows you to state the number of rows and cols (zero or more) that make up the array, sCellContents allows you to set a default value for each cell, the default being an empty string.

The two overloads allow you to pass a 1D array to set the initial contents of the array. Passing aRowCells with a corresponding iNumCols of 1 will create an array with one column containing the contents of the 1D array, iNumCols can also be used to duplicate this and create any number of identical columns.

The final overload works in the same fashion but allows the provision of default column values.

array_copy

	aNew2DArray = array_copy( a2DArray )
		

Returns a duplicate (deep copy) of aArray. However if you are using a 2d array to store references/pointers the objects referred to will not be deep-copied.

array_cols

	iNumCols = array_cols( a2DArray )
		

Returns the column count.

array_rows

	iNumRows = array_rows( a2DArray )
		

Returns the row count.

array_split

	a2DArray = array_split( sDelimitedString , sRowDelimiter , sColDelimiter )
		

Creates and returns a 2d array from the delimited string using the provided seperators.

This function assumes the input string is formatted in cols->rows order and performs no delimiter qualification

array_join

	sDelimitedString = array_join( a2DArray , sRowDelimiter , sColDelimiter )
		

Creates and returns a delimited string from the provided 2D array

Performs no delimiter qualification

array_join_clear

	sDelimitedString = array_join_clear( a2DArray , sRowDelimiter 
		, sColDelimiter )
		

Creates and returns a delimited string from the provided 2D array

Removes any instances of either delimiter in the input array prior to joining.

array_split_csv

	a2DArray = array_split_csv( sDelimitedString )
		

Parses a CSV formatted string, including qualified and escaped chars, and returns a new 2D array.

array_join_csv

	sDelimitedString = array_join_csv( a2DArray )
		

Creates and returns a standard CSV formatted string from the input array including delimiter qualification and escaped quotes.

array_split_params

	a2DArray = array_split_params( sDelimitedString , sRowDelimiter 
		, sColDelimiter , sQualifierChar , sEscapeChar )
		

Creates and returns a new 2D array from the given input string. The Row and Col delimiters can be escaped from an entry by enclosing the entry in a pair of sQualifierChar, and instances of that within a string are escaped with the sEscapeChar, which is self escaping by being doubled.

For CSV data therefore the function could be called thus:

	array_split_params( [string] , '\n' , ',' , '"' , '"' )
		

Note that in CSV the qualifier and escape chars are both the double quote. In some instances you may want to use different chars, for example a forward slash as the escape char to follow C encoding conventions.

array_join_params

	sDelimitedString = array_join_params( a2DArray , sRowDelimiter 
		, sColDelimiter , sQualifierChar , sEscapeChar )
		

Creates and returns a string containing the contents of the input array serialised using the delimiter and escape chars provided.

array_pad

	iNumCols = array_pad( a2DArray , sCellContents )
		

This will pad a jagged 2D array into a rectangular 2D array by filling out missing cells with the provided string.

Returns col count

array_resize

	array_resize( a2DArray , iRowOfs , iColOfs , iRowCount , iColCount 
		, sCellContents )
		

Grows or shrinks the array to the new bounds, existing data is preserved, new cells are filled with sCellContents.

The offsets are where the top-left of the array is to move to, so passing a value of -1 into iColOfs will add a column to the left of the array.

The Row and Col count can be overridden by passing -1, in which case the Row or Col count, respectively, will be left unchanged.

array_concat

	array_concat( a2DArray , aArrayToConcat )
		

This will append the rows from aArrayToConcat to the bottom of a2DArray.

This is an atomic operation and does not check if the resulting array is rectangular, it is up to the user if they wish to assert this by calling a function such as array_pad.

array_cojoin

	array_cojoin( a2DArray , aArrayToCojoin )
		

This will append the columns from aArrayToCojoin to the right of a2DArray.

This is an atomic operation, the user should if neccesary assert that each input array is rectangular before calling this function and may wish to do so for the resulting array by calling array_pad. Joining a jagged 2D array to another will yield mismatched column values.

array_flip

	array_flip( a2DArray )
		

Exchanges the rows and cols of the array, so a cell on the top right will swap with the bottom left, but the top left and bottom right cells will remain unchanged.

	a,b,c     a,d,g
	d,e,f  >  b,e,h
	g,h,i     c,f,i
		

array_trans_horiz

	array_trans_horiz( a2DArray )
		

Horizontally flips the array, reversing the column order

	a,b,c     c,b,a
	d,e,f  >  f,e,d
	g,h,i     i,h,g
		

array_trans_vert

	array_trans_vert( a2DArray )
		

Vertically flips the array, reversing the row order

	a,b,c     g,h,i
	d,e,f  >  d,e,f
	g,h,i     a,b,c
		

array_trans_left

	array_trans_left( a2DArray )
		

Rotates the cell contents 90 degrees counter-clockwise. A cell on the top left will move to the bottom left, which will in turn move to the bottom right and so on.

	a,b,c     c,f,i
	d,e,f  >  b,e,h
	g,h,i     a,d,g
		

array_trans_right

	array_trans_right( a2DArray )
		

Rotates the cell contents 90 degrees clockwise.

	a,b,c     g,d,a
	d,e,f  >  h,e,b
	g,h,i     i,f,c
		

array_trans_180

	array_trans_180( a2DArray )
		

Rotates the cell contents 180 degrees, the top left cell swaps with the bottom right and the top right swaps with the bottom left

	a,b,c     i,h,g
	d,e,f  >  f,e,d
	g,h,i     c,b,a
		

array_reg_copy

	aNew2DArray = array_reg_copy( a2DArray , iStartRow , iStartCol 
		, iNumRows , iNumCols , bForceBounds , sCellContents )
		

Copy a sub-array out of a larger array

Set bForceBounds to true if you need the returned array to be the specified number of rows and cols in size, even if the num of rows and cols in the original array arent available, in which case the additional new cells will be populated with sCellContents.

Setting bForceBounds to false will clip the returned array to the bounds of the original array.

iStartRow and iStartCol can be negative. This combined with the bounds switch actually allow you to copy a sub array out that is larger than the original array!

array_reg_paste

	array_reg_paste( a2DArray , a2DSubArray , iStartRow , iStartCol
		, iNumRows , iNumCols , bFillBounds , bExtendArray , sCellContents )
		

Paste a sub array into a region of another array.

bFillBounds - if the sub array is smaller than the defined region then sCellContents will be inserted into the remaining cells of the region, otherwise paste only the available data

bExtendArray - if the defined region falls outside of the bounds of the original array then extend the original array to accomodate (filling remaining new cells with sCellContents), otherwise clip the region.

if iNumRows and/or iNumCols are passed as -1 then the region will automatically be sized to the Row and/or Col count of the sub-array.

array_reg_clear

	array_reg_clear( a2DArray , iStartRow , iStartCol 
		, iNumRows , iNumCols , sCellContents )
		

Pastes sCellContents into every cell in the defined region within the array.

If the defined region is greater than the bounds of the original array then the array will be grown to accomodate.

array_col_ins

	iColCount = array_col_ins( a2DArray , a1DArray , iColIndex )
	iColCount = array_col_ins( a2DArray , sCellContents , iColIndex )
		

Insert the 1D array of cells as a column into the 2D array at the given index. If the 1D array is shorter than the column then null will be inserted into any remaining cells, if the 1D array is longer then it will be clipped.

The column at iColIndex will be displaced to the right, passing an iColIndex of -1 will append the column to the right of the 2D array. The left col index is always 0, so passing zero will prepend the 1D array to the left of the 2D array.

The overloaded function allows a col with every cell containing sCellContents to be inserted

array_col_del

	a1DArray = array_col_del( a2DArray , iColIndex )
		

Removes and returns a 1D array of the column at the given index from the array. Passing an iColIndex of -1 will remove and return the right hand column of the array.

array_col_unshift

	iColCount = array_col_unshift( a2DArray , a1DArray )
		

Provided for completeness, wraps array_col_ins, prepending the col to the left of the 2D array

array_col_shift

	a1DArray = array_col_shift( a2DArray )
		

Provided for completeness, wraps array_col_del, removing and returning the left col of the 2D array

array_col_push

	iColCount = array_col_push( a2DArray , a1DArray )
		

Provided for completeness, wraps array_col_ins, appending the col to the right of the 2D array

array_col_pop

	a1DArray = array_col_pop( a2DArray )
		

Provided for completeness, wraps array_col_del, removing and returning the right col of the 2D array

array_row_ins

	iRowCount = array_row_ins( a2DArray , a1DArray , iRowIndex )
	iRowCount = array_row_ins( a2DArray , sCellContents , iRowIndex )
		

Insert the 1D array of cells as a row into the 2D array at the given index. If the 1D array is shorter than the row then null will be inserted into any remaining cells, if the 1D array is longer then it will be clipped.

The row at iRowIndex will be displaced to the bottom, passing an iRowIndex of -1 will append the row to the bottom of the 2D array. The top row index is always 0, so passing zero will prepend the 1D array to the top of the 2D array.

The overloaded function allows a row with every cell containing sCellContents to be inserted

array_row_del

	a1DArray = array_row_del( a2DArray , iRowIndex )
		

Removes and returns a 1D array of the row at the given index from the array. Passing an iRowIndex of -1 will remove and return the bottom row of the array.

array_row_unshift

	iRowCount = array_row_unshift( a2DArray , a1DArray )
		

Provided for completeness, wraps array_row_ins, prepending the row to the top of the 2D array

array_row_shift

	a1DArray = array_row_shift( a2DArray )
		

Provided for completeness, wraps array_row_del, removing and returning the top row of the 2D array

array_row_push

	iRowCount = array_row_push( a2DArray , a1DArray )
		

Provided for completeness, wraps array_row_ins, appending the row to the bottom of the 2D array

array_row_pop

	a1DArray = array_row_pop( a2DArray )
		

Provided for completeness, wraps array_row_del, removing and returning the bottom row of the 2D array

array_is2dArray

	bIs2DArray = array_is2dArray( hAnyObject )
		

Analyses the object and returns true if it is found to be a 2D array

BUG: will return false for a 2D Array with a row/col count of zero.

array_isArray

	bIsArray = array_isArray( hAnyObject )
		

Analyses the object and returns true if it is found to be a standard 1D array

BUG: will return true for a 2D Array. Suggest conducting an array_is2dArray test first.

array_isString

	bIsString = array_isString( hAnyObject )
		

Analyses the object and returns true if it is found to be a standard javascript string

array_escapeRE

	sEscapedString = array_escapeRE( sInputString )
		

Escapes any special RegExp characters found in sInputString so that it can be used in a regular expression itself.