Class o2.Collection


static class o2.Collection

A class to modify collections.

Defined in collection.core

Function Summary
static any()

An alias to o2.Collection.some.

static clear (Object ar)

Removes all the elements of the Object.

Usage example:

 var obj = {a:'b'};
 o2.Collection.clear(obj);
 // obj is now {}
 obj = [1,2,3];
 o2.CollectionHelper.clear(obj);
 // obj is now []
 
static clone()

An alias to o2.Collection.copy.

Usage example:

static compact (Object ar)

Remove null, and undefined members from the Object. This function alters the actual Object.

Usage example:

 var ar = [null, 1, 2, undefined, '', 3, 4];
 o2.Collection.compact(ar);
 // ar is now [1, 2, '', 3, 4]
 
static contains (Array ar, Object elm)

An alias to o2.Collection.indexOf(ar, elm) > -1.

Usage example:

 var ar = [1, 2, 3, 4];
 var isInAr = o2.Collection.contains(ar, 3);
 // isInAr is true
 
static copy (Object ar)

Creates a clone of the given Object, and returns it; leaving the original intact.

Usage example:

 var obj1 = {a:'b'};
 var obj2 = o2.Collection.copy(obj1);
 
static detect()

An alias to o2.Collection.find.

Usage example:

static diff (Arguments ...)

Takes the difference between the current collection and a number of other collections. Only items that do not remain in the rest of the collections will be returned.

Usage example:

 var ar1 = [1, 2, 3, 4, 5];
 var ar2 = [2, 3, 4, 5, 6];
 var ar3 = o2.Collection.diff(ar1, ar2);
 // ar3 is [1, 5. 6]
 
static each()

An alias to o2.Collection.forEach.

static every (Object obj, Function delegate, Object context)

Check whether every element of a collection passes a truth test.

Usage example:

 var collection = [1, 2, 3, 4, 5];

 var isAllNumeric = o2.Collection.every(collection, function(item) {
      return !isNaN(item);
 });
 // isAllNumeric will be true
 
static exclude (Object obj, Function delegate, Object context)

Excludes filtered out items from the collection. Returns a new collection without alterin the initial one.

Usage example:

 var collection = [1, 2, 3, 4, 5];

 var rest = o2.Collection.exclude(collection, function(item) {
      return item % 2 === 0;
 });

 // rest will be [1, 3, 5]
 
static extend (Object toObj, Object fromObj)

Merges two Objects or Arrays.

Usage example:

 var base = {lorem: 'ipsum'};
 var child = {dolor: 'sit'};

 o2.Collection.extend(child, base);

 // child => {lorem : 'ipsum', dolor : 'sit'}
 
static filter()

An alias to o2.Collection.grep.

static find (Object obj, delegate, Object context)

Gets the first collection item that validates against the given delegator.

Usage example:

 var ar = [1, 2, 3, 4];

 var res = o2.Collection.find(ar, function(value){
      return value === 3;
 });

 // res will be 3
 
static flatten (Object obj)

Shallow flattens an Array.

Does not alter the original object, returns a new flattened object instead.

Usage example:

 var ar = [[1, 2], [3, 4], 5]
 var flattened = o2.Object.flatten(ar);
 // flattened is [1, 2, 3, 4, 5]
 
static fold()

An alias to {o2.Collection.reduce}.

static foldR()
static forEach (Object obj, Function delegate)

Executes a delegate of the form fn(item, currentIndex, collection) for each element of the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5];

 o2.Collection.forEach(collection, function(item, index, collection) {
      log(item);
 });
 // will log:
 1
 2
 3
 4
 
static getCount()

An alias to {o2.Collection.getSize}

static getDifference()

An alias to o2.Collection.diff.

static getFirst (Object obj)

Gets the first item in the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5]
 
static getFirstN (Object obj, Integer n)

Gets the first n elements of the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5, 6];
 var firstFew = o2.Collection.getFirstN(collection, 3);
 // firstFew will be [1, 2, 3]
 
static getFunctions (Object obj)

Gets all the static methods of the object.

Usage example:

 var obj = {fn1 : function(){}, fn2 : function() {}, lorem : 1};
 var methods = o2.Collection.getFunctions(obj);
 // methods now is [fn1, fn2]
 
static getKeys (Object obj)

Gets all the keys of the object.

Usage example:

 var obj = {lorem : 'ipsum', dolor : 'sit'};
 var keys = o2.Collection.getKeys(obj);
 // keys will be ['lorem', 'dolor']
 
static getLast (Object obj)

