Free component Utils

A global icon 'FCUtils' is directly available in the controller code of the 'Free component', which serves helper utilities to simplify recurring problems.
The following is an interface description of the FCUtils (The "CollectionLike" type is representative for an IList object or a native array:
FCUtils interface description
/**
* Checks if the given value is an IList or an Array
*
* @param value The value to check
* @returns true if value is CollectionLike
*/
isCollection(value: any): boolean;
 
/**
* Checks if the given value is an empty collection.
* If value is not a collection at all, it will be considered as empty collection
*
* @param value Any value to be checked
* @return true if the given value is an empty collection or if value is null or undefined, false otherwise
*/
isEmpty(value: any): boolean;
 
/**
* Returns the number of items in the given collection.
* If list is not a collection 0 will be returned.
*
* @param list A collection
*/
size(list: CollectionLike<any>): number;
 
/**
* Concatenates all given 'joins' elements and adds
* the result to the given 'target' array or IList.
* If a given element is an array or IList, all elements
* will appended to the result
*
* ### Example
* ```
* var target = [];
* FCUtils.join(target, [1, 2, 3], 'hello', ['world', 'foo']);
*
* target.length; // = 6 = [1, 2, 3].length + 1 + ['world', 'foo'].length
*
* console.log(target);
*
* //prints: [1, 2, 3, 'hello', 'world', 'foo']
* ```
* ```
*
* ```
* @param target The target array or IList which will add the joined 'joins'
* @param joins The elements which will be joined (var args)
* @returns A reference to the given target
*/
join<V extends CollectionLike<E>, E>(target: V, ...joins: Array<CollectionLike<E> | E>): V;
 
/**
* Returns the index of the given item within the given IList or array.
* How the items are compared for equality is defined by the 'useEquals' parameter (see useEquals paramter)
*
* ### Example:
* ```
* var list = ['hello', new Long(5), 5, 7, 5];
*
* FCUtils.getItemIndex(list, 'hello'); //returns 0 (first item of the list)
* FCUtils.getItemIndex(list, 5, 3); //returns 4 (fifth item of the list because the search started at index 3)
* FCUtils.getItemIndex(list, 5, 0); //returns 2 (third item of the list because new Long(5) !== 5)
* FCUtils.getItemIndex(list, 5, 0, true); //returns 1 (second item of the list because (new Long(5)).equals(5) )
* ```
* ```
*
* ```
* @param list An IList or array
* @param item The item which will be searched in the list
* @param start The start index to begin the search (defaults to 0)
*
* @returns The index of the first occurence of the given item or -1 if it was not found
*/
getItemIndex(list: CollectionLike<any>, item: any, start?: number): number;
 
/**
* Removes an item from the given list by checking if it's index is greater than or equal to 0.
* True will be returned if the item was contained in the list and was therefore removed
*
* @param list The list from which the item will be removed
* @param item The item which will be removed if it is contained in the list in the first place
*
* @returns true if the item was contained and therefore removed from the list
*/
removeItem<T>(list: CollectionLike<T>, item: T): boolean;
 
/**
* Removes the item at the given index and returns the removed item
* or undefined if the index was out of range or if the list was null
* or undefined
*
* @param list The list from which the item will be removed
* @param index The index of the item which will be removed
* @returns the item which has been removed or undefined if the index
* was out of range or if the given list was null or undefined
*/
removeItemAt<T>(list: CollectionLike<T>, index: number): T;
 
/**
* Retreives the item at the given index and returns the item
* or undefined if the index was out of range or if the list was null
* or undefined
*
* @param list The list from which the item will be retreived
* @param index The index of the item which will be retreived
* @returns The item which has been retreived or undefined if the index
* was out of range or if the given list was null or undefined
*/
getItemAt<T>(list: CollectionLike<T>, index: number): T;
 
/**
* Adds an item to the given list and returns the
* new length of the list or 0 if the item was not added
*
* @param list The list which will add the item
* @param item The item which will be added
* @returns The new length of the list or 0 if the item was not added
*/
addItem<T>(list: CollectionLike<T>, item: T): number;
 
/**
* Inserts an item into the list at the given index
*
* @param list An IList or array which will insert the item
* @param item The item which will be inserted
* @param index The insert position
* @returns The new length of the list or 0 if the item was not added
*/
addItemAt<T>(list: CollectionLike<T>, item: T, index: number): number;
 
/**
* Replaces the item at the given index with the
* given one and returns the replaced item
*
* @param item The item which will be set
* @param index The index of the replaced item
* @returns The replaced item or undefined if the index was out of range
* or if the list was null or undefined, or if the replaced item was undefined
*/
setItemAt<T>(list: CollectionLike<T>, item: T, index: number): T;
 
/**
* Sorts the given collection considering an optional sort function (see parameter sortFunction).
* If no sort function is given the comparison is made by itemA < itemB
*
* @param list The collection like object to be sorted
* @param inverse Inverts the sorting order if true (defaults to false)
* @param sortFunction An optional function to compare two items with each other (returns -1 if a < b, 0 if a === b or 1 if a > b)
*/
sort<T>(list: CollectionLike<T>, inverse?: boolean, sortFunction?: ((itemA: T, itemB: T) => number)): void;
 
/**
* Clears the given collection. i.e. Removes all items
*
* @param list The collection like object to be cleared
*/
clear(list: CollectionLike<any>): void;
 
/**
* Tries to convert the given collection into an array.
* The copy parameter determines whether a copy of the original data source should be returned (defaults to true).
* If the given list is not a CollectionLike object, toArray looks for a toArray() member function and applies it if given.
*
* @param list A collection like element
* @param copy Determines whether a copy of the original data source should be returned (defaults to true)
* @returns The given object converted to an array
*/
toArray<T>(list: CollectionLike<T>, copy?: boolean): T[];
 
/**
* Ensures that the given list is converted into an IList collection.
* If it is an IList already, the input parameter will be simply returned.
* If the conversion is not possible, the result will be null.
*/
toList<T>(list: CollectionLike<T>): IList<T>;
 
/**
* Iterates through all items in the given collection and calls the callback function for each of them.
* The callback function may return a truthy value which causes the iteration to stop immediately
*
* @param col A collection
* @param cb A function which gets called for each item in the given collection. If it returns a truthy value, the iteration will stop immediately
* @param thisArg Defines the this scope of the callback function cb
*/
forEach<T>(col: CollectionLike<T>, cb: (item: T) => any, thisArg?: Object): void;