Go to dict home page Methods are initially capitalised. Properties are initially lower case. 'private' items are initially underscored.


Simple dictionary/associative array
06 Aug 2015 Sorted() bug fixed
13 April 2015 1st finished
28 April 2015 2nd release event hooks added
30 April 2015 3rd release .Sorted .FromArray . AsKeysValues .AsValues added
25 May 2015 4th release Some stray globals removed
22 June 2015 Added DoesKeyExist()
Peter Fox vulpeculox.net
NOTE: Properties (including those that are user-defined functions) start with lower-case
Methods start with upper-case.
Private methods start with an underscore


This can take many permutations of arguments
* None ..... An empty Dict object
* String ... Json to feed to FromJson
* Array [,function]
Values which will be given nonce or generated keys (see .generateKey)
* Dict ..... Only .data is copied into new Dict.
* Storage, StoreKey [,Autosave] .. Dict will mirror local or session store
Autosave default is on.
* Object ... T to feed to FromObject
29_version"22 June 15 12:53" datestamp
30_storenull private localStorage or sessionStorage object if applicable
31_storeKey'' private Key used with ._store
32_changedfalse private Has any data changed? Reset after save.
33_AutoKeyMin0 private Supply for keys when null given. Counts-backwards.
35data{} The Key-Value data. This is an ordinary object with nothing except
property-names and property-values.
38autoSavefalse Boolean switch for should a store be automatically updated at every change
in the dictionary. Turn off when expecting lots of updates or knowing that
you'll get a chance to save (using .Save()) manually later
42onSavenull Function of the form function(Data){...} where Data is the .data property.
This will be called every time the dictionary needs saving. Switching off
.autoSave will switch this off. In contrast to .onChange this is handed
the complete data.
47onChangenull Function in the form function(Action,Key,Value){...} triggered when a single entry (record)
is changed. Action is either 'SET' or 'DEL'. This is unaffected by .autoSave
50generateKeynull Function in the form function(Value){... return key;} which can be used to generate a key
from a value. A typical use might be where the value is a data record / object which
already has an id. For example:
d.generateKey = function(Record){return Record.id;};
Add a single value or array to make an array
If K exists already then add to end of array (converting as necessary)
eg Set('Foo','Bar');
together give ['Bar','Buz',1,2,3]
WARNING: Remember arrays are concatenated not stored as-is.
253AsKeysValuesKeysArray Return an object of the form key->value based on the
array of supplied keys. Missing KeysArray returns all.
.Keys(), .reverseLookup() and .Sorted() return suitable KeysArray
NOTE: If a key has multiple values this will be returned as an array
so ... ,aKey:[val1,val2...],anotherkey:valx, ...
NOTE: Calling without KeysArray is not the same as accessing the .data
property as this provides a clone while .data is the real object
  • Dict.AsKeysValues needs an array
278AsValuesKeysArray Return an array of values as referenced by the keys supplied
in KeysArray. Missing KeysArray returns all.
.Keys(), .reverseLookup() and .Sorted() return suitable KeysArray
NOTE: If a key has multiple values this will be returned as separate
items so one->foo and two->bar,buz will return [foo,bar,buz]
  • Dict.AsValues needs an array
215Clear Clear whole dictionary data
225DeleteK Delete an item by key
Returns true only if Key existed
241DoesKeyExistK Does the specified key exist
Load values from an array
Optional KeyGenFun maps data to keys.
See .generateKey property for function details
This sets the .generateKey property
If omitted then a nonce will be used
Optional Merge boolean (NB not truthy) can force a merge.
Default is clear;
NOTE: Be careful when generating keys that you don't create
a collision. If you do then the earlier data will be
NOTE: Don't supply an array of arrays. (See .Set() )
  • Dict.FromArray() needs an array
Load dictionary from a JSON string
This might throw an error if the JSON can't be parsed...
... but illegal keys etc will be silently dropped.
See FromObject() for details
Copies the own properties of an object into
the dictionary. If Merge is true then append
or overwrite the existing keys.
If for any reason a key can't be set then return false, but
carry-on with the other keys
370GetK Return value for key or undefined
377Keys Return complete array of keys
Explicitly load dictionary from a given key in a store
  • Dict.LoadFromStore() has bad arguments
Return an array of keys where values match using various matching methods.
Tests with a simple ==
Tests with .search(RegExp) if value is a string
ReverseLookup(Value,'EQ') ==
ReverseLookup(Value,'IS') ===
ReverseLookup(Value,'GT') dict value < Value
ReverseLookup(Value,'LT') dict value > Value
ReverseLookup(Value,'IN') .indexOf() if working with strings.
NOTE this case sensitive. See (2)
Supply a boolean test function of the form (Test_value,dict_value)
eg d.ReverseLookup(myLargestNum,function(MLN,v){
return (v > (MLN-10)); /* Get last ten items */
473Save Forces a save action
If we've got a store set up then use that
If we've got an .onSave() function then call that
Forces a save to a specific store/key
  • Dict.SaveToStore() has bad arguments
Set up a Key/Value
K is normally a non-null string or number but if it is
explicitly null then a key (negative numbers counting down)
will be provided and appear as the return value
Returns false if K is not a (non-null)string or number
Returns false if Unique is true and key already exists
WARNING: Remember arrays are interpreted as multiple values so
a V of [foo,bar] will be equivilent to
.Set(aKey,foo) followed by .Add(aKey,bar)
Two strategies can be used if you have array data
Wrap in an object like this {data:myArray}
or use a Dict like this new Dict(myArray)
538SortedSortKeyFun Return an array of keys sorted by some function
If SortKeyFun is missing then sort by keys.
The supplied function is given the value and should return a string or number
eg. var mySortedArray = d.Sorted(function(V){return V.lastName + V.firstName;});
582ToJson export as JSON
590ValueCountK Count the number of values attached to a key
returns 0 if the key doesn't exist or the number
of values attached. See .Add() for explanation
private comparison function
used in sorting keys
We need this because "9" sorts after "10" and when keys start as
numbers they become strings. So this sorts numbers and strings properly
121_InvalidKeyNameK private function checking for silly key values
Returns true if a bad'un. NOTE TRUE=>BAD
Strings are preferred and must be non-null
Numbers are allowed but are converted to strings
(This is not a guarantee of safe keys but a sanity check)
140_NextAutoKey We may have to supply a key to replace a null supplied
so we have a downwards counter so auto-keys look like
-1,-2 .. -n
private function
Possibly save to store
In a typical internal call nothing happens if .store isn't set
if ActuallyDoIt is truthy then do it.
if ActuallyDoIt is falsey then only actually
save if autosave is on and data has changed
This reference document is completely self-contained so download and put with your other data sheets.
Created 14 May 16 at 11:53:52 Source from http://vulpeculox.net Written by Peter Fox @