Gets the last item in the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var last = o2.Collection.getLast(collection);
 // last will be 5
 
static getLastN (Object obj, Integer n)

Gets the last n items in the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var lastFew = o2.Collection.getLastN(collection, 3);
 // lastFew will be [3, 4, 5]
 
static getLength()

An alias to {o2.Collection.getSize}

static getMax (Object obj, Function delegate, Object context)

Gets the maximum value of the collection.

Usage example:

 var collection = [1, 3, 11, 42, 4, 5, 6];
 var meaningOfLife = o2.Collection.getMax(collection);
 // meaningOfLife will be 42

 var meaningOfUniverse = o2.Collection.getMax(collection, function(item) {
      return item !== 42 ? Math.PI : 42;
 });
 // meaningOfUniverse will also be 42
 
static getMethods()
static getMin (Object obj, Function delegate, Object context)

Gets the maximum value of the collection.

Usage example:

 var collection = [111, 311, 1211, 42, 114, 235, 126];
 var meaningOfLife = o2.Collection.getMin(collection);
 // meaningOfLife will be 42

 var meaningOfUniverse = o2.Collection.getMin(collection, function(item) {
      return item !== 42 ? 42 * Math.PI : 42;
 });
 // meaningOfUniverse will also be 42
 
static getRest (Object obj, Integer n)

Gets the elements of the collection after index n.

Usage example:

 var collection = [1, 2, 3, 4, 5];

 var rest = o2.Collection.getRest(collection);
 // rest will be [2, 3, 4, 5]

 rest = o2.Collection.getRest(collection, 2);
 // rest will be [3, 4, 5];
 
static getSize (Object obj)

Gets the number of items in the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var size = o2.Collection.getSize(collection);
 // size will be 5
 
static getSortedIndex (Array array, Object item, Function delegate)

Gets an index to insert the item at a sorted Array, so that is not needed to be resorted.

Usage example:

 var ar = [1, 2, 24, 30, 44, 66, 100];
 var idx = o2.Collection.getSortedIndex(42);
 // idx will be 4
 
static getValues (Object obj)

Gets the value of an Object that has {key1 : value1, key2 : value2 ... } kind of layout.

If an Array is passed, it makes a shallow copy of that array and returns it.

Usage example:

 var collection = {lorem : 1, ipsum : 2, dolor : 3};
 var values = o2.Collection.getValues(collection);
 // values will be ['lorem', 'ipsum', 'dolor']
 
static grep (Object obj, Function delegate)

Filters the items of a collections using an evaluator delegate and returns the filtered result set.

Usage example:

 var collection = [1, 2, 3, 4, 5, 6];
 var evens = o2.Collection.grep(collection, function(item) {
      return item % 2 === 0;
 });
 // evens will be [2, 4, 6]
 
static group (Object obj, Function delegate)

Groups the items in the collection by a key or an evaluator Function.

Usage example:

 var collection = [
      {lorem : 1},
      {lorem : 2},
      {lorem : 3},
      {ipsum : 1},
      {ipsum : 2}
 ];

 var lorems = o2.Collection.group(collection, 'lorem')
 //lorems will be {lorem : [1, 2, 3]}

 var grouped = o2.Collection.group(collection, function(item) {
      for(key in item) {
          if (item.hasOwnProperty(key)) {
              return key;
          }
      }
 });
 // grouped will be {lorem : [1, 2, 3], ipsum : [1, 2]}
 
static inArray()

An alias to o2.Collection.contains

Usage example:

static includes()
static indexOf (Object ar, Object elm)

Gets the index of the element in the given Array.

Usage example:

 var ar [1, 2, 3, 4];
 var id = o2.Collection.indexOf(ar, 3);
 // id is 2
 
static intersect (... varargin)

Returns an Array of items that are common in all of the collections passed in as parameters.

Usage example:

 var ar1 = [1, 2, 3, 4, 5];
 var ar2 = [2, 3, 4, 5, 6];
 var ar3 = o2.Collection.intersect(ar1, ar2);
 // ar3 is [2, 3, 4, 5]
 
static invoke (Object obj, Object delegate, varargin ...)

Calls the delegate Function with an optional set of parametrs for each item in the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 function log(item) { console.log(item); }
 o2.Collection.invoke(collection, log);
 // will log:
 // 1
 // 2
 // 3
 // 4
 // 5
 
static isEmpty (Object obj)

Check whether the collection contains any members.

Usage example:

 // This will return true:
 o2.Collection.isEmpty([]);

 // This will also return true:
 o2.Collection.isEmpty({});
 
