/*!
* Copyright (c) 2009 Francesco Mele jsbeans@francescomele.com
*
* This Software is licenced under the LGPL Licence (GNU Lesser General
* Public License).
* In addition to the LGPL Licence the Software is subject to the
* following conditions:
*
* i every modification must be public and comunicated to the Author
* ii every "jsbean" added to this library must be self consistent
* except for the dependence from jsbeans-x.x.x.js
* iii copyright notice and this permission notice shall be included
* in all copies or substantial portions of the Software
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
*/
// IE 5 on Mac doesn't know Array.push. Let it know it!
var _____jsbeansArray = new Array();
if (!_____jsbeansArray.push) {
Array.prototype.push = function(element) {
this[this.length] = element;
};
}
/**
* A collection of utilities for Array objects
* @class Array
* @namespace jsbeans
* @static
*/
jsbeans.Array = {
/**
* Checks if provided parameter is an Array
* @method isArray
* @param {Object} may_be_everything
* @return {boolean} true if parameter is an Array
* @static
*/
isArray: function(a) {
return typeof(a) === "object" && a.constructor == Array;
},
/**
* Returns the index (position) of the <strong>first</strong> occurence of {@param} <code class="param">object_to_find</code> inside {@param} <code class="param">an_Array</code> using the <code>==</code> operator, <code>-1</code> otherwise.<br/>
* Note that it returns -1 even if {@param} <code class="param">an_Array</code> isn't an Array Object.
* @method indexOf
* @param {Object} an_Array
* @param {Object} object_to_find
* @return {Integer} the position
* @static
*/
indexOf: function(a, o) {
if (jsbeans.Array.isArray(a)) {
for (var i = 0, e; e = a[i]; i++) {
if (e == o) {
return i;
}
}
}
return -1;
},
/**
* Returns the index (position) of the <strong>last</strong> occurence of {@param} <code class="param">object_to_find</code> inside {@param} <code class="param">an_Array</code> using operator <code>==</code>, <code>-1</code> otherwise.<br/>
* Note that it returns -1 even if {@param} <code class="param">an_Array</code> isn't an Array Object.
* @method lastIndexOf
* @param {Object} an_Array
* @param {Object} object_to_find
* @return {Integer} the position
* @static
*/
lastIndexOf: function(a, o) {
if (jsbeans.Array.isArray(a)) {
for (var i = a.length - 1, e; e = a[i]; i--) {
if (a[i] == o) {
return i;
}
}
}
return -1;
},
/**
* Checks if two Arrays have same content per position using the <code>==</code> operator.<br/>
* Note that it returns <code>false</code> even if at least one parameter isn't an Array Object.
* @method equals
* @param {Object} first_Array
* @param {Object} second_Array
* @return {boolean} true if both arguments have same content at same position
* @static
*/
equals: function(a, b) {
if (jsbeans.Array.isArray(a) && jsbeans.Array.isArray(b)) {
if (a.length != b.length) {
return false;
}
else {
for (var i = 0, e; e = a[i]; i++) {
if (e != b[i]) {
return false;
}
}
return true;
}
}
return false;
},
/**
* Counts how many times {@param} <code class="param">object_to_find</code> appears in {@param} <code class="param">an_Array</code>.<br/>
* Note that it returns {Integer} 0 even if {@param} <code class="param">an_Array</code> isn't an Array Object.
* @method frequency
* @param {Object} an_Array
* @param {Object} object_to_find
* @return {Integer} counts occurences in an Array
* @static
*/
frequency: function(a, o) {
var res = 0;
if (jsbeans.Array.isArray(a)) {
for (var i = 0, e; e = a[i]; i++) {
if (e == o) {
res++;
}
}
}
return res;
},
/**
* Compares elements each other using operator <code><</code> of given Array returning the lowest value.<br/>
* Note that it returns <code>null</code> even if {@param} <code class="param">an_Array</code> isn't an Array Object.
* @method min
* @param {Object} an_Array
* @return {Object} the lowest value
* @static
*/
min: function(a) {
var res = null;
if (jsbeans.Array.isArray(a)) {
res = a[0];
for (var i = 0, e; e = a[i]; i++) {
if (e < res) {
res = e;
}
}
}
return res;
},
/**
* Compares elements each other using operator <code>></code> of given Array returning the highest value.<br/>
* Note that it returns <code>null</code> even if {@param} <code class="param">an_Array</code> isn't an Array Object.
* @method max
* @param {Object} an_Array
* @return {Object} the highest value
* @static
*/
max: function(a) {
var res = null;
if (jsbeans.Array.isArray(a)) {
res = a[0];
for (var i = 0, e; e = a[i]; i++) {
if (e > res) {
res = e;
}
}
}
return res;
},
/**
* Calls {@param} <code class="param">callback</code> on each element of given Array.<br/>
* An optional third argument can be passed as argument of {@param} <code class="param">callback</code>.
* Note that it breaks execution if a callback returns <code>false</code>. If {@param} <code class="param">an_Array</code> isn't an Array Object this function does nothing exiting silently.
* @method forEach
* @param {Object} an_Array
* @param callback {Function} an (eventually) anonymous function fired on each element
* @param [args] {Object} optional argument for callback. May be everything.
* @static
*/
forEach: function(a, callback /*, args*/) {
if (jsbeans.Array.isArray(a) && typeof(callback) == "function") {
var args = arguments[2] || null;
for (var i = 0, e; e = a[i]; i++) {
if (callback(e, args) === false) {
break;
}
}
}
},
/**
* Creates a copy of {@param} <code class="param">an_Array</code> without {@param} <code class="param">value</code>.<br/>
* {@param} <code class="param">value</code> matches using <code>!=</code> operator.
* If {@param} <code class="param">an_Array</code> isn't an Array Object it returns the parameter itself.
* @method remove
* @param {Object} an_Array
* @param value {Object} the element to remove
* @return {Array}
* @static
*/
remove: function(a, value) {
if (jsbeans.Array.isArray(a)) {
var res = [];
for (var i = 0, e; (e = a[i]) != null; i++) {
if (e != value) {
res.push(e);
}
}
return res;
}
return a;
},
/**
* Parses string {@param} <code class="param">str</code> in the form <code>[<em>element list separated by commas</em>]</code>.<br/>
* Internally this method parses the string via a JSON format, so it fails when native JSON parsing fails.
* @method parse
* @param {String} str
* @return {Array}
* @static
*/
parse: function(str) {
var t = eval("({t:" + str + "})");
return t['t'];
}
};