crossbrowdy
Version:
A Multimedia JavaScript framework to create real cross-platform and hybrid game engines, games, emulators, multimedia libraries and apps.
939 lines (804 loc) • 97.6 kB
HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>CrossBrowdy API documentation [printable] Source: CrossBase/general/CB_data.js</title>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/sunlight.default.css">
<link type="text/css" rel="stylesheet" href="styles/site.yeti.css">
</head>
<body style="min-width:800px; overflow-wrap:break-word; word-wrap:break-word; word-break:break-word; line-break:strict; hyphens:none; -webkit-hyphens:none; -moz-hyphens:none;">
<div class="navbar navbar-default navbar-fixed-top ">
<div class="container">
<div class="navbar-header">
<a class="navbar-brand" href="index.html">CrossBrowdy API documentation [printable]</a>
<button class="navbar-toggle" type="button" data-toggle="collapse" data-target="#topNavigation">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<div class="navbar-collapse collapse" id="topNavigation">
<ul class="nav navbar-nav">
<li class="dropdown">
<a href="namespaces.list.html" class="dropdown-toggle" data-toggle="dropdown">Namespaces<b class="caret"></b></a>
<ul class="dropdown-menu inline">
<li><a href="CB_Arrays.html">CB_Arrays</a></li><li><a href="CB_AudioDetector.html">CB_AudioDetector</a></li><li><a href="CB_Client.html">CB_Client</a></li><li><a href="CB_Collisions.html">CB_Collisions</a></li><li><a href="CB_Configuration.html">CB_Configuration</a></li><li><a href="CB_Configuration.CrossBase.html">CB_Configuration.CrossBase</a></li><li><a href="CB_Configuration.CrossBrowdy.html">CB_Configuration.CrossBrowdy</a></li><li><a href="CB_Controllers.html">CB_Controllers</a></li><li><a href="CB_Controllers_Proprietary.html">CB_Controllers_Proprietary</a></li><li><a href="CB_Controllers_Proprietary.WII.html">CB_Controllers_Proprietary.WII</a></li><li><a href="CB_Controllers_Proprietary.WII_U.html">CB_Controllers_Proprietary.WII_U</a></li><li><a href="CB_Device.html">CB_Device</a></li><li><a href="CB_Device.AmbientLight.html">CB_Device.AmbientLight</a></li><li><a href="CB_Device.Battery.html">CB_Device.Battery</a></li><li><a href="CB_Device.Location.html">CB_Device.Location</a></li><li><a href="CB_Device.Motion.html">CB_Device.Motion</a></li><li><a href="CB_Device.Orientation.html">CB_Device.Orientation</a></li><li><a href="CB_Device.Proximity.html">CB_Device.Proximity</a></li><li><a href="CB_Device.Vibration.html">CB_Device.Vibration</a></li><li><a href="CB_Elements.html">CB_Elements</a></li><li><a href="CB_Events.html">CB_Events</a></li><li><a href="CB_Keyboard.html">CB_Keyboard</a></li><li><a href="CB_Keyboard.chars.html">CB_Keyboard.chars</a></li><li><a href="CB_Keyboard.extended.html">CB_Keyboard.extended</a></li><li><a href="CB_Keyboard.keys.html">CB_Keyboard.keys</a></li><li><a href="CB_Modules.html">CB_Modules</a></li><li><a href="CB_Mouse.html">CB_Mouse</a></li><li><a href="CB_Mouse.CursorImage.html">CB_Mouse.CursorImage</a></li><li><a href="CB_Net.html">CB_Net</a></li><li><a href="CB_Net.Fetch.html">CB_Net.Fetch</a></li><li><a href="CB_Net.REST.html">CB_Net.REST</a></li><li><a href="CB_Net.Sockets.html">CB_Net.Sockets</a></li><li><a href="CB_Net.Sockets.SockJS.html">CB_Net.Sockets.SockJS</a></li><li><a href="CB_Net.XHR.html">CB_Net.XHR</a></li><li><a href="CB_Pointer.html">CB_Pointer</a></li><li><a href="CB_Screen.html">CB_Screen</a></li><li><a href="CB_Speaker.html">CB_Speaker</a></li><li><a href="CB_Touch.html">CB_Touch</a></li><li><a href="CB_baseSymbols.html">CB_baseSymbols</a></li>
</ul>
</li>
<li class="dropdown">
<a href="classes.list.html" class="dropdown-toggle" data-toggle="dropdown">Classes<b class="caret"></b></a>
<ul class="dropdown-menu inline">
<li><a href="CB_AudioFile.html">CB_AudioFile</a></li><li><a href="CB_AudioFileCache.html">CB_AudioFileCache</a></li><li><a href="CB_AudioFileSprites.html">CB_AudioFileSprites</a></li><li><a href="CB_AudioFileSpritesPool.html">CB_AudioFileSpritesPool</a></li><li><a href="CB_AudioFile_API.AAPI.html">CB_AudioFile_API.AAPI</a></li><li><a href="CB_AudioFile_API.ACMP.html">CB_AudioFile_API.ACMP</a></li><li><a href="CB_AudioFile_API.SM2.html">CB_AudioFile_API.SM2</a></li><li><a href="CB_AudioFile_API.WAAPI.html">CB_AudioFile_API.WAAPI</a></li><li><a href="CB_Canvas.html">CB_Canvas</a></li><li><a href="CB_GraphicSprites.html">CB_GraphicSprites</a></li><li><a href="CB_GraphicSpritesScene.html">CB_GraphicSpritesScene</a></li>
</ul>
</li>
<li class="dropdown">
<a href="global.html" class="dropdown-toggle" data-toggle="dropdown">Global<b class="caret"></b></a>
<ul class="dropdown-menu inline">
<li><a href="global.html#CB_BASE_NAME">CB_BASE_NAME</a></li><li><a href="global.html#CB_CREDITS_DEFAULT">CB_CREDITS_DEFAULT</a></li><li><a href="global.html#CB_NAME">CB_NAME</a></li><li><a href="global.html#CB_OPTIONS">CB_OPTIONS</a></li><li><a href="global.html#CB_VERSION">CB_VERSION</a></li><li><a href="global.html#CB_addCredits">CB_addCredits</a></li><li><a href="global.html#CB_baseToBase">CB_baseToBase</a></li><li><a href="global.html#CB_baseToInt">CB_baseToInt</a></li><li><a href="global.html#CB_br2nl">CB_br2nl</a></li><li><a href="global.html#CB_brToNl">CB_brToNl</a></li><li><a href="global.html#CB_combineArraysOrObjects">CB_combineArraysOrObjects</a></li><li><a href="global.html#CB_combineAutomatically">CB_combineAutomatically</a></li><li><a href="global.html#CB_combineJSON">CB_combineJSON</a></li><li><a href="global.html#CB_combineURIParameters">CB_combineURIParameters</a></li><li><a href="global.html#CB_combineURLParameters">CB_combineURLParameters</a></li><li><a href="global.html#CB_console">CB_console</a></li><li><a href="global.html#CB_copyObject">CB_copyObject</a></li><li><a href="global.html#CB_countDecimalDigits">CB_countDecimalDigits</a></li><li><a href="global.html#CB_countDecimalPart">CB_countDecimalPart</a></li><li><a href="global.html#CB_countDecimals">CB_countDecimals</a></li><li><a href="global.html#CB_countIntegerDigits">CB_countIntegerDigits</a></li><li><a href="global.html#CB_countIntegerPart">CB_countIntegerPart</a></li><li><a href="global.html#CB_credits">CB_credits</a></li><li><a href="global.html#CB_forEach">CB_forEach</a></li><li><a href="global.html#CB_forceString">CB_forceString</a></li><li><a href="global.html#CB_getBase64StringObject">CB_getBase64StringObject</a></li><li><a href="global.html#CB_getCookie">CB_getCookie</a></li><li><a href="global.html#CB_getDatum">CB_getDatum</a></li><li><a href="global.html#CB_getJSONPropertyValue">CB_getJSONPropertyValue</a></li><li><a href="global.html#CB_getLZStringObject">CB_getLZStringObject</a></li><li><a href="global.html#CB_getValueIndex">CB_getValueIndex</a></li><li><a href="global.html#CB_getValuePath">CB_getValuePath</a></li><li><a href="global.html#CB_includeJSFile">CB_includeJSFile</a></li><li><a href="global.html#CB_indexOf">CB_indexOf</a></li><li><a href="global.html#CB_init">CB_init</a></li><li><a href="global.html#CB_intToBase">CB_intToBase</a></li><li><a href="global.html#CB_isArray">CB_isArray</a></li><li><a href="global.html#CB_isEmail">CB_isEmail</a></li><li><a href="global.html#CB_isFileLocal">CB_isFileLocal</a></li><li><a href="global.html#CB_isString">CB_isString</a></li><li><a href="global.html#CB_lastIndexOf">CB_lastIndexOf</a></li><li><a href="global.html#CB_ltrim">CB_ltrim</a></li><li><a href="global.html#CB_nl2br">CB_nl2br</a></li><li><a href="global.html#CB_nlToBr">CB_nlToBr</a></li><li><a href="global.html#CB_numberFormat">CB_numberFormat</a></li><li><a href="global.html#CB_numberOfDecimalDigits">CB_numberOfDecimalDigits</a></li><li><a href="global.html#CB_numberOfDecimals">CB_numberOfDecimals</a></li><li><a href="global.html#CB_numberOfIntegerDigits">CB_numberOfIntegerDigits</a></li><li><a href="global.html#CB_parseJSON">CB_parseJSON</a></li><li><a href="global.html#CB_parseString">CB_parseString</a></li><li><a href="global.html#CB_regularExpressionString">CB_regularExpressionString</a></li><li><a href="global.html#CB_renderString">CB_renderString</a></li><li><a href="global.html#CB_replaceAll">CB_replaceAll</a></li><li><a href="global.html#CB_rtrim">CB_rtrim</a></li><li><a href="global.html#CB_scriptPath">CB_scriptPath</a></li><li><a href="global.html#CB_scriptPathCalculate">CB_scriptPathCalculate</a></li><li><a href="global.html#CB_setCookie">CB_setCookie</a></li><li><a href="global.html#CB_setDatum">CB_setDatum</a></li><li><a href="global.html#CB_sizeOf">CB_sizeOf</a></li><li><a href="global.html#CB_sizeof">CB_sizeof</a></li><li><a href="global.html#CB_stringifyJSON">CB_stringifyJSON</a></li><li><a href="global.html#CB_symmetricCall">CB_symmetricCall</a></li><li><a href="global.html#CB_symmetricCallClear">CB_symmetricCallClear</a></li><li><a href="global.html#CB_this">CB_this</a></li><li><a href="global.html#CB_trim">CB_trim</a></li>
</ul>
</li>
</ul>
<div class="col-sm-3 col-md-3">
<form class="navbar-form" role="search">
<div class="input-group">
<input type="text" class="form-control" placeholder="Search" name="q" id="search-input">
<div class="input-group-btn">
<button class="btn btn-default" id="search-submit"><i class="glyphicon glyphicon-search"></i></button>
</div>
</div>
</form>
</div>
</div>
</div>
</div>
<div class="container" id="toc-content" style="width:100%;">
<div class="row" style="width:100%;">
<div class="col-md-12">
<div id="main">
<h1 class="page-title">Source: CrossBase/general/CB_data.js</h1>
<section>
<article>
<pre
class="sunlight-highlight-javascript linenums">/**
* @file Data and related management.
* @author Joan Alba Maldonado <workindalian@gmail.com>
* @license Creative Commons Attribution 4.0 International. See more at {@link https://crossbrowdy.com/about#what_is_the_crossbrowdy_copyright_and_license}.
* @todo A function equivalent to htmlentities/htmlspecialchars (as in PHP).
*/
//If we want to extend the DOM, we do it:
if (CB_Configuration[CB_BASE_NAME].EXTEND_DOM)
{
try
{
if (!Array.prototype.indexOf) { Array.prototype.indexOf = function(searchElement, fromIndex) { CB_indexOf(this, searchElement, fromIndex, true); } }
if (!Array.prototype.lastIndexOf) { Array.prototype.lastIndexOf = function(searchElement, fromIndex) { CB_lastIndexOf(this, searchElement, fromIndex, true); } }
if (!Array.isArray) { Array.isArray = function() { return CB_isArray(this, true); } } //isArray is a method which is not in the prototype.
//if (!Array.prototype.isArray) { Array.prototype.isArray = function() { return CB_isArray(this, true); } }
if (!Array.prototype.forEach) { Array.prototype.forEach = function(callback, thisArg) { CB_forEach(this, callback, thisArg, true); } }
if (!NodeList.prototype.forEach) { NodeList.prototype.forEach = Array.prototype.forEach; }
if (!HTMLCollection.prototype.forEach) { HTMLCollection.prototype.forEach = Array.prototype.forEach; }
} catch(E) {}
}
/**
* Implementation of [Array.lastIndexOf]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf} method for browsers that do not support it natively.
<br>
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.
* @function
* @param {array} array - Desired array.
* @param {*} searchElement - Element we want to search. Note that it is type sensitive.
* @param {integer} [fromIndex=array.length - 1] - First index of the given array where the search will start.
* @param {boolean} [extendedDOM=false] - Defines whether the function is being called by a native function which was extended. Internal usage recommended only.
* @returns {integer}
* @todo Implement the "fromIndex" in the polyfill.
*/
//* Polyfill source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf
function CB_lastIndexOf(array, searchElement, fromIndex, extendedDOM)
{
'use strict';
if (!extendedDOM)
{
if (array && array.lastIndexOf) { return array.lastIndexOf.call(array, searchElement, fromIndex || array.length); } //It can be a string.
if (Array.prototype.lastIndexOf) { return Array.prototype.lastIndexOf.call(array, searchElement, fromIndex || array.length); }
}
if (typeof(array) === "undefined" || array === null) { throw new TypeError(); }
var n, k,
t = Object(array),
len = t.length >>> 0;
if (len === 0) { return -1; }
n = len - 1;
if (arguments.length > 2 && typeof(arguments[2]) !== "undefined" && arguments[2] !== null && !isNaN(arguments[2]))
{
n = Number(arguments[2]);
if (n != n) { n = 0; }
//if (n != n) { n = len - 1; }
else if (n != 0 && n != (1 / 0) && n != -(1 / 0))
{
n = (n > 0 || -1) * Math.floor(Math.abs(n));
}
}
for (k = n >= 0 ? Math.min(n, len - 1) : len - Math.abs(n); k >= 0; k--)
{
if (k in t && t[k] === searchElement) { return k; }
}
return -1;
}
/**
* Implementation of [Array.indexOf]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf} method for arrays in browsers that do not support it natively.
<br>
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.
* @function
* @param {array} array - Desired array.
* @param {*} searchElement - Element we want to search. Note that it is type sensitive.
* @param {integer} [fromIndex=0] - First index of the given array where the search will start.
* @param {boolean} [extendedDOM=false] - Defines whether the function is being called by a native function which was extended. Internal usage recommended only.
* @returns {integer}
*/
//* Polyfill source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf
function CB_indexOf(array, searchElement, fromIndex, extendedDOM)
{
if (!extendedDOM)
{
if (array && array.indexOf) { return array.indexOf.call(array, searchElement, fromIndex); } //It can be a string.
if (Array.prototype.indexOf) { return Array.prototype.indexOf.call(array, searchElement, fromIndex); }
}
if (typeof(array) === "undefined" || array === null)
{
throw new TypeError( '"array" is null or not defined' );
}
var length = array.length >>> 0; // Hack to convert object.length to a UInt32
fromIndex = +fromIndex || 0;
if (Math.abs(fromIndex) === Infinity) { fromIndex = 0; }
if (fromIndex < 0)
{
fromIndex += length;
if (fromIndex < 0) { fromIndex = 0; }
}
for (;fromIndex < length; fromIndex++)
{
if (array[fromIndex] === searchElement)
{
return fromIndex;
}
}
return -1;
}
/**
* Implementation of the [Array.forEach]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach} method for browsers that do not support it natively.
<br>
Executes a function for each element of a given array.
* @function
* @param {array} array - Desired array.
* @param {function} callback - Function that will be executed for each element of the given array. Following the same rules as the native [Array.forEach]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach} method, it will receive three arguments: currentValue, currentIndex and the array given.
* @param {*} [thisArg] - Value that will be passed as "this" every time the function is called.
* @param {boolean} [extendedDOM=false] - Defines whether the function is being called by a native function which was extended. Internal usage recommended only.
* @returns {array|undefined} If the "extendedDOM" parameter is set to false, returns the given "array" again. Otherwise, returns undefined.
*/
//* Polyfill source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach
function CB_forEach(array, callback, thisArg, extendedDOM)
{
"use strict";
if (!extendedDOM)
{
if (array.forEach) { array.forEach.call(array, callback, thisArg); return array; }
else if (Array.prototype.forEach) { Array.prototype.forEach.call(array, callback, thisArg); return array; }
}
if (array === void 0 || array === null) { throw new TypeError(); }
if (typeof callback !== "function") { throw new TypeError(); }
var t = Object(array);
var len = t.length >>> 0;
//thisArg = arguments.length >= 2 ? arguments[1] : void 0;
for (var i = 0; i < len; i++)
{
if (i in t) { callback.call(thisArg, t[i], i, t); }
}
return extendedDOM ? undefined : array;
}
/**
* Implementation of [Array.isArray]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray} method for browsers that do not support it natively.
<br>
Returns whether a given element is an array or not.
* @function
* @param {*} element - The element we want to check.
* @param {boolean} [extendedDOM=false] - Defines whether the function is being called by a native function which was extended. Internal usage recommended only.
* @returns {boolean}
* @todo Think about a parameter to check whether the given array is a typed array (for example, 'Uint8Array') or not.
*/
function CB_isArray(element, extendedDOM)
{
if (typeof(element) === "undefined" || element === null) { return false; }
var isArray = false;
if (Array)
{
if (Array.isArray && !extendedDOM)
{
isArray = Array.isArray(element);
}
else
{
isArray = element instanceof Array;
if (!isArray) //It could still be an Array from another frame.
{
isArray = (Object.prototype.toString.call(element) === '[object Array]');
}
}
}
return isArray;
}
/**
* Alias for {@link CB_sizeOf}.
* @function CB_sizeof
* @see {@link CB_sizeOf}
*/
/**
* Returns the size of an object or array.
* @function
* @param {Object|array} element - The element whose size we want to know. It should be an object or an array.
* @param {boolean} [onlyOwn=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]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty} method).
* @returns {integer} 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]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length} property).
*/
function CB_sizeOf(object, onlyOwn)
{
var size = 0;
if (CB_isArray(object) && typeof(object.length) !== "undefined" && object.length !== null && !isNaN(object.length) && object.length > 0) { return object.length; }
for (var key in object)
{
if (!onlyOwn || object.hasOwnProperty(key)) { size++; }
}
return size;
}
var CB_sizeof = CB_sizeOf; //Alias for the function.
/**
* Returns whether a given element is a string or not.
* @function
* @param {*} element - The element we want to check.
* @returns {boolean}
*/
function CB_isString(element)
{
return (typeof(element) === "string" || element instanceof String);
}
/**
* Returns back the given element if it is a string or an empty string otherwise.
* @function
* @param {*} element - The element that will be checked.
* @returns {string}
*/
function CB_forceString(element)
{
if (!CB_isString(element)) { return ""; }
else { return element; }
}
/**
* Returns back the given element as a string if it could be parsed or an empty string otherwise.
* @function
* @param {*} element - The element that will be checked.
* @returns {string}
*/
function CB_parseString(element)
{
if (typeof(element) === "undefined" || element === null || element === true || element === false || !CB_isString(element) && isNaN(element)) { return ""; }
else { return element + ""; }
}
/**
* 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.
* @function
* @param {string|array} element - The element that will be trimmed. It should be either a string or an array of strings.
* @param {string|array} [undesiredStrings=[ " ", "\n", "\r", "\t" ]] - String or an array with the strings that we want to trim off the given element.
* @returns {string|array} 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.
* @todo Accept a "recursive" parameter (boolean) to affect multiple levels (array of arrays of strings, etc.).
* @todo Consider accepting objects instead of arrays in the "element" parameter.
*/
function CB_trim(element, undesiredStrings)
{
if (CB_isArray(element))
{
for (var x = 0, elementLength = element.length; x < elementLength; x++)
{
element[x] = CB_trim(element[x], undesiredStrings);
}
return element;
}
//else if (typeof(element) !== "undefined" && element !== null && !isNaN(element)) { return element; }
else if (typeof(element) === "undefined" || element === null) { return ""; }
else if (element === true || element === false) { return ""; }
else if (!isNaN(element)) { element = element + ""; }
else if (!CB_isString(element)) { return ""; }
else if (typeof(element.trim) === "function")
{
//Only calls the native function when the "undesiredStringFound" parameter is the default one (it will not just trim blank spaces but also "\r", "\n"...):
if (!CB_isArray(undesiredStrings) && !CB_isString(undesiredStrings))
{
return element.trim();
}
}
//return element.replace(/^\s+|\s+$/g, "");
element = CB_rtrim(element, undesiredStrings);
element = CB_ltrim(element, undesiredStrings);
return element;
}
/**
* 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.
* @function
* @param {string|array} element - The element that will be trimmed. It should be either a string or an array of strings.
* @param {string|array} [undesiredStrings=[ " ", "\n", "\r", "\t" ]] - String or an array with the strings that we want to trim off the given element.
* @returns {string|array} 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.
* @todo Accept a "recursive" parameter (boolean) to affect multiple levels (array of arrays of strings, etc.).
* @todo Consider accepting objects instead of arrays in the "element" parameter.
* @todo Think about optimizing (using a counter for the number of occurrences in the loop and trim all the occurrences when finished).
*/
function CB_rtrim(element, undesiredStrings)
{
if (CB_isArray(element))
{
for (var x = 0, elementLength = element.length; x < elementLength; x++)
{
element[x] = CB_rtrim(element[x], undesiredStrings);
}
return element;
}
//else if (typeof(element) !== "undefined" && element !== null && !isNaN(element)) { return element; }
else if (typeof(element) === "undefined" || element === null) { return ""; }
else if (element === true || element === false) { return ""; }
else if (!isNaN(element)) { element = element + ""; }
else if (!CB_isString(element)) { return ""; }
if (CB_isString(undesiredStrings)) { undesiredStrings = [ undesiredStrings ]; }
else if (!CB_isArray(undesiredStrings))
{
undesiredStrings = [ " ", "\n", "\r", "\t" ];
//Only calls the native function when the "undesiredStringFound" parameter is the default one (it will not just trim blank spaces but also "\r", "\n"...):
if (typeof(element.trimEnd) === "function") { return element.trimEnd(); }
}
//Loops through the undesired strings:
var undesiredStringsLength = undesiredStrings.length;
var undesiredStringFound = false;
for (var x = 0; x < undesiredStringsLength; x++)
{
//Trims undesired string at the end:
while (element.substring(element.length - undesiredStrings[x].length, element.length) === undesiredStrings[x])
{
element = element.substring(0, element.length - undesiredStrings[x].length);
undesiredStringFound = true;
}
//If an undesired string has been found, we are looking for more than one undesired strings and the loop is at the end, starts the loop again:
if (undesiredStringFound && undesiredStringsLength > 1 && x + 1 === undesiredStringsLength) { undesiredStringFound = false; x = -1; }
}
return element;
}
/**
* 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.
* @function
* @param {string|array} element - The element that will be trimmed. It should be either a string or an array of strings.
* @param {string|array} [undesiredStrings=[ " ", "\n", "\r", "\t" ]] - String or an array with the strings that we want to trim off the given element.
* @returns {string|array} 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.
* @todo Accept a "recursive" parameter (boolean) to affect multiple levels (array of arrays of strings, etc.).
* @todo Consider accepting objects instead of arrays in the "element" parameter.
* @todo Think about optimizing (using a counter for the number of occurrences in the loop and trim all the occurrences when finished).
*/
function CB_ltrim(element, undesiredStrings)
{
if (CB_isArray(element))
{
for (var x = 0, elementLength = element.length; x < elementLength; x++)
{
element[x] = CB_ltrim(element[x], undesiredStrings);
}
return element;
}
//else if (typeof(element) !== "undefined" && element !== null && !isNaN(element)) { return element; }
else if (typeof(element) === "undefined" || element === null) { return ""; }
else if (element === true || element === false) { return ""; }
else if (!isNaN(element)) { element = element + ""; }
else if (!CB_isString(element)) { return ""; }
if (CB_isString(undesiredStrings)) { undesiredStrings = [ undesiredStrings ]; }
else if (!CB_isArray(undesiredStrings))
{
undesiredStrings = [ " ", "\n", "\r", "\t" ];
//Only calls the native function when the "undesiredStringFound" parameter is the default one (it will not just trim blank spaces but also "\r", "\n"...):
if (typeof(element.trimStart) === "function") { return element.trimStart(); }
}
//Loops through the undesired strings:
var undesiredStringsLength = undesiredStrings.length;
var undesiredStringFound = false;
for (var x = 0; x < undesiredStringsLength; x++)
{
//Trims undesired string at the beginning:
while (element.substring(0, undesiredStrings[x].length) === undesiredStrings[x])
{
element = element.substring(undesiredStrings[x].length, element.length);
undesiredStringFound = true;
}
//If an undesired string has been found, we are looking for more than one undesired strings and the loop is at the end, starts the loop again:
if (undesiredStringFound && undesiredStringsLength > 1 && x + 1 === undesiredStringsLength) { undesiredStringFound = false; x = -1; }
}
return element;
}
/**
* Alias for {@link CB_nl2br}.
* @function CB_nlToBr
* @see {@link CB_nl2br}
*/
/**
* Changes new lines (\n) for &lt;br /&gt;'s in a given string.
* @function
* @param {string} string - The string we want to modify.
* @returns {string} Returns the string with all the occurrences replaced or an empty string if the element given was not a string.
*/
function CB_nl2br(string)
{
//If it is not a string, uses an empty string instead:
if (!CB_isString(string)) { string = ""; }
//Parses the variable to string type:
string = string.toString();
string = string.replace(/\n/gi, "<br />");
return string;
}
var CB_nlToBr = CB_nl2br; //Alias for the function.
/**
* Alias for {@link CB_br2nl}.
* @function CB_brToNl
* @see {@link CB_br2nl}
*/
/**
* Changes &lt;br /&gt;'s, &lt;br/&gt;'s and &lt;br&gt;'s for new lines (\n) in a given string.
* @function
* @param {string} string - The string we want to modify.
* @returns {string} Returns the string with all the occurrences replaced or an empty string if the element given was not a string.
*/
function CB_br2nl(string)
{
//If it is not a string, uses an empty string instead:
if (!CB_isString(string)) { string = ""; }
//Parses the variable to string type:
string = string.toString();
string = string.replace(/<br \/>/gi, "\n");
string = string.replace(/<br\/>/gi, "\n");
string = string.replace(/<br>/gi, "\n");
return string;
}
var CB_brToNl = CB_br2nl; //Alias for the function.
/**
* Tries to guess whether a given file path (absolute or relative) is a local address or not. It will be assumed as local if the path
uses the "file:" protocol or the current script is running locally and the path does not use the "http:", "https:" or "ftp:" protocols.
* @function
* @param {string} filePath - The file path we want to check.
* @returns {boolean} Returns whether the given file path is a local address or not.
*/
function CB_isFileLocal(filePath)
{
var isFileLocal = false;
filePath = CB_trim(filePath);
if (filePath !== "")
{
if (filePath.substring(0, 5) === "file:" || CB_Client.isRunningLocally() && filePath.substring(0, 5) !== "http:" && filePath.substring(0, 6) !== "https:" && filePath.substring(0, 4) !== "ftp:")
{
isFileLocal = true;
}
}
return isFileLocal;
}
/**
* Processes a given string as a template and returns it rendered (if possible) with the values of the given JSON object.
Tries to use [Handlebars]{@link https://handlebarsjs.com/} as the first choice but if is is not available it will just replace all occurrences with
vanilla JavaScript.
* @function
* @param {string} str - The string we want to render.
* @param {Object} [JSONObject=CB_JSONData] - The JSON object which contains the values. If not provided, it will try to use the global CB_JSONData object in the case it exists.
* @param {boolean} [forceVanilla=false] - Forces vanilla JavaScript rendering instead of using [Handlebars]{@link https://handlebarsjs.com/}.
* @param {integer} [depthLevelMax=10] - Maximum depth level allowed to read the object to render the string. Only applies when it is rendered by vanilla JavaScript. For performance purposes.
* @returns {str}
*/
function CB_renderString(string, JSONObject, forceVanilla, depthLevelMax)
{
string = CB_trim(string);
//If a JSON object is not given, uses the default one (if any):
if (typeof(JSONObject) === "undefined" || JSONObject === null)
{
if (typeof(CB_JSONData) !== "undefined" && CB_JSONData !== null) { JSONObject = CB_JSONData; }
}
//If we do not want vanilla JavaScript rendering and Handlebars is present, uses it:
if (!forceVanilla && typeof(Handlebars) !== "undefined" && Handlebars !== null && typeof(Handlebars.compile) === "function")
{
//Returns the template rendered:
return Handlebars.compile(string)(JSONObject); //Using Handlebars.
}
//...otherwise, just replaces all occurrences in the given string:
else
{
return CB_renderStringRecursively(string, JSONObject, false, depthLevelMax);
}
}
//Renders a given string recursively with the given object and the given max level:
function CB_renderStringRecursively(string, desiredObject, avoidRecursive, depthLevelMax, levelCurrent, pathCurrent)
{
if (typeof(desiredObject) === "undefined" || desiredObject === null) { return string; }
if (typeof(depthLevelMax) === "undefined" || depthLevelMax === null || isNaN(depthLevelMax)) { depthLevelMax = 10; }
if (typeof(levelCurrent) === "undefined" || levelCurrent === null || isNaN(levelCurrent)) { levelCurrent = 0; }
if (typeof(pathCurrent) === "undefined" || pathCurrent === null) { pathCurrent = ""; }
if (pathCurrent.substring(0, 1) === ".") { pathCurrent = pathCurrent.substring(1); }
for (var property in desiredObject)
{
if (CB_sizeof(desiredObject[property]) === 0 || CB_isString(desiredObject[property]))
{
string = string.replace(CB_regularExpressionString("{{" + pathCurrent + (pathCurrent === "" ? "" : ".") + property + "}}", true, false), desiredObject[property]);
}
else if (!avoidRecursive && levelCurrent < depthLevelMax)
{
string = CB_renderStringRecursively(string, desiredObject[property], avoidRecursive, depthLevelMax, ++levelCurrent, pathCurrent + "." + property);
string = string.replace(CB_regularExpressionString("{{" + pathCurrent + (pathCurrent === "" ? "" : ".") + property + "}}", true, false), ""); //In the case is has not been found, clears it.
}
}
return string;
}
/**
* Tells whether a given email is valid or not. Not really precise.
* @function
* @param {string} email - Possible email that we want to validate.
* @returns {boolean}
*/
//* Source: steve @ http://stackoverflow.com/questions/46155/validate-email-address-in-javascript
function CB_isEmail(email)
{
return (CB_isString(email) && email.indexOf("..") === -1 && /^((([a-z]|\d|[!#\$%&'\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+(\.([a-z]|\d|[!#\$%&'\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+)*)|((\x22)((((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(([\x01-\x08\x0b\x0c\x0e-\x1f\x7f]|\x21|[\x23-\x5b]|[\x5d-\x7e]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(\\([\x01-\x09\x0b\x0c\x0d-\x7f]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF]))))*(((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(\x22)))@((([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.)+(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))$/i.test(email));
}
/**
* Returns the given number with the desired decimals and make it a string if we want to (so it will be able to have trailing zeros). Uses decimal numeral system only. It will perform ceiling round automatically if needed.
* @function
* @param {integer|float|string} number - The number that we want to format. It can be a string.
* @param {integer} [decimals=2] - The number of decimals we want to allow.
* @param {boolean} [stringify=false] - Set to true if we want it to return a string (filled with trailing zeros to reach the desired number of decimals).
* @returns {integer|float|string} Returns zero in the case a non-valid number has been provided.
* @todo Allow to define a minimum length for the integer part of the "number" parameter, so it will fill with leading zeros if needed (when "stringify" is set to true). Think about allowing to define a maximum too.
*/
function CB_numberFormat(number, decimals, stringify)
{
number = parseFloat(number);
if (isNaN(number)) { return 0; }
decimals = parseInt(decimals);
if (isNaN(decimals) || decimals < 0) { decimals = 2; }
number *= Math.pow(10, decimals);
number = parseInt(number + 0.5); //Ceil round.
number /= Math.pow(10, decimals);
if (stringify)
{
number = number + "";
//if (number.indexOf(".") === -1) { number += ".00"; }
//else if (number.substring(number.indexOf(".") + 1).length === 1) { number += "0"; }
if (decimals >= 1 && number.indexOf(".") === -1) { number += "."; }
while (number.substring(number.indexOf(".") + 1).length < decimals)
{
number += "0";
}
}
return number;
}
/**
* Alias for {@link CB_countDecimalPart}.
* @function CB_countDecimals
* @see {@link CB_countDecimalPart}
*/
/**
* Alias for {@link CB_countDecimalPart}.
* @function CB_countDecimalDigits
* @see {@link CB_countDecimalPart}
*/
/**
* Alias for {@link CB_countDecimalPart}.
* @function CB_numberOfDecimals
* @see {@link CB_countDecimalPart}
*/
/**
* Alias for {@link CB_countDecimalPart}.
* @function CB_numberOfDecimalDigits
* @see {@link CB_countDecimalPart}
*/
/**
* Returns the number of decimals of the given number. It also works with numbers in exponential notation (as for example '1e-13' which would be 0.0000000000001).
* @function
* @param {integer|float|string} number - The number whose decimals we want to count. It can be a string.
* @returns {integer} Returns zero in the case a non-valid number has been provided. Otherwise, it returns the number of decimals counted.
*/
var CB_countDecimalPart = CB_countDecimalDigits = CB_countDecimals = CB_numberOfDecimals = CB_numberOfDecimalDigits = function(number)
{
number = parseFloat(number);
if (isNaN(number)) { return 0; }
number = Math.abs(number);
if (number % 1 === 0) { return 0; }
//First it tries "fastest" way (it does not work for numbers in exponential notation):
var decimals = (number + "").split(".");
decimals = (typeof(decimals[1]) !== "undefined") ? decimals[1].length : 0;
if (decimals > 0) { return decimals; }
//For float numbers that are represented in exponential notation (like '1e-13', for example):
decimals = 0;
var numberMultiplied = 0;
while ((numberMultiplied = number * Math.pow(10, ++decimals)) % 1 !== 0);
return decimals;
}
/**
* Alias for {@link CB_countIntegerPart}.
* @function CB_numberOfIntegerDigits
* @see {@link CB_countIntegerPart}
*/
/**
* Alias for {@link CB_countIntegerPart}.
* @function CB_countIntegerDigits
* @see {@link CB_countIntegerPart}
*/
/**
* Returns the number of integer digits (the number of digits that belong to the integer part) of the given number. It also works with numbers in exponential notation (as for example '1e-13' which would be 0.0000000000001).
* @function
* @param {integer|float|string} number - The number whose integer digits (the digits that belong to the integer part) we want to count. It can be a string.
* @returns {integer} Returns zero in the case a non-valid number has been provided. Otherwise, it returns the number of integer digits (the number of digits that belong to the integer part) counted.
*/
var CB_countIntegerPart = CB_countIntegerDigits = CB_numberOfIntegerDigits = function(number)
{
number = parseFloat(number);
if (isNaN(number)) { return 0; }
number = Math.abs(number);
if (number < 1) { return 0; }
//First it tries "fastest" way (it does not work for numbers in exponential notation):
var integers = (number + "").split(".");
integers = (typeof(integers[1]) !== "undefined") ? integers[0].length : 0;
if (integers > 0) { return integers; }
//For float numbers that are represented in exponential notation (like '1e-13', for example):
integers = 0;
var numberMultiplied = 0;
while ((numberMultiplied = number / Math.pow(10, ++integers)) > 1);
return integers;
}
/**
* Returns the value of a desired path in an object or an empty string if it cannot be found.
* @function
* @param {Object} object - The object where we want to find the path.
* @param {string} path - The path that will be search in the given object to retrieve the value. It should use the string defined in the "splitString" parameter to separate items. If it is empty or not provided, it will just return the given "object" again.
* @param {string} [splitString="."] - The string that will be used to separate one item from another one. By default, it will be a dot (".") so, for example, a given "path" with a value of "hello.world" will indicate the "object.hello.world" path.
* @returns {*} Returns the value of a desired path in an object or an empty string if it cannot be found. If the "path" parameter is empty or not provided, it will just return the given "object" again.
*/
function CB_getValuePath(object, path, splitString)
{
if (CB_sizeof(object) === 0 || CB_isString(object)) { return ""; }
path = CB_trim(path);
if (path === "") { return object; }
if (!CB_isString(splitString) || splitString.length < 1) { splitString = "."; }
var indexes = path.split(splitString);
var indexesLength = indexes.length;
var index;
var value = object;
for (var x = 0; x < indexesLength; x++)
{
index = CB_trim(indexes[x]);
value = CB_getValueIndex(value, index, "");
if (CB_sizeof(value) === 0 || CB_isString(value)) { break; }
}
return (x + 1 === indexesLength) ? value : "";
}
var CB_setDatumDateObject = new Date();
/**
* Stores a value using [Web Storage API]{@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API} ([localStorage]{@link https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage}). It can use [localStorage]{@link https://github.com/mortzdk/localStorage} as a fallback or cookies instead.
* @function
* @param {string|number} index - The index where the value given will be stored.
* @param {string|number} value - The value we want to store. It should be a string or a number.
* @param {integer} [days] - The number of days after which the cookie will expire (in the case that cookies are used). It belongs to the "expires=" parameter of the cookie. If not provided, the parameter will not be used at all.
* @param {string} [path] - The path where the cookie will be stored (in the case that cookies are used). It belongs to the "path=" parameter of the cookie. If not provided, the parameter will not be used at all.
* @param {boolean} [forceCookie=false] - Forces to use cookies instead of [Web Storage API]{@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API} ([localStorage]{@link https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage}).
* @returns {boolean} Returns true if the value has been stored successfully (not totally reliable, it should be checked with {@link CB_getDatum} after a while).
*/
function CB_setDatum(index, value, days, path, forceCookie)
{
index += "";
value += "";
if (!forceCookie && window.localStorage && window.localStorage.setItem)
{
try
{
localStorage.setItem(index, value);
return true;
} catch(E) { }
}
if (typeof(document.cookie) !== "undefined" && document.cookie !== null)
{
try
{
path = CB_trim(path);
if (path !== "") { path = ";path=" + escape(path); }
var expires = "";
if (typeof(days) !== "undefined" && days !== null && !isNaN(days) && days >= 0 && days <= 365)
{
CB_setDatumDateObject.setTime(CB_setDatumDateObject.getTime() + (days * 24 * 60 * 60 * 1000));
expires = ";expires=" + CB_setDatumDateObject.toUTCString();
}
document.cookie = escape(index) + "=" + escape(value) + expires + path;
return true;
} catch(E) { }
}
return false;
}
/**
* Stores a cookie.
* @function
* @param {string|number} index - The index where the value given will be stored.
* @param {string|number} value - The value we want to store. It should be a string or a number.
* @param {integer} [days] - The number of days after which the cookie will expire. It belongs to the "expires=" parameter of the cookie. If not provided, the parameter will not be used at all.
* @param {string} [path] - The path where the cookie will be stored. It belongs to the "path=" parameter of the cookie. If not provided, the parameter will not be used at all.
* @returns {boolean} Returns true if the value has been stored successfully (not totally reliable, it should be checked with {@link CB_getCookie} after a while).
*/
function CB_setCookie(index, value, days, path)
{
return CB_setDatum(index, value, days, path, true);
}
/**
* Gets, from its index, a previous value stored. It will try to get it using [Web Storage API]{@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API} ([localStorage]{@link https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage}). It can use [localStorage]{@link https://github.com/mortzdk/localStorage} as a fallback or cookies instead.
* @function
* @param {string} index - The index whose value we want to retrieve.
* @param {boolean} [forceCookie=false] - Forces to use cookies instead of [Web Storage API]{@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API} ([localStorage]{@link https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage}).
* @param {boolean} [unescapeIndex=false] - Applies the unescape function to the value before returning it. Only applies when cookies are used.
* @returns {string|null} Returns null when the value cannot be found.
*/
function CB_getDatum(index, forceCookie, unescapeIndex)
{
var itemFound = null;
if (window.localStorage && window.localStorage.getItem && !forceCookie)
{
itemFound = localStorage.getItem(index);
}
if (itemFound === null && typeof(document.cookie) !== "undefined" && document.cookie !== null)
{
index += "=";
if (unescapeIndex) { index = unescape(index); }
var cookies = document.cookie.split(";");
var cookies_length = cookies.length;
for (var x = 0; x < cookies_length; x++)
{
if (cookies[x].indexOf(index) !== -1) { return unescape(cookies[x].substring(cookies[x].indexOf(index) + index.length, cookies[x].length)); }
}
}
return itemFound;
}
/**
* Returns, from its index, a previous stored cookie.
* @function
* @param {string} index - The index whose value we want to retrieve.
* @returns {string|null} Returns null when the value cannot be found.
*/
function CB_getCookie(index)
{
return CB_getDatum(index, true);
}
/**
* Gets the value from a given object which belongs to the desired index or returns the value of "returnValueOnFail" if it cannot be found.
* @function
* @param {Object} object - The object from which we want to get the value.
* @param {string} index - The index whose value we want to retrieve.
* @param {*} [returnValueOnFail=undefined] - The value we want it to return in the case that the property cannot be found. If not provided, undefined will be returned.
* @returns {*} Returns the value from a given object which belongs to the desired index or the value of "returnValueOnFail" otherwise if it cannot be found.
*/
function CB_getValueIndex(object, index, returnValueOnFail)
{
if (typeof(object) !== "undefined" && object !== null && typeof(object[index]) !== "undefined" && object[index] !== null) { return object[index]; }
else { return returnValueOnFail; }
}
/**
* Returns an object copied from the given one.
* @function
* @param {object} element - The element whose properties and values we want to copy. It should be an object.
* @param {boolean} [onlyOwn=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]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty} method).
* @returns {object} Returns an object copied from the given one. Returns an empty object if the given "element" was not an object.
*/
function CB_copyObject(object, onlyOwn)
{
if (typeof(object) !== "object" || object === null) { return {}; }
var newObject = {};
for (var key in object)
{
if (!onlyOwn || object.hasOwnProperty(key)) { newObject[key] = object[key]; }
}
return newObject;
}
/**
* Gets the value of a desired property of a given JSON object. Uses the {@link CB_getValueIndex} function internally.
* @function
* @param {Object|string} JSONObject - The JSON object from which we want to get the value. If it is a string, it will try to parse it to create a real object from it. Used as the "object" parameter when calling the {@link CB_getValueIndex} function internally.
* @param {string} property - The property whose value we want to retrieve. If no