static lastIndexOf (Object obj, Object item)

Returns the last index of the given item.

Usage example:

 var collection = [1, 2, 4, 2, 42, 2, 4, 42, 21, 12, 1];
 var idx = o2.Collection.lastIndexOf(collection, 42);
 // idx will be 7
 
static map (Object obj, Function delegate, Object context)

Calls a Function for each member of the collection, passing the current item as a parameter. Returns an Array containing the results of each call.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var squared = o2.Collection.map(collection, function(item) {
      return item*item;
 });
 // squared will be [1, 4, 9, 25]
 
static merge()

An alias to o2.Collection.extend.

static pluck (Object obj, Object key)

Hard to explain in words. Let us demonstrate by an example:

Usage example:

 var collection = [
      {key1 : {lorem1 : 'ipsum1'}, key2 : {dolor1 : 'amet1'}},
      {key1 : {lorem2 : 'ipsum2'}, key2 : {dolor2 : 'amet2'}},
      {key1 : {lorem3 : 'ipsum3'}, key2 : {dolor3 : 'amet3'}}
 ];

 // Will return:
 // [
 //    {dolor1 : 'amet1'},
 //    {dolor2 : 'amet2'},
 //    {dolor3 : 'amet3'}
 // ]
 o2.Collection.pluck(collection, 'key2');
 
static reduce (Object obj, Functon delegate, Object store, Object context)

Works similar to the reduce part of the Map Reduce algorithm.

Reduces a collection into a single value by applying a delegate of the form function(cache, value, index, collection) where cache is the accumulator, value is the iterated item, index is the item's index, and collection is the collection we are working on.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var reduced = o2.Collection.reduce(collection, function(store, value) {
      return store + value;
 }, 0);
 // reduced will be 15
 
static reduceRight (Object obj, Functon delegate, Object store, Object context)

Works similar to o2.Collection.fold, but goes from the end of the collection to the beginning of the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var reduced = o2.Collection.reduceRight(collection, function(
              store, value) {
      return store + value;
 }, 0);
 // reduced will be 15
 
static reject()

An alıas to o2.Collection.exclude.

static removeElement (Object obj, Object elm)

Removes all ocurences of the element from the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5]
 var result = o2.Collection.removeElement(collection, 3);
 // result will be [1, 2, 4, 5]
 
static removeElementByValue (Object obj, String name, Object value)

Removes and element from the collection if it has a property named name with a value value.

This method works by reference, and alters the given collection.

Usage example:

 var collection = { lorem : 1, ipsum : 2, sit : 3}
 o2.Collection.removeElementByValue(collection, 'sit', 3);
 // collection will be {lorem : 1, ipsum : 2}
 
static select()

An alias to o2.Collection.grep.

static shuffle (Object obj)

Randomizes the collection. Does not alter the original collection, just returns a randomized copy.

Usage example:

 var ar = [1, 2, 3, 4, 5];
 var shuffled = o2.Collection.shuffle(ar);
 
static some (Object obj, delegate, Object context)

Checks whether at least one element of the given collection satisfies a condition given with the delegate.

The delegate is in the form function(context, value, index, collection), iterates through the items of the collection and returns a boolean value. When this delegate returns true in any iteratioin, some(...) also returns true; it returns false otherwise.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var isSome = o2.Collection.some(collection, function(item) {
      return item > 4;
 });
 // isSome will be true
 
static sort (Object obj, Function delegate, Object context)

Sorts the collection.

Contrary to Array.prototype.sort, this function does not sort the collection in place, and therefore it does not alter the initial object's contents.

Usage example:

 var collection = [1, 2, 5, 4, 7];
 var sorted = o2.Collection.sort(collection, function(item) {
      return item;
 });
 // sorted will be [1, 2, 4, 5, 7]
 
static toArray (Object obj)

Safely converts the Object in question into anarray.

Usage example:

 var obj = {lorem : 1, ipsum : 2};
 var ar = o2.Collection.toArray(obj);
 // ar will be [1, 2]
 
static union (... varargin)

Merges several collections into a single Array

Usage example:

 var union = o2.Collection.union([1, 2], [2, 3], [3, 4], [5]);
 // union will be [1, 2, 3, 4, 5]
 
static unique (Object obj, Function delegate)

Removes duplicate entries from the collection. Returns a new Array; does not alter the original collection.

Usage example:

 var ar = [1, 2, 3, 2, 4, 2, 42];
 var uniq = o2.Collection.unique(ar);
 // uniq will be [1, 2, 3, 4, 42]
 
