Dict.js Key-Value and more

Usage

Instant start

var d = new Dict(); d.Set('foo',myFooeyThing); d.Get('foo'); d.Set('foo',overwrityThing); // This is OK but 3rd arg will stop d.Set('foo',scribble,true); // scribble. Nothing happens here. d.Get('foo'); // returns overwrityThing. (NOT scribble) d.Delete('foo'); d.Clear(); // clear everything d.data; // inner object

If you want to use it like an array then supply null as the key. You can then iterate over .Keys(), .Sorted() or .ReverseLookup()

Keys

d.Keys() returns complete list of keys

d.ReverseLookup(...) examines the values by ==, RegExp, EQ/IS,GT/LT/IN or a callback function. See reference for details.

You can get Dict to generate a nonce key for you or supply a function to be used when a record is added. For example: myDict.generateKey = function(ObjBeingAdded){return ObjBeingAdded.name;};

In and out

FromJson() and ToJson() do what you'd expect.

FromObject() copies the object's own properties.

These can be used in merge or overwrite modes, and are built-in to the constructor.

A typical use might be in a 'success' method of an AJAX call
.success(function(Data){myDict = new Dict(Data);})

One to many

The .Add(Key,Val) method works as follows

d.Clear(); d.Add('foo','f'); d.Add('foo','o'); // does NOT o/write f d.Add('foo','o'); d.Get('foo'); // gives array ['f','o','o'] d.Add('foo',['bar','buz']); // concatenates arrays d.Get('foo'); // gives array ['f','o','o','bar','buz']

See caution about arrays below

Persistent storage

The constructor can be give a Storage object (localStorage or sessionStorage) and that's it! The dictionary will be loaded automatically and all changes mirrored back to the store.

Dictionaries can also be explicitly loaded or saved using a store/key of your choice.

Sometimes you don't want the overhead of writing everything to the store on each change so set .autoSave false and call .Save() manually.

Server friendlyness

(Or data-driven events.)
Two events are exposed which can be hooked-into for updating a server or other 'data-changed' operations. .onChange fires when a value is changed and provides the 'SET' or 'DEL' action, key and value to a function of your choice. A typical use might be something like this:

d.onChange = function(Action,K,V){ var dataToPost = {"verb":Action,"id":K,"record":V}; DoMyAjaxyUpdate(dataToPost); };

A similar scheme operates when the whole dictionary is to be saved. For example

d.onSave = function(Data){PipelineToSomewhere(Data);};

Array values caution

Dict allows multiple values for a key with the .Add()method. As you might expect it does this with an array. So if you actually want to store an array as a single value then you MUST wrap it in an object.

d.Set('points',['N','E','S','W']); d.Add('points','Mean prizes!'); d.ValueCount('points'); // -> 5 not 2!

d.Set('points',{data:['N','E','S','W']}); d.Add('points','Mean prizes!'); d.ValueCount('points'); // -> 2

Sorting

So you've got a dictionary and you'd like it sorted? OK use d.Sorted() to return a sorted array of keys. (By the way: Numbers are sorted correctly and not as strings.) What more could you want? How about when you've created a dictionary where the keys are nonces and you'd rather sort on the values. Wow! How flexible is that! Provide a function that returns a comparable value from the value and you're away.

d.Set(10,'foo');d.Set(20,'bar');d.Set(30,'cat'); d.Sorted(function(V){return V;}); // returns [20,30,10]

d.Set('Mavis',{age:22,gender:'F'}); d.Set('John',{age:19,gender:'M'}); d.Set('Sally',{age:20,gender:'F'}); d.Sorted(function(V){return V.gender+V.age;}); // returns ['Sally','Mavis','John']