/yaca

YACA (Yet Another Collection Approach) is a collection library for TypeScript / JavaScript

Primary LanguageTypeScriptMIT LicenseMIT

YACA

DEPRECATED - This library is deprecated and not maintained for a long time. It is probably not even compatible with recent versions of TypeScript

Yet Another Collection Approach

Introduction

YACA is another approach to introduce collections to TypeScript / JavaScript like known in Java, C# or other object-oriented programming languages. There are other approaches, but sometimes, small things regarding the convenience are missing. YACA provides (among common methods like add, remove or clear) a big variety of different non-standard methods, such as swapping of values, lookup of values according to a list of keys, or sorting of lists based on predefined or user-defined comparison methods. YACA is fully tested with hundred of assertions and a code coverage of 100%.

Coverage Status npm license

YACA contains at the moment List<T>, Dictionary<K,V> and SortedDictionary<K,V> as collection types. Further types (e.g. Stack) are planned.

Important features

  • Multiple add and remove methods like add, addRange, insertAtIndex, push or set
  • Multiple check methods like contains, containsKey, containsValues or containsKeyAsList
  • Multiple copy methods like copyToArray or getRange
  • forEach method provided (returns KeyValuePair for Dictionaries)
  • Built-in break and (optional) continue calls within forEach loops as control elements
  • Native sorting of the types number, string, boolean and Date (in List class)
  • Possibility of the implementation of a compareTo function in classes for sorting purpose (interface IComparer)
  • Possibility to sort SortedDictionary by key or value, according to the default behavior, a defined comparison method or an implementation of a compareTo function
  • Provided static compareTo functions for the types number, string, boolean and Date (module Comparer)

See the Change Log for recent updates.

Installation

npm install -S yaca

List<T>

A list stores values similar to an array. In comparison to an array, several methods like copies of a range, clearing or sorting can be applied out of the box. Additionally, operations for stacks and queues are included.

Supported methods

  • add
  • addRange
  • break (used in forEach)
  • clear
  • contains
  • continue (used in forEach)
  • dequeue
  • distinct
  • enqueue
  • forEach
  • get
  • getRange
  • indexOf
  • indicesOf
  • indicesOfAsList
  • insertAtIndices
  • lastIndexOf
  • next
  • peek
  • pop
  • remove
  • removeAll
  • removeAt
  • removeAtIndices
  • reverse
  • set
  • sort
  • swapValues

Usage

import {List} from 'yaca';

// Default constructor
let numberList: List<number> = new List<number>();

// Constructor with initial value
var stringList: List<string> = new List<string>("initial value");

// Constructor with array as initial value
let booelanList: List<boolean> = new List<boolean>([true, false, true, true]);

// Usage of more complex types
var otherList: List<SomeType> = new List<SomeType>();

numberList.add(22);

numberList.addRange([23,24,25]);

numberList.sort();

numberList.forEach(element => {
            console.log(element);
            if (element === 2)
            {
                numberList.continue(); // Optional / syntactic call to skip this iteration
                return; // Mandatory! -> sufficient as continue call
            }
            if (element === 4)
            {
                numberList.break(); // Breaks the forEach loop immediately
                return; // Mandatory!
            }

        });

numberList.clear();

See The List documentation page for further details:

  • Constructors
  • Properties
  • Methods

Dictionary<K,V>

A dictionary stores tuples of keys and an values. The type of both can be arbitrary. However, keys must be unique. Thus, a dictionary with boolean as keys allows only two tuples (true and false) in the Dictionary. If custom classes are used as keys, a valid toString method must be implemented in those classes or the method overrideHashFunction must be used in the Dictionary.

Supported methods

  • add
  • addRange
  • break (used in forEach)
  • clear
  • containsKey
  • containsKeys
  • containsValue
  • containsValues
  • continue (used in forEach)
  • distinct
  • forEach
  • get
  • getKeys
  • getKeysAsList
  • getKeysByValue
  • getKeysByValueAsList
  • getKeysByValues
  • getKeysByValuesAsList
  • getRange
  • getRangeByValue
  • getValues
  • getValuesAsList
  • next
  • overrideHashFunction
  • remove
  • removeByValue
  • set
  • swapValues

Usage

import {Dictionary} from 'yaca';

// Default constructor
let dictionary: Dictionary<number, string> = new Dictionary<number, string>();

// Constructor with initial value
let dictionary2: Dictionary<number, string> = new Dictionary<number, string>([1,2,3],["one","two","three"]]);

// Constructor with custom function to override the hashing of the keys (defaul is toString)
let dictionary3: Dictionary<number, Date> = new Dictionary<number, Date>(MyUtils.DateHashingFunction);

// Usage of more complex types
var otherDictionary: Dictionary<Date, SomeType> = new Dictionary<Date, SomeType>();

dictionary.add(22, "twenty two");

let value:string = dictionary2.get(2);

dictionary2.forEach(item => {
            console.log("key:" + item.key + " -> value:" + item.value);

            if (item.value === "two")
            {
                dictionary2.continue(); // Optional / syntactic call to skip this iteration
                return; // Mandatory! -> sufficient as continue call
            }
            if (item.key === 3)
            {
                dictionary2.break(); // Breaks the forEach loop immediately
                return; // Mandatory!
            }

        });

dictionary3.clear();

See The Dictionary documentation page for further details:

  • Constructors
  • Properties
  • Methods

SortedDictionary<K,V>

A sorted dictionary has the same behavior properties and methods like a standard dictionary. Additionally, there are many methods regarding the indices of the key value tuples and the possibility to sorting the dictionary by keys or values.

Supported methods

All methods of Dictionary <K,V>, and additionally...

  • getByIndex
  • getByIndices
  • getByIndicesAsList
  • getKeyByIndex
  • getKeysByIndices
  • getKeysByIndicesAsList
  • removeByIndex
  • removeByIndices
  • setByIndex
  • setByIndices
  • sortByKey
  • sortByValue

Usage

import {SortedDictionary} from 'yaca';
import {Comparer} from 'yaca';

// Default constructor
let dictionary: SortedDictionary<number, string> = new SortedDictionary<number, string>();

// Constructor with initial value
let dictionary2: Dictionary<number, string> = new Dictionary<number, string>([1,2,3],["one","two","three"]]);

// -> All operation of the standard Dictionary<K,V> class possible

let value: string = dictionary2.getByIndex(1); // Returns "two" (key=2; index=1; value="two")

dictionary2.removeByIndex(2); // Removes the third element (key=3; index=2; value="three")

dictionary2.sortByKey(); // Sort the dictionary by its keys (using default behavior of number)

dictionary2.sortByKey(Comparer.compareNumbers); // Sort the dictionary by its keys (using a comparison function)

dictionary2.sortByValue(); // Sort the dictionary by its values (using default behavior of string)

See The SortedDictionary documentation page for further details:

  • Constructors
  • Properties
  • Methods