static zip (... varargin)

Takes a set of Arrays as parameters and brings together the elements that have the same index.

Usage example:

 var ar1 = [1,2,3];
 var ar2 = ['a', 'b', 'c', 'd'];
 var ar3 = [true, false];

 // returns:
 // [
 //       [1, 'a', true],
 //       [2. 'b', false],
 //       [3, 'c'],
 //       ['d']
 // ]
 zip(ar1, ar2, ar3);
 

Function Details

function any

static any()

An alias to o2.Collection.some.

See also:

function clear

static clear(Object ar)

Removes all the elements of the Object.

Usage example:

 var obj = {a:'b'};
 o2.Collection.clear(obj);
 // obj is now {}
 obj = [1,2,3];
 o2.CollectionHelper.clear(obj);
 // obj is now []
 
Parameters:
ar - the Object to clear.
Returns:
a reference to the object itself.

function clone

static clone()

An alias to o2.Collection.copy.

Usage example:

See also:

function compact

static compact(Object ar)

Remove null, and undefined members from the Object. This function alters the actual Object.

Usage example:

 var ar = [null, 1, 2, undefined, '', 3, 4];
 o2.Collection.compact(ar);
 // ar is now [1, 2, '', 3, 4]
 
Parameters:
ar - the Object to clean.
Returns:
a reference to the Object itself.

function contains

static contains(Array ar, Object elm)

An alias to o2.Collection.indexOf(ar, elm) > -1.

Usage example:

 var ar = [1, 2, 3, 4];
 var isInAr = o2.Collection.contains(ar, 3);
 // isInAr is true
 
Parameters:
ar - the Array to search.
elm - the Object to match.
Returns:
true if the Array contains the item, false otherwise.

function copy

static copy(Object ar)

Creates a clone of the given Object, and returns it; leaving the original intact.

Usage example:

 var obj1 = {a:'b'};
 var obj2 = o2.Collection.copy(obj1);
 
Parameters:
ar - the object to clone.
Returns:
the copied Object.

function detect

static detect()

An alias to o2.Collection.find.

Usage example:

See also:

function diff

static diff(Arguments ...)

Takes the difference between the current collection and a number of other collections. Only items that do not remain in the rest of the collections will be returned.

Usage example:

 var ar1 = [1, 2, 3, 4, 5];
 var ar2 = [2, 3, 4, 5, 6];
 var ar3 = o2.Collection.diff(ar1, ar2);
 // ar3 is [1, 5. 6]
 
Parameters:
... - variable number of input arguments; each argument should either be an Array or an iterable Object.
Returns:
an Array of non-matching items.

function each

static each()

An alias to o2.Collection.forEach.


function every

static every(Object obj, Function delegate, Object context)

Check whether every element of a collection passes a truth test.

Usage example:

 var collection = [1, 2, 3, 4, 5];

 var isAllNumeric = o2.Collection.every(collection, function(item) {
      return !isNaN(item);
 });
 // isAllNumeric will be true
 
Parameters:
obj - an Array or an iterable collection.
delegate - an iterator of the form function(item, index, obj); where item is the current collection item, index is the current index and obj is the collection itself.
context - (optional, defaults to undefined) the context that the delegate uses as the this reference.
Returns:
true if delegate returns true for every element of the collection; false otherwise.

function exclude

static exclude(Object obj, Function delegate, Object context)

Excludes filtered out items from the collection. Returns a new collection without alterin the initial one.

Usage example:

 var collection = [1, 2, 3, 4, 5];

 var rest = o2.Collection.exclude(collection, function(item) {
      return item % 2 === 0;
 });

 // rest will be [1, 3, 5]
 
Parameters:
obj - an Array or an iterable Object to work on.
delegate - the iterator in the form function(context, value, index, obj) where value is the current element of obj being iterated over, and index is the index of that element.
context - (optional, defaults to undefined) the context that the delegate uses as the this reference.
Returns:
a new filtered object.
See also:

function extend

static extend(Object toObj, Object fromObj)

Merges two Objects or Arrays.

Usage example:

 var base = {lorem: 'ipsum'};
 var child = {dolor: 'sit'};

 o2.Collection.extend(child, base);

 // child => {lorem : 'ipsum', dolor : 'sit'}
 
Parameters:
toObj - the Object to copy values to.
fromObj - the Object to copy values from.
Returns:
a reference to the modified toObj.

function filter

static filter()

An alias to o2.Collection.grep.

See also:

function find

static find(Object obj, delegate, Object context)

Gets the first collection item that validates against the given delegator.

