dictionaryjs

A simple dictionary wrapper for JavaScript objects providing associative array functionality and helpful methods. Methods include: get, set, getDefault, remove, has, size, empty, asyncEmpty, forEach, and asyncForEach.

dictionaryjs

  • Get and Set entries as key/value pairs
  • GetDefault method with default value if value is not found
  • Remove key from dictionary
  • Get length of dictionary
  • Built-in forEach and asyncForEach loops
  • Ability to break forEach and asyncForEach loops
  • asyncForEach now has a end callback which will be called once the loop is complete
  • Empty and asyncEmpty to clear all entries from dictionary

0.0.8

  • Improved the forEach loop to not use a seperate array for keys.
  • Added Empty and asyncEmpty to quickly remove all entries from the dictionary.

API

To use simply include at the top of your script:

var Dictionary = require('dictionaryjs');

var dict = new Dictionary();

To store a key provide the key as a string and the value can be any data type.

dict.set("key",value);

Get the value of a key.

dict.get("key");

Get the value of a key or return the default value.

dict.getDefault("key",default);
If key is not contained within dictionary then the default value will be returned.

Remove a key.

dict.remove("key");

Determine how many keys are in the dictionary, returns an integer.

dict.size();

Check if key is in the dictionary, returns boolean.

dict.has("key");

Removes all dictionary entries. This method is blocking.

dict.empty();

Removes all dictionary entries. This method is non-blocking.

dict.asyncEmpty(function() {
  //called after dictionary has been emptied
});

To loop over each entry in the dictionary use:

dict.forEach(function(key,value) {
  //returns key and value of each
});

To break and end looping:

dict.forEach(function(key,value) {
  if (..logic..) return false;
});

To loop over each entry in a non-blocking manner:

dict.asyncForEach(function(key,value,next) {
  //returns key and value of each
  next();
});

To break and end looping:

dict.asyncForEach(function(key,value,next) {
  if (..logic..) return false;
  next();
});

(Optional) You may also call a function once the asyncForEach loop is complete:

dict.asyncForEach(function(key,value,next) {
  next();
}, function() {
  //called once loop is complete
});

Returns an array of keys:

dict.getKeys();

Full Example

var Dictionary = require('dictionaryjs');

var dict = new Dictionary();

//Setting keys examples dict.set("key1","value1"); dict.set("key2","value2"); dict.set("1","num1"); dict.set("2","num2"); dict.set("3","num3"); dict.set("4","num4"); dict.set("obj",{test:"object"}); dict.set("arr",[0,1,2,3]);

//Delete key example dict.remove("2"); dict.remove("key2");

//Return length of dictionary console.log("Dictionary size="+dict.size());

//Has key console.log("Dictionary contains key 5? "+dict.has(5));

//Get key examples console.log("Get key1="+dict.get("key1"));

//GetDefault example console.log(dict.getDefault("key3","default value, not found"));

//For each looping example dict.forEach(function(key,value) { console.log(key+"="+value); });

//To break within the loops dict.forEach(function(key,value) { if (key==3) return false; //breaks if key is 3 console.log(key+"="+value); });

//Async for each looping example dict.asyncForEach(function(key,value,next) { console.log(key+"="+value); next(); },function() { console.log("Async loop is complete!"); });

//Async Empty dict.asyncEmpty(function() { //dictionary should be empty console.log("emptied, size:" + dict.size()); });

To Do

  • Use some kind of hashing function to store keys so non-strings may be supported.