Namespace: CB_Arrays

CB_Arrays

Static class to manage arrays. It will return itself if it is tried to be instantiated.

Source:

Methods


<static> bsort(array [, reversed]) → {array}

Sorts an array using the bubble sort (sinking sort) method. Internally, it uses the ">" operator for comparing values as they will be treated as numbers.

Parameters:
Name Type Argument Default Description
array array

The array whose elements we want to sort.

reversed boolean <optional>
false

Defines whether to sort in the reverse order or not.

Source:
To Do:
  • Think about accepting a comparing function (as the "sort" method).
Returns:

Returns the array ordered. If another value which is not an array is given, it will be returned again.

Type
array

<static> combine( [arrayOrObjectA] [, arrayOrObjectB], avoidDuplicatedValuesInArray [, modifyArrayOrObjectA]) → {array|Object}

Returns a combined array or object from two arrays or objects. Using the following rules:


If they both are arrays (numeric indexes), it will keep all elements (attaching the elements of the second array after the elements of the first one).


Otherwise, if either of them is not an array (it should be an associative array which is an object in JavaScript), it will merge the elements (overwritting those whose index is the same and keeping the ones from the second array/object):

Parameters:
Name Type Argument Default Description
arrayOrObjectA array | Object | string | null | undefined <optional>
[]|{}

One of the arrays (numeric indexes) or associative arrays (object) that we want to combine. If a string is provided, it will try to convert it into a new object (the string should be a JSON-valid string). It can be optional if "arrayOrObjectB" is a valid value and neither null nor undefined. If not provided but the "arrayOrObjectB" is provided, it will be a new empty array if the "arrayOrObjectB" is an array or it will be an empty object otherwise.

arrayOrObjectB array | Object | string | null | undefined <optional>
[]|{}

One of the arrays (numeric indexes) or associative arrays (object) that we want to combine. If a string is provided, it will try to convert it into a new object (the string should be a JSON-valid string). It can be optional if "arrayOrObjectA" is a valid value and neither null nor undefined. If not provided but the "arrayOrObjectA" is provided, it will be a new empty array if the "arrayOrObjectA" is an array or it will be an empty object otherwise.

avoidDuplicatedValuesInArray boolean

Tells whether to avoid or allow items with duplicated values in the returned array or not. Only applies when both arrays to combine are numeric arrays.

modifyArrayOrObjectA boolean <optional>
false

Parameter that will be used in the case that CB_combineJSON or CB_combineArraysOrObjects is called. If set to true, it will modify the original "arrayOrObjectA" array or object.

Source:
Returns:
Type
array | Object

<static> copy(array) → {object}

Returns an array copied from the given one. It will also make a copy of the arrays found in the values (if any), calling itself recursively.

Parameters:
Name Type Description
array array

The array whose values we want to copy.

Source:
Returns:

Returns an array copied from the given one. Returns an empty array if the given "array" was not an array.

Type
object

<static> count()

Alias for CB_Arrays.sizeOf.

Source:
See:

<static> executeFunctionAll(array, functionEach [, delayBetweenEach] [, returnSetTimeoutsArray] [, delayBetweenEachAffectsFirst] [, functionFinish]) → {integer|array}

Performs a desired action, using the provided function, on all the existing elements of a given array. Elements which are undefined or null will be skipped without calling the "functionEach" function.

Parameters:
Name Type Argument Default Description
array array

A numeric array containing the elements that we want to loop.

functionEach CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK

Function that will be called for each element of the given array. As the first parameter it receives the element of the "array" provided being looped, as the second parameter the position of this element in the "array" provided, the third parameter is the array being looped and the fourth parameter will be the "delayBetweenEach" being used, being "this" the element itself.

delayBetweenEach number | CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK <optional>
0

If a value greater than zero is used, it will be used as the delay desired between each call to the "functionEach" function (calling them using the setTimeout function internally). If not provided or the value is 0 (zero) or lower, each call to the "functionEach" function will be performed immediately one after the other. If a function is provided, it will be called with the same parameters as the "functionEach" function and its returning value will be used as the delay (executed every loop for each item).

returnSetTimeoutsArray boolean <optional>
false

Defines whether we want the method to return an integer or a numeric array with information of each setTimeout call. Returning an array with information of each setTimeout call is only useful when the setTimeout function is called internally, which happens when the "delayBetweenEach" parameter is greater than 0 (zero).

delayBetweenEachAffectsFirst boolean <optional>
false

If set to true, the desired delay (if any) will also affect the first call to the "functionEach" function.

functionFinish CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK <optional>