Usage example:

 var ar = [1, 2, 3, 4];

 var res = o2.Collection.find(ar, function(value){
      return value === 3;
 });

 // res will be 3
 
Parameters:
obj - the Array or an iterable Object.
delegate - Iterator Function in the form function(value, index, collection).
context - (optional, defaults to undefined) the context that acts as the this reference in the iterator.
Returns:
the first truthy evaluated item; null if nothing is found.

function flatten

static flatten(Object obj)

Shallow flattens an Array.

Does not alter the original object, returns a new flattened object instead.

Usage example:

 var ar = [[1, 2], [3, 4], 5]
 var flattened = o2.Object.flatten(ar);
 // flattened is [1, 2, 3, 4, 5]
 
Parameters:
obj - an Array or an iterable Object to work on.
Returns:
the flattened collection.

function fold

static fold()

An alias to {o2.Collection.reduce}.


function foldR

static foldR()

function forEach

static forEach(Object obj, Function delegate)

Executes a delegate of the form fn(item, currentIndex, collection) for each element of the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5];

 o2.Collection.forEach(collection, function(item, index, collection) {
      log(item);
 });
 // will log:
 1
 2
 3
 4
 
Parameters:
obj - the Array or an iterable Object.
delegate - the iterator in the form function(item, index, collection).

function getCount

static getCount()

An alias to {o2.Collection.getSize}


function getDifference

static getDifference()

An alias to o2.Collection.diff.

See also:

function getFirst

static getFirst(Object obj)

Gets the first item in the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5]
 
Parameters:
obj - an Array or an iterable Object to work on.
Returns:
the first item in the collection if exists; null otherwise.

function getFirstN

static getFirstN(Object obj, Integer n)

Gets the first n elements of the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5, 6];
 var firstFew = o2.Collection.getFirstN(collection, 3);
 // firstFew will be [1, 2, 3]
 
Parameters:
obj - an Array or an iterable Object to work on.
n - the number of items to retrieve.
Returns:
the first n elements of the collection if the collection has more than n items; all of the items in the collection otherwise.

function getFunctions

static getFunctions(Object obj)

Gets all the static methods of the object.

Usage example:

 var obj = {fn1 : function(){}, fn2 : function() {}, lorem : 1};
 var methods = o2.Collection.getFunctions(obj);
 // methods now is [fn1, fn2]
 
Parameters:
obj - an Array or an iterable Object to work on.
Returns:
gets all the member Functions in the current object.

function getKeys

static getKeys(Object obj)

Gets all the keys of the object.

Usage example:

 var obj = {lorem : 'ipsum', dolor : 'sit'};
 var keys = o2.Collection.getKeys(obj);
 // keys will be ['lorem', 'dolor']
 
Parameters:
obj - an Array or an iterable Object to work on.
Returns:
an Array of the object's keys.

function getLast

static getLast(Object obj)

Gets the last item in the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var last = o2.Collection.getLast(collection);
 // last will be 5
 
Parameters:
obj - an Array or an iterable Object to work on.
Returns:
the last item in the collection if any; null otherwise.

function getLastN

static getLastN(Object obj, Integer n)

Gets the last n items in the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var lastFew = o2.Collection.getLastN(collection, 3);
 // lastFew will be [3, 4, 5]
 
Parameters:
obj - an Array or an iterable Object to work on.
n - the number of items to retrieve.
Returns:
the last n items if the collection has at least n items; all the items of the collection otherwise.

function getLength

static getLength()

An alias to {o2.Collection.getSize}


function getMax

static getMax(Object obj, Function delegate, Object context)

Gets the maximum value of the collection.

Usage example:

 var collection = [1, 3, 11, 42, 4, 5, 6];
 var meaningOfLife = o2.Collection.getMax(collection);
 // meaningOfLife will be 42

 var meaningOfUniverse = o2.Collection.getMax(collection, function(item) {
      return item !== 42 ? Math.PI : 42;
 });
 // meaningOfUniverse will also be 42
 
Parameters:
obj - an Array or an iterable Object to work on.
delegate - (optional, defaults to undefined) the evaluator Function in the form functon(item, index, obj) where item is the current collection item; index is the index of that item.
context - (optional, defaults to undefined) the context that the delegate uses as the this reference.
Returns:
the maximum value in the collection.

function getMethods

static getMethods()

function getMin

static getMin(Object obj, Function delegate, Object context)

Gets the maximum value of the collection.

