ki-map
v1.0.2
Published
"Keyed and Indexed Map", a pure javascript object that simulates the native 'Map' object with indexing features and others useful methods.
Downloads
10
Maintainers
Readme
kiMap
Pure javascript object that simulates the native 'Map' object with indexing features and others useful methods.
Documentation
Install
npm install --save kiMap
Methods and properties
- setLogger(obj)
- debug(options)
- size
- clear()
- delete(ki)
- entries()
- forEach(callback, thisArg)
- get(ki)
- has(ki)
- keys()
- set(ki, value, options)
- values()
- indexOf(key)
- keyOf(index)
- keyUpdate(old_key, new_key, force)
- setMany(kv_array)
- merge(map)
- swap(ki_A,ki_B)
- move(ki, pos)
Create the kiMap object
let kiMap = require('ki-map');
let map = new kiMap();
setLogger(obj)
Set the logger object. By default is the native console object.
- {object|null} obj - (optional, default:console) a console-like object
map.setLogger(mylogger);
map.setLogger(null); //To disable internal logging just pass a null object.
debug(options)
Show the internal data-structures and makes some simple checks.
- {object} options - (optional, default:null) set the debug output
map.debug({
label:'', // for a labeled debug output
complete:false // print all the internal structures
});
size
Current size of the collection.
- returns {integer} - values:[0,+inf)
let length = map.size;
clear()
Empty all internal structures and reset the counters. After this, the kiMap is totally cleaned.
map.clear();
delete(ki)
Removes the specified element from the collection.
- param {number|string} ki - key or index
- returns {integer} index of the deleted item or a number<0
map.delete(3);
map.delete('label6');
if(map.delete(4)<0) console.warn('No object found!');
entries()
All the elements stored within the collection.
- returns {iterator}
let it1 = map.entries();
let d1 = it1.next();
while(!d1.done){
console.log('index:',d1.value.i);
console.log('key:',d1.value.k);
console.log('data:',d1.value.d);
d1 = it1.next();
}
forEach(callback, thisArg)
Executes a provided function once per each key/value pair in the Map object, in insertion order.
- param {function} callback - Function to execute for each element; prototype: callback(index,key,value,kiMap)
- param {object} thisArg - Value to use as this when executing callback.
// Simple forEach
x.forEach(function(i,k,d,map){
console.log('index:',i);
console.log('key:',k);
console.log('data:',d);
});
// Usage of thisArg
class exampleClass{
fn(){
map.forEach(function(i,k,d,this_map){
this.show(i,k,d,this_map);
},this);
}
show(i,k,d,this_map){
console.log('index:',i);
console.log('key:',k);
console.log('data:',d);
}
}
let myObj = new exampleClass();
myObj.fn();
get(ki)
Get an element from the collection.
- param {integer|string} ki - key or index
- returns {mixed|null} null if data not found
map.get(1);
map.get('label');
has(ki)
Returns a boolean indicating whether an element with the specified key exists or not.
- param {integer|string} ki - key or index
- returns {boolean}
map.has(1);
map.has('label');
keys()
All the keys within the collection.
- returns {array}
map.keys(); //returns ['label1','label2','label3']
set(ki, value, options)
Adds or updates an element with a specified index and/or key and value.
- param {integer|string} ki - key or index
- param {any} value
- param {object} options - 'key' used when ki is an index, ...
- returns {number} index of the new element
// Insertion with label
x.set('label1',{oo:'obj1',cc:1}); // 1
// Simple insertion (the label will be 'autokey_1')
x.set({oo:'obj2',cc:2}); // 2
// Insertion in the specified position 3
x.set(3,{oo:'obj3',cc:3}); // 3
// Insertion in the specified position 3 with label 'mykey44'
x.set(4,{oo:'obj44',cc:44},{
key:'mykey44'
})); // 4
values()
Returns a new Iterator object that contains the values for each element in the Map object in insertion order.
- returns {iterator}
let it1 = map.entries();
let d1 = it1.next();
while(!d1.done){
console.log('data:',d1.value);
d1 = it1.next();
}
indexOf(key)
Returns the index of the element stored with the specified key.
- param {string} key
- returns {number} - a value lower than zero indicates that the element was not found
map.indexOf('label3');
keyOf(index)
Returns the key of the element stored within the specified index.
- param index
- returns {string|null} - null indicates that the element was not found
map.keyOf(3);
keyUpdate(old_key, new_key, force)
Update the key of an item. If an item with new_key already exists, this method does nothing. To force the update and the overwrite, set force=true.
- param {string} old_key
- param {string} new_key
- param {boolean} force (optional, default:false)
- return {integer} position of the updated element
map.keyUpdate('label1', 'newlabel1'); // 1
map.keyUpdate('label3', 'label1'); // -1 - no update
map.keyUpdate('label3', 'label1', true); // 3 - the element 1 will have 'autokey_4'
setMany(kv_array)
Insert a bunch of values from an array. In case of key collisions, the key of the new element will be changed with an 'autokey_xx'.
- param {Array} kv_array - simple array or array with couples [key,value]
- returns {boolean} true if the insertion is done
map.setMany([
['tag20',{oo:'obj20',cc:20}],
['tag21',{oo:'obj21',cc:21}]
]);
map.setMany([
{oo:'obj30',cc:30},
{oo:'obj31',cc:31}
]);
merge(map)
Extends the current map with the values inside the 'map' argument. In case of key collisions, the key of the new element will be changed with an 'autokey_xx'.
- param {kiMap} map
- returns {boolean} true if the insertion is done
map1.merge(map2);
swap(ki_A,ki_B)
Swap two items.
- param {string|integer} ki_A - key or index
- param {string|integer} ki_B - key or index
- return {boolean}
map.swap('label1','label2');
map.swap('label1',1);
map.swap(0,'label2');
map.swap(0,1);
move(ki, pos)
Move the item with ki to the specified position
- param {string|number} ki - key or index
- param {integer} pos - final position
- returns {integer}
map.move('label1',4);
map.move(0,4);
Examples
The directory '/examples' has some useful examples ready to be executed as node scripts.
node ./examples/e1.js
- e1.js - Example 1 > Fill, move and swap
- e2.js - Example 2 > Iterators usage
- e3.js - Example 3 > kiMap.forEach() usage
- e4.js - Example 4 > Mixed basic functions: size, get, keyOf, indexOf, has, keys, clear
- e5.js - Example 5 > kiMap.keyUpdate() usage
- e6.js - Example 6 > kiMap.setMany() and kiMap.merge() usage
Bugs or requests
I am still working on this project. So, please, report me any kind of bug or requests about new features. You can do it on GitHub Issues or via email. I will try to solve each issues in a reasonable time.