Struct Class

The Struct class is designed to be an alternative way to store data in javascript rather than the traditional object. This stemmed from the use of Adobe/Macromedia's Coldfusion and the Structure data type that was provided (basically a javascript object). The Coldfusion Structure featured the ability to search recursively for keys/values, clear, delete items, insert, update etc, feature which are not natively available to Javascript's Object class as simple methods.

The Struct class provides all these features and more, including the useful ability to search for values, however the Struct's method to do this also allows for a regular expression to be provided to search with in addition to a normal string for powerfully dynamic searching. The ability to chain methods ie: var myStruct = new Struct().insert('Some key', 'Some Value').update('Some key', 'New Value').dump(); data dumping and Error catching.

One of the incredibly handy tags available in Coldfusion is the <cfdump> tag providing the ability to display simple and complex variables in a user friendly way that is perfect for debugging/inspecting data. There is no way to do this with javascript and many times I had wished for this functionality. The Struct class provides a method to do just that allowing for an infinite amount of data nesting complete with color coding for different data types, the ability to show/hide the data's type (String/Number/Boolean/Object/Array/Function), expandable and collapsible tables/keys and cross browser support.

Click on the buttons bellow to see some examples in action, toggle the Show Data Types box to see javascript data typing in action (not possible in Coldfusion).

Browser Support

Internet Explorer 6, Internet Explorer 7, Firefox 1.5, Opera 8, Safari 1.2 (Mac), Firefox 1.5 (Mac) - all tested, should also work in most other browsers.

Download

Click here to download the latest version (1.06)

Dump Examples

Example dump screenshot below.

Click to see dump examples (Click on headings/keys to expand and collapse tables/values)

Show Data Types

Comments

Any feedback? Click here to comment!

Initialization

Struct([object])
@ param [object] (Object) optional object to insert on creation
@ return (Object) returns a reference to the current instance

Examples