Usage example:

 var collection = [111, 311, 1211, 42, 114, 235, 126];
 var meaningOfLife = o2.Collection.getMin(collection);
 // meaningOfLife will be 42

 var meaningOfUniverse = o2.Collection.getMin(collection, function(item) {
      return item !== 42 ? 42 * Math.PI : 42;
 });
 // meaningOfUniverse will also be 42
 
Parameters:
obj - an Array or an iterable Object to work on.
delegate - (optional, defaults to undefined) the evaluator Function in the form functon(item, index, obj) where item is the current collection item; index is the index of that item.
context - (optional, defaults to undefined) the context that the delegate uses as the this reference.
Returns:
the minimum value in the collection.

function getRest

static getRest(Object obj, Integer n)

Gets the elements of the collection after index n.

Usage example:

 var collection = [1, 2, 3, 4, 5];

 var rest = o2.Collection.getRest(collection);
 // rest will be [2, 3, 4, 5]

 rest = o2.Collection.getRest(collection, 2);
 // rest will be [3, 4, 5];
 
Parameters:
obj - an Array or an iterable Object to work on.
n - (optional; defaults to 1) the zero-based index to cut at.
Returns:
the items after the index n (nth item included)

function getSize

static getSize(Object obj)

Gets the number of items in the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var size = o2.Collection.getSize(collection);
 // size will be 5
 
Parameters:
obj - an Array or an iterable Object to work on.
Returns:
the number of items in the collection.

function getSortedIndex

static getSortedIndex(Array array, Object item, Function delegate)

Gets an index to insert the item at a sorted Array, so that is not needed to be resorted.

Usage example:

 var ar = [1, 2, 24, 30, 44, 66, 100];
 var idx = o2.Collection.getSortedIndex(42);
 // idx will be 4
 
Parameters:
array - an Array to work on.
item - the item to insert.
delegate - (optional, defaults to identity function), a Function that takes the current item as a parameter and returns an Integer value.
Returns:
-1 if the collection is not an Array; the computed sorted index otherwise.

function getValues

static getValues(Object obj)

Gets the value of an Object that has {key1 : value1, key2 : value2 ... } kind of layout.

If an Array is passed, it makes a shallow copy of that array and returns it.

Usage example:

 var collection = {lorem : 1, ipsum : 2, dolor : 3};
 var values = o2.Collection.getValues(collection);
 // values will be ['lorem', 'ipsum', 'dolor']
 
Parameters:
obj - an Array or an iterable Object to work on.
Returns:
the values in the collection.

function grep

static grep(Object obj, Function delegate)

Filters the items of a collections using an evaluator delegate and returns the filtered result set.

Usage example:

 var collection = [1, 2, 3, 4, 5, 6];
 var evens = o2.Collection.grep(collection, function(item) {
      return item % 2 === 0;
 });
 // evens will be [2, 4, 6]
 
Parameters:
obj - an Array or an iterable Object to work on.
delegate - the filter Function in the form [Boolean] function(item).
Returns:
the filtered collection.

function group

static group(Object obj, Function delegate)

Groups the items in the collection by a key or an evaluator Function.

Usage example:

 var collection = [
      {lorem : 1},
      {lorem : 2},
      {lorem : 3},
      {ipsum : 1},
      {ipsum : 2}
 ];

 var lorems = o2.Collection.group(collection, 'lorem')
 //lorems will be {lorem : [1, 2, 3]}

 var grouped = o2.Collection.group(collection, function(item) {
      for(key in item) {
          if (item.hasOwnProperty(key)) {
              return key;
          }
      }
 });
 // grouped will be {lorem : [1, 2, 3], ipsum : [1, 2]}
 
Parameters:
obj - an Array or an iterable Object to work on.
delegate - A String key that the items in the collection share, or a Function in the form [key] function(item, index) where item is the current collection item, index if that item's index; and the return value is a key to group.
Returns:
an Array of grouped items.

function inArray

static inArray()

An alias to o2.Collection.contains

Usage example:


function includes

static includes()

function indexOf

static indexOf(Object ar, Object elm)

Gets the index of the element in the given Array.

Usage example:

 var ar [1, 2, 3, 4];
 var id = o2.Collection.indexOf(ar, 3);
 // id is 2
 
Parameters:
ar - the Array or Object to search.
elm - the Object to match.
Returns:
the index of the element if found, -1 otherwise.

function intersect

static intersect(... varargin)

Returns an Array of items that are common in all of the collections passed in as parameters.

Usage example:

 var ar1 = [1, 2, 3, 4, 5];
 var ar2 = [2, 3, 4, 5, 6];
 var ar3 = o2.Collection.intersect(ar1, ar2);
 // ar3 is [2, 3, 4, 5]
 
