Freie Komponenten Utils

Im Controller Code der Freien Komponente steht direkt ein globales Symbol "FCUtils" zur Verfügung, welches Helfer-Utilities zum Vereinfachen immerwiederkehrender Probleme dient.
Nachfolgend eine Schnittstellenbeschreibung der FCUtils (Der Typ "CollectionLike" steht dabei stellvertretend für ein IList Objekt oder ein natives Array:
Schnittstellenberschreibung FCUtils
/**
* 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;
 
/**
* Version 4.7.5
*
* Returns the value of a style palette property
* 
* Example:
* var color = FCUtils.getStyleVar("primaryColor");
* 
* @param varName The name of the property
* @param defaultValue (optional) A value which will be returned if no property has been found or if the value of the property was empty for any reason
*/
getStyleVar( varName: string, defaultValue?: string ): string;