iArray: Associative Array for Javascript

iArray is a JavaScript class to facilitate some basic level of associative arrays.

Associative arrays are data arrays in which the are associated with a key value rather than just a numeric index. Many languages such as PHP already support such data types. In effect it allows you to keep an array of arbitary data objects accessible by a name (the key) rather than having to store (and keep current following deletion or insertion) the index.

Index-Based Array    Associative Array
0 = Hello            first = Hello
1 = There            second = There
2 = World            third = World

In this example we would refer to 'There' in the index array by calling the index(1) and in the associative array with the key value 'second'.

The iArray object allows you to refer to an element by index or key value as shown in the documentation.

iArray is entirely free for use under the GNU General Public Licence version 3 (or later as you wish).

Anything not covered here or problems? Post to the PurplePixie Support Forum (under "Anything Else")

Using iArray

To use iArray simply download the code and include in your project (or hotlink) as described on the Code/Download page (link at the top).

Then just create an iArray object with something like: var myarray = new iArray();

You can then add/fetch/find/delete elements from the array using the provided methods (detailed in full below).

For example: myarray.set('mykey','some value');

Would set an array element with the key 'mykey' to be 'some value' (if that key doesn't already exist then it would be appended to the end of the array otherwise the value would be updated).

A Working Example

You can see the output generated by the below example by clicking here

Code from this example:

<HTML>
<HEAD>
<TITLE>iArray Example</TITLE>
<SCRIPT SRC="iarray.js" TYPE="text/javascript"></SCRIPT>
</HEAD>
<BODY>
<H1>JavaScript iArray Example: <A HREF="http://www.purplepixie.org/iarray/">www.purplepixie.org/iarray</A></H1>

<SCRIPT TYPE="text/javascript">
var myarray = new iArray();

document.write("Setting values for index keys:<BR />");
document.write(" FreeNATS = Free Network Automatic Testing System<BR />");
myarray.set("FreeNATS","Free Network Automatic Testing System"); // creates if not already existant
document.write(" Dave = Idiot<BR />");
myarray.push("Dave","Idiot"); // push appends to the end, only use if CERTAIN key doesn't exist already
document.write(" Fish = Swim in the Sea<BR />");
myarray.set("Fish","Swim in the Sea");
document.write("<BR /><BR />");

document.write("Does the Key Dave Exist? ");
if (myarray.exists("Dave")) document.write("Yes");
else document.write("No");
document.write("<BR />");

document.write("Does the Key Blibble Exist? ");
if (myarray.exists("Blibble")) document.write("Yes");
else document.write("No");
document.write("<BR />");

document.write("<BR />");

document.write("And the value of Dave key element: ");
document.write(myarray.get("Dave"));
document.write("<BR /><BR />");

document.write("Now let's loop through the elements...<BR />");
var l = myarray.length(); // note the brackets this is a METHOD not a property

for (var i=0; i<l; i++)
{
	document.write(" " + myarray.getKeyByIndex(i) + " = " + myarray.getValByIndex(i) + "<BR />");
}

document.write("<BR />");
document.write("How about we delete the Dave key element and try again...<BR />");

myarray.unset("Dave");

var l = myarray.length(); // note the brackets this is a METHOD not a property

for (var i=0; i<l; i++)
{
	document.write(" " + myarray.getKeyByIndex(i) + " = " + myarray.getValByIndex(i) + "<BR />");
}

document.write("<BR />");

document.write("And sometimes fish fly so let's update that key element...<BR />");

myarray.set("Fish","Swim in the Sea and Sometimes Fly");

document.write("... and loop through again ...<BR />");

var l = myarray.length(); // note the brackets this is a METHOD not a property

for (var i=0; i<l; i++)
{
	document.write(" " + myarray.getKeyByIndex(i) + " = " + myarray.getValByIndex(i) + "<BR />");
}

</SCRIPT>

iArray Methods

iArray.set(key, value)
Sets an array element of specified key to value. If element doesn't exist it is created (using iArray.push) otherwise the value is updated.

Unless you are CERTAIN the key doesn't exist then you should use this rather than iArray.push as the overhead is not much and it's duplicate key safe.

iArray.get(key)
Gets the value of the element associated with the key (returns false if not found but of course the value could be false so if not sure check with iArray.exists first).

iArray.unset(key)
Delete (unset) the element associated with key (and the key), returns false if failure (doesn't exist) or true on success.

We use unset rather than delete because delete will break MSIE.

iArray.exists(key)
Check if the key exists and returns true if it does or false if not found.

iArray.push(key, value)
Adds element to the end of the array with key and value specified. See notes in iArray.set as to why you should use iArray.set instead.

iArray.length()
Returns the length of the array (note this is a METHOD and not a property as with standard JS arrays e.g. you need the () after it)

iArray.getIndex(key)
Returns the index of the element associated with the provided key or -1 if the key is not found.

iArray.getKeyByIndex(index)
Get the key for the array element at given index position

iArray.getValByIndex(index)
Get the value for the array element at given index position

Examples

var myarray = new iArray(); // create the iArray object

myarray.set('fish','sea'); // set an element key=fish value=sea
myarray.set('lizard','land'); // set an element key=lizard value=land

myarray.set('fish','Sea'); // update element with key=fish to value=Sea (upper case S)

var fish_live_in_the = '';
if (myarray.exists('fish))
	fish_live_in_the = myarray.get('fish'); // get value for key 'fish' if exists
else
	fish_live_in_the = "no idea"; // otherwise we have no idea

myarray.unset('fish'); // enough of the fish!

To view the Javascript code just click here.

You can copy+paste into a file called iarray.js, save it into your website folder and add the following line into the <HEAD> of your HTML:

<SCRIPT SRC="iarray.js" TYPE="text/javascript"></SCRIPT>

Or you can hot link it (include it directly from PurplePixie) with the following line in your document <HEAD>:

<SCRIPT SRC="http://www.purplepixie.org/iarray/iarray/iarray.js" TYPE="text/javascript"></SCRIPT>

For your convenience the code is also shown in full here:

/* -------------------------------------------------------------
This file is part of iArray

iArray is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

iArray 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.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with iArray.  If not, see www.gnu.org/licenses

For more information see http://www.purplepixie.org/iarray
-------------------------------------------------------------- */

// VERSION: 0.01 2010-01-07 //

/* This is fix to implement Array.indexOf for IE;
   once again damn you Microsoft
*/
if (!Array.prototype.indexOf)
{
	Array.prototype.indexOf = function(val)
	{
		for (var x=0; x<this.length; x++)
		{
			if (this[x] == val) return x; // found it
		}
		return -1; // not found
	}
}

/* Now the actual iArray code...
*/

function iA_set(key, val)
{
	var idx = this.getIndex(key);
	if (idx==-1)
	{
		this.push(key,val);
	}
	else
	{
		this.values[idx]=val;
	}
}

function iA_get(key)
{
	var idx = this.getIndex(key);
	if (idx==-1) return false;
	return this.values[idx];
}

function iA_delete(key)
{
	var idx = this.getIndex(key);
	if (idx==-1) return false;
	
	this.keys.splice(idx,1);
	this.values.splice(idx,1);
	
	return true;
}

function iA_exists(key)
{
	if (this.getIndex(key)==-1) return false;
	return true;
}

function iA_push(key, val)
{
	this.keys.push(key);
	this.values.push(val);
}

function iA_getIndex(key)
{
	return this.keys.indexOf(key);
}

function iA_getKeyByIndex(idx)
{
	return this.keys[idx];
}

function iA_getValByIndex(idx)
{
	return this.values[idx];
}

function iA_length()
{
	return this.keys.length;
}

function iArray()
{
	this.keys = Array();
	this.values = Array();
	
	this.set = iA_set;
	this.get = iA_get;
	this.unset = iA_delete;
	this.exists = iA_exists;
	this.push = iA_push;
	this.length = iA_length;
	this.getIndex = iA_getIndex;
	this.getKeyByIndex = iA_getKeyByIndex;
	this.getValByIndex = iA_getValByIndex;
}