Parameters:
varargin - the objects to intersect as input arguments.
Returns:
an Array containing only the values that are common in all of the collections given.

function invoke

static invoke(Object obj, Object delegate, varargin ...)

Calls the delegate Function with an optional set of parametrs for each item in the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 function log(item) { console.log(item); }
 o2.Collection.invoke(collection, log);
 // will log:
 // 1
 // 2
 // 3
 // 4
 // 5
 
Parameters:
obj - an Array or an iterable Object to work on.
delegate - the delegate to invoke in the form delegate(item, ...varargin). If it's a String then item[delegate] will be used instead.
... - A set of parameters to pass after the delegate.
See also:

function isEmpty

static isEmpty(Object obj)

Check whether the collection contains any members.

Usage example:

 // This will return true:
 o2.Collection.isEmpty([]);

 // This will also return true:
 o2.Collection.isEmpty({});
 
Parameters:
obj - an Array or an iterable Object to work on.
Returns:
true if the collection is empty; false otherwise.

function lastIndexOf

static lastIndexOf(Object obj, Object item)

Returns the last index of the given item.

Usage example:

 var collection = [1, 2, 4, 2, 42, 2, 4, 42, 21, 12, 1];
 var idx = o2.Collection.lastIndexOf(collection, 42);
 // idx will be 7
 
Parameters:
obj - an Array or an iterable Object to work on.
item - the item to check the index of.
Returns:
the last index of the item if exists, -1 otherwise.

function map

static map(Object obj, Function delegate, Object context)

Calls a Function for each member of the collection, passing the current item as a parameter. Returns an Array containing the results of each call.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var squared = o2.Collection.map(collection, function(item) {
      return item*item;
 });
 // squared will be [1, 4, 9, 25]
 
Parameters:
obj - an Array or an iterable Object to work on.
delegate - A mapper in the form function(item, index, collection) where item is the current collection element, index is its index, and collection is the current object obj.
context - (optional, defaults to undefined) the context that the delegate uses as the this reference.
Returns:
a mapped Array.

function merge

static merge()

An alias to o2.Collection.extend.


function pluck

static pluck(Object obj, Object key)

Hard to explain in words. Let us demonstrate by an example:

Usage example:

 var collection = [
      {key1 : {lorem1 : 'ipsum1'}, key2 : {dolor1 : 'amet1'}},
      {key1 : {lorem2 : 'ipsum2'}, key2 : {dolor2 : 'amet2'}},
      {key1 : {lorem3 : 'ipsum3'}, key2 : {dolor3 : 'amet3'}}
 ];

 // Will return:
 // [
 //    {dolor1 : 'amet1'},
 //    {dolor2 : 'amet2'},
 //    {dolor3 : 'amet3'}
 // ]
 o2.Collection.pluck(collection, 'key2');
 
Parameters:
obj - an Array or an iterable Object to work on.
key - the key to pluck.
Returns:
a plucked subset.

function reduce

static reduce(Object obj, Functon delegate, Object store, Object context)

Works similar to the reduce part of the Map Reduce algorithm.

Reduces a collection into a single value by applying a delegate of the form function(cache, value, index, collection) where cache is the accumulator, value is the iterated item, index is the item's index, and collection is the collection we are working on.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var reduced = o2.Collection.reduce(collection, function(store, value) {
      return store + value;
 }, 0);
 // reduced will be 15
 
Parameters:
obj - an Array or an iterable Object to work on.
delegate - the reducer Function.
store - the initial seed.
context - (optional, defaults to undefined) the context that the delegate uses as the this reference.
Returns:
a single reduced value.

function reduceRight

static reduceRight(Object obj, Functon delegate, Object store, Object context)

Works similar to o2.Collection.fold, but goes from the end of the collection to the beginning of the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var reduced = o2.Collection.reduceRight(collection, function(
              store, value) {
      return store + value;
 }, 0);
 // reduced will be 15
 
Parameters:
obj - an Array or an iterable Object to work on.
delegate - the reducer Functon.
store - the initial seed.
context - (optional, defaults to undefined) the context that the delegate uses as the this reference.
Returns:
a single reduced value.

function reject

static reject()

An alıas to o2.Collection.exclude.


function removeElement

static removeElement(Object obj, Object elm)

Removes all ocurences of the element from the collection.

Usage example:

 var collection = [1, 2, 3, 4, 5]
 var result = o2.Collection.removeElement(collection, 3);
 // result will be [1, 2, 4, 5]
 
