Multi-Dimensional Array (marray) Documentation

Verison 1.0 - January 25th, 2008

Author

This object and group of functions were written by Colin Jermain (PHP Know How). They are to be used in accordance with the accompanying license.

[Return to Top]

Purpose

The purpose of the object and functions is to allow dynamic access to multi-dimensional arrays. This is similar to the concept of variable variables, in which a variable is referenced by another. The object and functions allow both the setting and getting of mult-dimensional arrays, as well as a few extra functions/methods. All indexes are referenced with location strings. Therefore, the only required functions for operation are marray_loc, marray_set, and marray_get, which is also true with the analogous object methods. The other few can be recreated using marray_get (shown in func.marray.php comments). They were provided for ease of use, but are not necessary. Make sure to exersise caution while using these functions because of their use of eval(). When not used properly, they could cause a serious security breach.

Enjoy.

[Return to Top]

Contents

documentation.html
The current document.
obj.marray.php
The uncompressed object source code with comments and descriptions
obj.marray.compressed.php
The compressed object source code with comments and descriptions
func.marray.php
The uncompressed function source code with comments and descriptions
func.marray.compressed.php
The compressed function source code without comments or descriptions
license.txt
The GNU General Public License, Version 3, 29 June 2007
[Return to Top]

Installation

In order to install the object, use the following code:
  require('obj.marray.php');
  $array=new marray(); // required for object
  
If you would rather use the compressed version, or functions, include that file instead.

[Return to Top]

Definitions

Location String
A comma separated string path of array keys. Example:
    table,tr,td
    
[Return to Top]

Object

The object is provided for ease of use. Unlike the functions, the array does not have to be continually passed in as an argument. However, both operate in exactly the same manor.

Constructor

Creates a new marray containing an empty array.
$array=new marray();

marray->set(string $loc, mixed $value)

Arguments:
string $loc
mixed $value
Purpose:
Set a value to a specific array location.
Example:
$array=new marray();
$array->set("table,tr,td", 1);
echo $array;
/* Returns:
Array
(
    [table] => Array
        (
            [tr] => Array
                (
                    [td] => 1
                )

        )

)        
*/
[Return to Top]

marray_get(string $loc)

Arguments:
array $array
string $loc
Purpose:
Get the value at a specific location.
Example:
$array=new marray();
$array->set($array, "table,tr,td", 1);
$loc_array=$array->get("table,tr");
print_r($loc_array);
/* Returns:
Array
(
    [td] => 1
)        
*/
[Return to Top]

marray->loc(string $loc)

Arguments:
string $loc
Purpose:
Processes a location string into array syntax.
Example:
$array=new marray();
echo $array->loc("table,tr,td");
// Returns: ['table']['tr']['td']
[Return to Top]

marray->count(string $loc)

Arguments:
string $loc
Purpose:
Count the specific array location. A variation can be recreated easily with the marray->get method.
Example:
$array=new marray();
$array->set("table,tr,td", array('a'=>1,'b'=>2));
echo $array->count("table,tr,td");
// Returns: 2
[Return to Top]

marray->is_empty(string $loc)

Arguments:
string $loc
Purpose:
Return a boolean value if specific array location is empty. A variation can be recreated easily with the marray->get method.
Example:
$array=new marray();
$array->set("table,tr,td", 1);
if($array->is_empty("table,tr,td")) {
echo "td empty";
}
if($array->is_empty("table,trrr")) {
echo "trrr empty";
}
// Prints: trrr empty
[Return to Top]

marray->is_set(string $loc)

Arguments:
string $loc
Purpose:
Return a boolean value if specific array location is set. A variation can be recreated easily with the marray->get method.
Example:
$array=new marray();
$array->set("table,tr,td", 1);
if($array->is_set("table,tr,td")) {
echo "is_set";
}
if($array->is_set("table,trrr")) {
echo "another is_set";
}
// Prints: is_set
// Doesn't print: another is_set
[Return to Top]

Functions

The functions are identical in both compressed and uncompressed function packages. The functions are provided as an alternative to the object, but function in the same way.

marray_loc(string $loc)

Arguments:
string $loc
Purpose:
Processes a location string into array syntax.
Example:
echo marray_loc("table,tr,td");
// Returns: ['table']['tr']['td']
[Return to Top]

marray_set(array &$array, string $loc, mixed $value)

Arguments:
array $array
string $loc
mixed $value
Purpose:
Set a value to a specific array location.
Example:
marray_set($array, "table,tr,td", 1);
print_r($array);
/* Returns:
Array
(
    [table] => Array
        (
            [tr] => Array
                (
                    [td] => 1
                )

        )

)        
*/
[Return to Top]

marray_get(array &$array, string $loc)

Arguments:
array $array
string $loc
Purpose:
Get the value at a specific location.
Example:
marray_set($array, "table,tr,td", 1);
$loc_array=marray_get($array, "table,tr");
print_r($loc_array);
/* Returns:
Array
(
    [td] => 1
)        
*/
[Return to Top]

marray_count(array &$array, string $loc)

Arguments:
array $array
string $loc
Purpose:
Count the specific array location. A variation can be recreated easily with the marray_get function.
Example:
marray_set($array, "table,tr,td", array('a'=>1,'b'=>2));
echo marray_count($array, "table,tr,td");
// Returns: 2
[Return to Top]

marray_is_empty(array &$array, string $loc)

Arguments:
array $array
string $loc
Purpose:
Return a boolean value if specific array location is empty. A variation can be recreated easily with the marray_get function.
Example:
marray_set($array, "table,tr,td", 1);
if(marray_is_empty($array, "table,tr,td")) {
echo "td empty";
}
if(marray_is_empty($array, "table,trrr")) {
echo "trrr empty";
}
// Prints: trrr empty
[Return to Top]

marray_is_set(array &$array, string $loc)

Arguments:
array $array
string $loc
Purpose:
Return a boolean value if specific array location is set. A variation can be recreated easily with the marray_get function.
Example:
marray_set($array, "table,tr,td", 1);
if(marray_is_set($array, "table,tr,td")) {
echo "is_set";
}
if(marray_is_set($array, "table,trrr")) {
echo "another is_set";
}
// Prints: is_set
// Doesn't print: another is_set
[Return to Top]