Function that will be called for when it has finished looping all the items. The first parameter will be the array which was looped, the second parameter will be the number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null), and the third parameter will be the maximum "delay" used, being "this" the array itself.

Source:
Returns:

If the "returnSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed (which should be the same number as the elements given in the "array" parameter). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with a CB_Arrays.executeFunctionAll_OBJECT object for each element given. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the setTimeout function.

Type
integer | array

<static> forEach(array, callback [, thisArg] [, extendedDOM]) → {array|undefined}

Implementation of the Array.forEach method for browsers that do not support it natively.


Executes a function for each element of a given array.

Parameters:
Name Type Argument Default Description
array array

Desired array.

callback function

Function that will be executed for each element of the given array. Following the same rules as the native Array.forEach method, it will receive three arguments: currentValue, currentIndex and the array given.

thisArg * <optional>

Value that will be passed as "this" every time the function is called.

extendedDOM boolean <optional>
false

Defines whether the function is being called by a native function which was extended. Internal usage recommended only.

Source:
Returns:

If the "extendedDOM" parameter is set to false, returns the given "array" again. Otherwise, returns undefined.

Type
array | undefined

<static> indexOf(array, searchElement [, fromIndex] [, extendedDOM]) → {integer}

Implementation of Array.indexOf method for arrays in browsers that do not support it natively.


Returns the first index of a given element that exists in an array (starting from a certain index if desired) or -1 if not found.

Parameters:
Name Type Argument Default Description
array array

Desired array.

searchElement *

Element we want to search. Note that it is type sensitive.

fromIndex integer <optional>
0

First index of the given array where the search will start.

extendedDOM boolean <optional>
false

Defines whether the function is being called by a native function which was extended. Internal usage recommended only.

Source:
Returns:
Type
integer

<static> insert()

Source:
See:

<static> insertElement(array [, index], item [, onInsert]) → {array}

Inserts an element in the desired position of a given an array. Elements which are placed after it will be moved a position to the right (increasing their index).

Parameters:
Name Type Argument Default Description
array array

The array whose element we want to delete.

index integer <optional>
0

Position of the element in the given array that we want to remove.

item *

Element (item) which belongs to the index which is being checked in the current iteration of the given array.

onInsert CB_Arrays.removeDuplicated_PURGE_FUNCTION <optional>

Function to call if the element is inserted, after inserting it.

Source:
Returns:

Returns the new array (with the element inserted if it was possible). If no valid array is given, it will return an empty array.

Type
array

<static> insertElementByPosition()

Source:
See:

<static> isArray(element [, extendedDOM]) → {boolean}

Implementation of Array.isArray method for browsers that do not support it natively.


Returns whether a given element is an array or not.

Parameters:
Name Type Argument Default Description
element *

The element we want to check.

extendedDOM boolean <optional>
false

Defines whether the function is being called by a native function which was extended. Internal usage recommended only.

Source:
To Do:
  • Think about a parameter to check whether the given array is a typed array (for example, 'Uint8Array') or not.
Returns:
Type
boolean

<static> lastIndexOf(array, searchElement [, fromIndex] [, extendedDOM]) → {integer}

Implementation of Array.lastIndexOf method for browsers that do not support it natively.


Returns the last index of a given element that exists in an array (starting from a certain index if desired) or -1 if not found.

Parameters:
Name Type Argument Default Description
array array

Desired array.

searchElement *

Element we want to search. Note that it is type sensitive.

fromIndex integer <optional>
array.length - 1

First index of the given array where the search will start.

extendedDOM boolean <optional>
false

Defines whether the function is being called by a native function which was extended. Internal usage recommended only.

Source:
To Do:
  • Implement the "fromIndex" in the polyfill.
Returns:
Type
integer

<static> ltrim(element [, undesiredStrings]) → {string|array}

Trims the left side of a given string or array of strings (modifying the given array), taking off the desired strings or otherwise trimming spaces, tabs ("\t"), new lines ("\n") and carriage returns ("\r"). Case sensitive.

Parameters:
Name Type Argument Default Description
element string | array

The element that will be trimmed. It should be either a string or an array of strings.

undesiredStrings string | array <optional>
[ " ", "\n", "\r", "\t" ]

String or an array with the strings that we want to trim off the given element.

Source:
To Do:
  • Accept a "recursive" parameter (boolean) to affect multiple levels (array of arrays of strings, etc.).
  • Consider accepting objects instead of arrays in the "element" parameter.
  • Think about optimizing (using a counter for the number of occurrences in the loop and trim all the occurrences when finished).
Returns:

Returns the given element again if it was an string, a number (it will be casted to a string) or an array of strings, trimmed if it has been possible. If it was another type, returns an empty string.

