xArray

xArray stands for eXtended array. It allows you to manipulate arrays in a different, more comfortable manner. Most methods accept (expect) a lambda/callback parameter - a function that will be executed on all members - so the criteria can be as dynamic and programatic as you need it to be.

Change Log

• v0.1 - Start, basic functionallity.

• v0.1.1 - Some bug fixes.

• v0.2 - Added new methods - eachRecursive(), reach(), reachSingle, reachMultiple(). Added another callback parameter ($_result) to each() and eachRecursive().

• v0.3 - Added test cases. Some code refactoring (_getCallback()).

Methods

xArray ($objectArray=false)

Constructor. An array to be converted to xArray can be passed as an argument.

(public) append ($what)

Appends value/array of values to the end of the array.

(public) appendArray ($which)

Appends array.

(public) appendSingle ($what, $where=false)

Appends single value.

(public) prepend ($what)

Prepends value/array of values at the beginning of the array.

(public) prependArray ($which)

Prepends array.

(public) prependSingle ($what)

Prepends single value.

(public) length ()

Returns xArray length.

(public) reverse ($inPlace=false)

Returns reversed first-level xArray. If passed $inPlace argument, reverses xArray itself.

(public) reset ()

Resets xArray iteration pointer.

(public) first ()

Returns first element of the xArray.

(public) last ()

Returns last element of the xArray.

(public) fetch ()

Returns next element of the xArray.

(public) each ($iterator)

Calls $iterator callback/lambda on every member of xArray. First-level only. Returns the last result.

(public) eachRecursive ($iterator, $_result=null)

Calls $iterator callback/lambda on every member of xArray. Recursive. Returns the last result.

(public) all ($iterator=false, $strict=false)

Returns true if all xArray members return true form supplied $iterator callback/lambda.

Second parameter forces strict testing.

(public) any ($iterator=false, $strict=false)

Returns true if any one of xArray members returns true form supplied $iterator callback/lambda.

Second parameter forces strict testing.

(public) collect ($iterator, $inPlace=false)

Calls $iterator callback/lambda on each xArray member and returns result as xArray.

If passed $inPlace attribute, result replaces current xArray.

(public) map ($iterator, $inPlace=false)

Same as collect().

(public) detect ($iterator=false, $strict=false)

Returns first xArray member that returns true from $iterator callback/lambda. False if none found.

If no callback supplied, will default to 'return $value'.

Second parameter forces strict testing.

(public) detectKey ($iterator=false, $strict=false)

Returns first xArray member's KEY that returns true from $iterator callback/lambda. False if none found.

If no callback supplied, will default to 'return $value'.

Second parameter forces strict testing.

(public) find ($iterator, $strict=false)

Same as detect().

(public) grep ($pattern, $iterator=false, $inPlace=false)

Tests xArray members against supplied regular expression pattern.

Returns matching results as xArray.

If $iterator callback/lambda given, result contains return values of $iterator for each match.

If given $inPlace attribute, will replace current xArray with result.

(public) grepKeys ($pattern, $iterator=false, $inPlace=false)

Tests xArray keys against supplied regular expression pattern.

Returns matching results as xArray.

If $iterator callback/lambda given, result contains return values of $iterator for each match.

If given $inPlace attribute, will replace current xArray with result.

(public) has ($pattern)

Tests xArray members against supplied regular expression pattern.

Returns true if match found, false otherwise.

(public) hasKey ($pattern)

Tests xArray keys against supplied regular expression pattern.

Returns true if match found, false otherwise.

(public) invoke ($methodName, $args=array(), $inPlace=false)

Calls $methodName method on each xArray object member.

Returns results as xArray.

Optional arguments array is passed to each method.

(public) invokeSingle ($methodName, $id, $args=array())

Calls $methodName method on a single xArray object member.

(public) max ($iterator=false)

Returns the element with the greatest result of calling the $iterator callback/lambda for each xArray element, if given. Else returns element with greatest value.

(public) min ($iterator=false)

Returns the element with the smallest result of calling the $iterator callback/lambda for each xArray element, if given. Else returns element with smallest value.

(public) select ($iterator=false, $inPlace=false)

Returns xArray with all elements that return true-a-like value from $iterator callback/lambda. Loose testing.

If given $inPlace parameter, replaces current xArray.

(public) reject ($iterator=false, $inPlace=false)

Returns xArray with all elements that return false-a-like value from $iterator callback/lambda. Loose testing.

If given $inPlace parameter, replaces current xArray.

(public) pluck ($propertyName, $inPlace=false)

Returns xArray with all elements' $propertyName properties.

If given $inPlace parameter, replaces current xArray.

(public) pluckSingle ($propertyName, $id)

Returns a single element's $propertyName property.

(public) sortBy ($iterator, $inPlace=false)

Returns xArray sorted by $iterator callback/lambda result.

If given $inPlace parameter, replaces current xArray.

(public) toArray ()

Returns xArray as simple array.

(public) toString ($separator=', ')

Converts xArray to string. First-level only.

(public) get ($id)

Returns xArray $id member.

(public) set ($id, $value, $force=true)

Sets xArray $id member to $value.

Optional third parameter forces overwrite (defaults to true).

(public) remove ($id)

Unsets xArray $id member.

(public) clear ()

Clears xArray members.

(public) indexOf ($val, $strict=false)

Returns xArray index for $value. Searches only first-level xArray.

Optional third parameter forces strict matching.

(public) compact ($inPlace=false)

Returns xArray reindexed and with null values removed.

If given $inPlace parameter, result replaces current xArray.

(public) without ($passedArray)

Returns current xArray without supplied values.

(public) withoutKeys ($passedArray)

Returns current xArray without supplied keys.

(public) extract ($start=0, $len=false, $inPlace=false)

Extracts a slice of xArray. First-level only.

(public) reach ($path, $callback=false)

Path-reaching hub.

(public) reachSingle ($path, $callback=false)

Reaches a single value, designated by $path, and optionally applies $callback.

Path must be deterministic (ie. '0.xMemberKey.xAnotherXmemberKey').

EXPERIMENTAL: Will attempt reaching non-xArray object properties, according to given path.

(public) reachMultiple ($path, $callback=false)

Reaches multiple values, designated by $path, and applies $callback through each() method.

Path must be non-deterministic (ie. '{n}.xMemberKey.xAnotherXmemberKey').

EXPERIMENTAL: Will attempt reaching non-xArray object properties, according to given path.

(private) _getCallback ($callback, $args = false, $defaultCallback=false)

Uniform way to obtain callback.

(private) _makeValueClone ($val)

Makes object clones for PHP5.