Parameters:
obj - an Array or an iterable Object to work on.
elm - the element to remove.

function removeElementByValue

static removeElementByValue(Object obj, String name, Object value)

Removes and element from the collection if it has a property named name with a value value.

This method works by reference, and alters the given collection.

Usage example:

 var collection = { lorem : 1, ipsum : 2, sit : 3}
 o2.Collection.removeElementByValue(collection, 'sit', 3);
 // collection will be {lorem : 1, ipsum : 2}
 
Parameters:
obj - an Array or an iterable Object to work on.
name - the name of the property.
value - the value to compare.
Returns:
a reference to obj itself.

function select

static select()

An alias to o2.Collection.grep.

See also:

function shuffle

static shuffle(Object obj)

Randomizes the collection. Does not alter the original collection, just returns a randomized copy.

Usage example:

 var ar = [1, 2, 3, 4, 5];
 var shuffled = o2.Collection.shuffle(ar);
 
Parameters:
obj - an Array or an iterable Object to work on.
Returns:
an Array that's a shuffled copy of the initial collection.

function some

static some(Object obj, delegate, Object context)

Checks whether at least one element of the given collection satisfies a condition given with the delegate.

The delegate is in the form function(context, value, index, collection), iterates through the items of the collection and returns a boolean value. When this delegate returns true in any iteratioin, some(...) also returns true; it returns false otherwise.

Usage example:

 var collection = [1, 2, 3, 4, 5];
 var isSome = o2.Collection.some(collection, function(item) {
      return item > 4;
 });
 // isSome will be true
 
Parameters:
obj - an Array or an iterable Object to work on.
delegate - Iterator Function in the form function(value, index, collection).
context - The context to regard as this reference.
Returns:
true if the iterator returns true for at least one element; returns false otherwise.

function sort

static sort(Object obj, Function delegate, Object context)

Sorts the collection.

Contrary to Array.prototype.sort, this function does not sort the collection in place, and therefore it does not alter the initial object's contents.

Usage example:

 var collection = [1, 2, 5, 4, 7];
 var sorted = o2.Collection.sort(collection, function(item) {
      return item;
 });
 // sorted will be [1, 2, 4, 5, 7]
 
Parameters:
obj - an Array or an iterable Object to work on.
delegate - (Optional, defaults to an identity function that returns the original item) the sorter in the form function(value, index, collection) where value is the current item, index is that item's index; and collection is obj; this delegate should return an Integer value. function(item, index, collection).
context - (optional, defaults to undefined) the context that the delegate uses as the this reference.
Returns:
a sorted copy of the initial collection.

function toArray

static toArray(Object obj)

Safely converts the Object in question into anarray.

Usage example:

 var obj = {lorem : 1, ipsum : 2};
 var ar = o2.Collection.toArray(obj);
 // ar will be [1, 2]
 
Parameters:
obj - Any Object to convert to an Array. If obj is, in deed, an Array, then a shallow copy of it is returned without altering the original Object.
Returns:
the generated Array.
See also:

function union

static union(... varargin)

Merges several collections into a single Array

Usage example:

 var union = o2.Collection.union([1, 2], [2, 3], [3, 4], [5]);
 // union will be [1, 2, 3, 4, 5]
 
Parameters:
varargin - the collections to merge as input parameters.
Returns:
the merged Array.
See also:
o2.Collection.istersect

function unique

static unique(Object obj, Function delegate)

Removes duplicate entries from the collection. Returns a new Array; does not alter the original collection.

Usage example:

 var ar = [1, 2, 3, 2, 4, 2, 42];
 var uniq = o2.Collection.unique(ar);
 // uniq will be [1, 2, 3, 4, 42]
 
Parameters:
obj - an Array or an iterable Object to work on.
delegate - (optional, defaults to undefined) a mapper in the form function(item, index, collection) where item is the current collection element, index is its index, and collection is the current object obj.
Returns:
a copy of the collection containing unique items.

function zip

static zip(... varargin)

Takes a set of Arrays as parameters and brings together the elements that have the same index.

Usage example:

 var ar1 = [1,2,3];
 var ar2 = ['a', 'b', 'c', 'd'];
 var ar3 = [true, false];

 // returns:
 // [
 //       [1, 'a', true],
 //       [2. 'b', false],
 //       [3, 'c'],
 //       ['d']
 // ]
 zip(ar1, ar2, ar3);
 
Parameters:
varargin - the Arrays to zip as a variable number of input arguments.
Returns:
a zipped Array.