Type
string | array

<static> removeDuplicated(array [, purgeFunction] [, ignoreDuplicated]) → {array}

Deletes duplicated and/or not desired values (with a checking function to purge) from a numeric array. Values can be of any type. Internally, loops through the given array backwards (from the last index to the first one).

Parameters:
Name Type Argument Default Description
array array

The array whose values we want to purge.

purgeFunction CB_Arrays.removeDuplicated_PURGE_FUNCTION <optional>

Callback that will be called for each item, being "this" the current item. It should return false when we want to keep the value or true otherwise. If the "ignoreDuplicated" parameter is set to true, all duplicated elements will be removed regardless of the returning value of the "purgeFunction" function.

ignoreDuplicated boolean <optional>
false

If it is set to true, it will keep duplicated values (unless the given "purgeFunction" purge them).

Source:
Returns:

Returns the array purged. If no valid array is given, it will return an empty array.

Type
array

<static> removeElement(array [, element] [, onRemove]) → {array}

Deletes a given element from an array. All occurrences will be deleted. Elements which were after a removed element will be moved a position to the left (decreasing their index).

Parameters:
Name Type Argument Description
array array

The array whose element we want to delete.

element * <optional>

The element we want to remove. All occurrences will be deleted. Note that it is type sensitive.

onRemove CB_Arrays.removeDuplicated_PURGE_FUNCTION <optional>

Function to call if the element is removed, before removing it.

Source:
Returns:

Returns the new array (with the element removed if it was possible). If no valid array is given, it will return an empty array.

Type
array

<static> removeElementByIndex()

Source:
See:

<static> removeElementByPosition(array [, index] [, onRemove]) → {array}

Deletes an element from an array which is placed in the desired position. Elements which were after it will be moved a position to the left (decreasing their index).

Parameters:
Name Type Argument Default Description
array array

The array whose element we want to delete.

index integer <optional>
0

Position of the element in the given array that we want to remove.

onRemove CB_Arrays.removeDuplicated_PURGE_FUNCTION <optional>

Function to call if the element is removed, before removing it.

Source:
Returns:

Returns the new array (with the element removed if it was possible). If no valid array is given, it will return an empty array.

Type
array

<static> removeElements(array, elements) → {array}

Deletes the given elements from an array. All occurrences will be deleted. Elements which were after a removed element will be moved a position to the left (decreasing their index).

Parameters:
Name Type Description
array array

The array whose element we want to delete.

elements array

An array with the elements we want to remove. All occurrences will be deleted. Note that it is type sensitive.

Source:
Returns:

Returns the new array (with the element removed if it was possible). If no valid array is given, it will return an empty array.

Type
array

<static> replaceAll(stringOrArray, stringOrArrayFind [, stringReplace] [, caseInsensitive]) → {string|array}

Returns the string or array of strings with all the desired occurrences replaced. Calls itself recursively and calls the CB_regularExpressionString function internally.

Parameters:
Name Type Argument Default Description
stringOrArray string | array

An string or an array of strings whose content we want to replace. It can also be an array of arrays of strings (as many levels as you wish). If an array is given, it will not be modified and a copy from it will be generated and returned with the occurrences replaced.

stringOrArrayFind string | array

An string or an array of strings (not a regular expressions) that we want to find to be replaced (special characters will be escaped).

stringReplace string <optional>
""

The string that will replace "stringFind". If not provided, it will be replaced as an empty string (it will just remove the occurrences found).

caseInsensitive boolean <optional>
false

Defines whether we want to be case insensitive or not.

Source:
Returns:

Returns the "stringOrArray" given with occurrences replaced. If the "stringOrArray" given was neither a string nor an array, it will be returned without being modified.

Type
string | array

<static> rtrim(element [, undesiredStrings]) → {string|array}

Trims the right side of a given string or array of strings (modifying the given array), taking off the desired strings or otherwise trimming spaces, tabs ("\t"), new lines ("\n") and carriage returns ("\r"). Case sensitive.

Parameters:
Name Type Argument Default Description
element string | array

The element that will be trimmed. It should be either a string or an array of strings.

undesiredStrings string | array <optional>
[ " ", "\n", "\r", "\t" ]

String or an array with the strings that we want to trim off the given element.

Source:
To Do:
  • Accept a "recursive" parameter (boolean) to affect multiple levels (array of arrays of strings, etc.).
  • Consider accepting objects instead of arrays in the "element" parameter.
  • Think about optimizing (using a counter for the number of occurrences in the loop and trim all the occurrences when finished).
Returns:

Returns the given element again if it was an string, a number (it will be casted to a string) or an array of strings, trimmed if it has been possible. If it was another type, returns an empty string.

Type
string | array

<static> sizeof()

Alias for CB_Arrays.sizeOf.

Source:
See:

<static> sizeOf(element [, onlyOwn]) → {integer}

Returns the size of an object or array.

Parameters:
Name Type Argument Default Description
element Object | array

The element whose size we want to know. It should be an object or an array.

onlyOwn boolean <optional>
false

If the "element" given is not an object, this parameter will be ignored. Otherwise, if it is set to true, it will only have into account the properties which the object has as their own property and have not been inherited (using the Object.hasOwnProperty method).

Source:
Returns:

If an object is provided, the size will be the number of its properties. Otherwise, if an array is given, the size will be the numbers of its indexes (Array.length property).

Type
integer

<static> sort(array [, reversed] [, comparingFunction]) → {array}

Sorts the values of an array (using the native Array.sort method).

Parameters:
Name Type Argument Default Description
array array

The array whose elements we want to sort.

reversed boolean <optional>
false

Defines whether to sort in the reverse order or not. Only applies when comparingFunction is not provided.

comparingFunction function <optional>

Comparing function with the same rules as the native Array.sort method. If provided, the "reversed" parameter will be ignored.

Source:
Returns:

Returns the array ordered. If another value which is not an array is given, it will be returned again.

Type
array

<static> trim(element [, undesiredStrings]) → {string|array}

Trims a given string or array of strings (modifying the given array), taking off the desired strings or otherwise trimming spaces, tabs ("\t"), new lines ("\n") and carriage returns ("\r"). Case sensitive.

Parameters:
Name Type Argument Default Description
element string | array

The element that will be trimmed. It should be either a string or an array of strings.

undesiredStrings string | array <optional>
[ " ", "\n", "\r", "\t" ]

String or an array with the strings that we want to trim off the given element.

Source:
To Do:
  • Accept a "recursive" parameter (boolean) to affect multiple levels (array of arrays of strings, etc.).
  • Consider accepting objects instead of arrays in the "element" parameter.
Returns:

Returns the given element again if it was an string, a number (it will be casted to a string) or an array of strings, trimmed if it has been possible. If it was another type, returns an empty string.

Type
string | array

executeAll()

Alias for CB_Arrays#executeFunctionAll.

Source:
See:
  • CB_Arrays#executeFunctionAll

forEachDelay()

Alias for CB_Arrays#executeFunctionAll.

Source:
See:
  • CB_Arrays#executeFunctionAll

Type Definitions


executeFunctionAll_OBJECT

Object used by the CB_Arrays#executeFunctionAll method when the "returnSetTimeoutsArray" parameter is set to true.

Type:
  • Object
Properties:
Name Type Description
item *

The element affected.

setTimeoutReturningValue integer

The returning value of calling the setTimeout internally or null if it was not called, depending on the "delayBetweenEach" parameter.

setTimeoutDelay number

The value used as the second parameter when calling the setTimeout internally or zero if it was not called, depending on the "delayBetweenEach" parameter.

Source:

executeFunctionAll_ON_FINISH_CALLBACK(array, itemsAffected, delayMaximum)

Callback that is used when finishes all iterations after looping the array. Being "this" the array itself.

Parameters:
Name Type Description
array array

Whole array which was being looped.

itemsAffected integer

The number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null).

delayMaximum integer

The maximum "delay" used.

Source:

executeFunctionAll_ON_LOOP_CALLBACK(item, index, array, delay) → {number}

Callback that is used for each iteration when looping the array. Being "this" the value itself.

Parameters:
Name Type Description
item *

Element (item) which belongs to the index which is being checked in the current iteration of the given array.

index integer

Index which is being checked in the current iteration.

array array

Whole array which is being looped.

delay integer

The "delayBetweenEach" used for this loop.

Source:
Returns:

When used as a function to calculate the delay, it should return the delay desired as a number.

Type
number

removeDuplicated_PURGE_FUNCTION(item, index, array) → {boolean}

Callback that is used as the "purgeFunction" parameter of the CB_Arrays.removeDuplicated function. Being "this" the current element (item). It should return false when we want to keep the value or true otherwise.

Parameters:
Name Type Description
item *

Element (item) which belongs to the index which is being checked in the current iteration used in CB_Arrays.removeDuplicated.

index integer

Index which is being checked in the current iteration used in CB_Arrays.removeDuplicated.

array array

Whole array which is being checked.

Source:
Returns:

It should return false when we want to keep the value or true otherwise.

Type
boolean