var myStruct = new Struct(object);
var myOtherStruct = new Struct({'key':'value','number:123,'array':[]});
var myEmptyStruct = new Struct();

Methods

errorHandling(boolean [, function])
@ param boolean (Boolean) enable error handling output
@ param [function] (Callback Function) optional function pointer to accept error object when error is thrown
@ return (Object) returns a reference to the current instance

Examples

myEmptyStruct.errorHandling(false); // turns of error catching
myStruct.errorHandling(true, function(e) {alert(e);}); // turns on error catching and provides a custom function to deal with errors

wordReserved(string)
@ param string (String) word to check if reserved
@ return (Boolean) returns if the word is reserved or not

Examples

myStruct.wordReserved('insert'); // returns true
myStruct.wordReserved('name'); // returns false

dump([showTypes, object])
@ param [showTypes] (Boolean) optional to display each key/value's type
@ param [object] (Callback Function) optional object to dump instead of default
@ return (Void) returns nothing

Examples

myStruct.dump(true); // opens a dump window displaying key/value types of the current instance
myStruct.dump(false, [123,456,789]); // opens a dump window not displaying key/value types of the array passed

getFunctions([position])
@ param [position] (Number) optional function to pull
@ return (Array) returns an array of all functions in the Struct can return a specific function if pos is supplied

Examples

myStruct.getFunctions(); // returns an array containing all functions stored ie: function num(x) {return x+1;},function str(x) {return str;}
myStruct.getFunctions(0); // returns the function at the position passed if valid ie: function num(x) {return x+1;}

isEmpty()
@ return (Boolean) returns true or false if the current instance is empty or not

Examples

myEmptyStruct.isEmpty(); // returns true
myOtherStruct.isEmpty(); // returns false

count()
@ return (Number) returns the total count of keys in the Struct

Examples

myEmptyStruct.count(); // returns 0
myOtherStruct.count(); // returns n ie 5

deleteItem(key)
@ param key (String) takes a valid variable path as a string expression to parse ie 'obect.key["key"][0]' and deletes the key found at this position if found
@ return (Object) returns a reference to the current instance

Examples

myEmptyStruct.deleteItem('word'); // returns this (deletes 'word' if found)
myOtherStruct.deleteItem('array.key["object"]["value"]); // returns this (deletes 'value' if found)
myStruct.deleteItem('key').deleteItem('other key'); // returns this (deletes either key if found)

clear()
@ return (Object) returns a reference to the current instance

Examples

myStruct.clear(); // returns this with all keys removed

append(struct [, overWrite])
@ param struct (Object) takes another struct/object and adds its values to the current instance
@ param [overWrite] (Boolean) overwrite existing values with new ones
@ return (Object) returns a reference to the current instance

Examples

myEmptyStruct.append(myOtherStruct); // returns this (myEmptyStruct) with myOtherStruct's values added to it
myOtherStruct.append({'key':'value'}, true); // returns this with 'key/value' added overwrites any existing keys that match 'key'

insert(key, value [, overWrite])
@ param key (String) takes a valid variable path as a string expression to parse ie 'obect.key["key"][0]' and inserts the key/value at this position if it doesn't already exist. If it exists and the overwrite flag is true then the current value is overwritten.
@ param value (String) the value you want to store
@ param [overWrite] (Boolean) indicates if you want to overwrite existing values found
@ return (Object) returns a reference to the current instance

Examples

myEmptyStruct.insert('Some key','some value'); // returns this
myOtherStruct.insert('object', {'key':'value'}, true); // returns this overwrites any existing keys that match 'object'
myStruct.insert('name', 'shuns').insert('age', 18); // returns this with two new key/value pairs added: 'name' and 'age'

insertObject(object [, overWrite, path])
@ param object (Object) takes an object/array and adds each item in it as a key/value pair
@ param [overWrite] (Boolean) indicates if you want to overwrite existing values found
@ param [path] (String) optional string path pointing to a key in the current instance to insert each of the values into
@ return (Object) returns a reference to the current instance

Examples

myOtherStruct.insertObject({'key':'value'}, true); // returns this overwrites any existing keys that match 'key'
myStruct.insertObject(object, false, 'data'); // returns this attempts to insert the object variable into a variable called data won't overwrite existing values

update(key, newValue)
@ param key (String) takes a valid variable path as a string expression to parse ie 'obect.key["key"][0]' and updates the value at this position if it exists
@ param newValue (String) the new value you want the key to be
@ return (Object) returns a reference to the current instance

Examples

myEmptyStruct.update('Some key','some new value'); // returns this
myOtherStruct.update('object.someKey["key"]', {'key':'value'}, true); // returns this tries to update a variable object.someKey.key with the new value
myStruct.update('name', 'shuns.').update('age', 18.2); // returns this with two updated key/value pairs added: 'name' and 'age'

renameKey(key, newName)
@ param key (String) takes a valid variable path as a string expression to parse ie 'obect.key["key"][0]' to search for
@ param newName (String) if the key is found it is renamed to this value
@ return (Object) returns a reference to the current instance

Examples

myEmptyStruct.renameKey('Some key','New Name'); // returns this
myOtherStruct.renameKey('object.someKey', 'SOME KEY'); // returns this tries to rename a key object.someKey with a new name
myStruct.renameKey('name', 'Name').renameKey('age', 'Age'); // returns this with two renamed keys 'Name' and 'Age'

searchPath(object, count, function, path)
@ param object (Object) takes a Struct instance to search
@ param count (Number) should be 0
@ param function (Callback Function) takes a function pointer which is passed the value of the key found from the path provided if a value is found
@ param path (String) takes a valid variable path as a string expression to parse ie 'obect.key["key"][0]'
@ return (Void)

Examples

myStruct.searchPath(myStruct, 0, function(v) {alert(v);}, 'array[2].key'); // passes a value to the callback function if found

getFromPath(path)
@ param path (String) takes a valid variable path as a string expression to search the instance for ie 'obect.key
@ return (Any) returns the value of the variable if found otherwise null

Examples

myStruct.getFromPath('array[2].key'); // returns a value if the path can be followed

findKeys(key)
@ param key (String) takes a key name to search the Struct instance recursively for
@ return (Array) an array of values that had matching keys

Examples

myStruct.findKeys('name'); // returns an array of all keys found that matched the string 'name'

findValue(value [, useRegularExpression, getFunctions])
@ param value (String) takes a value to search recursively for
@ param [useRegularExression] (Boolean) optional flag if the search string should be interpreted as a regular expression
@ param [getFunctions] (Boolean) optional flag if functions in the Struct instance should be compared
@ return (Array) an array of objects which contain the match's key, value, type and the value searched for (regExp search only)

Examples

myStruct.findValue('shuns'); // returns an array of all values found that matched the string 'shuns' each index contains the key, value and type of the value matched
myStruct.findValue('^[sS\$]h.*ns$', true, false); // returns an array of all values found that matched the regular expression each index contains the key, value, type and regExp used of the value matched

keyExists(key)
@ param key (String) takes a key name to search the Struct instance recursively for existence
@ return (Boolean) true of false if a key with the provided name exists in the instance

Examples

myStruct.keyExists('name'); // returns true or false if the key can be found

keyList([delimiter])
@ param [delimiter] (String) optional delimiter for the list returned comma is the default
@ return (String) a list of all keys in the instance

Examples

myStruct.keyList('\n'); // returns a list of keys in the instance delimited by a newline character

keyArray()
@ return (Array) an array of all keys in the instance

Examples

myStruct.keyArray(); // returns an array of all keys in the instance

Back to Website Files

Click here

Comments

Feel free to comment below.

Submit Comments

Name:

Email:

Comment:

All Comments