KEY
KEY
The default key index in an array defined element
EX: Array( 0 => 'key', 1 => 'value' ) See __constructor
Map Class - Defines A Map Data Structure
A Map in this instance is a very versatile and complex data type. In a traditional array in PHP, the keys are integers or strings, as an indexed array is pretty much the same as an indexed one in the language. This cracks this concept wide open and allows keys to be objects, resources, any valid comparable php value. This means that a Person object could be a key to an array of Courses.
Some of this functionality can be accomplished by simply creating a private array in the 'enclosing' class, (e.g. Person->Courses), but some functionality is unique to Maps themselves as opposed to arrays.
CHANGELOG
1.0: Map Completed and Documented - March 8th, 2013 1.1: Eliminated unnecessary Null objects - March 26th, 2013 1.2: Provided closure's for static methods - October 7th, 2013 2.0: Implemented in Primus - August 25th, 2015 2.1: Fixed Typo in Remove - September 5th, 2015 3.0: re-worked exists() to be compatible with arrayaccess methods reformatted and updated for includion in phabstractic - July 24th, 2016 3.0.1: implements configurationinterface - July 31st, 2016
configure(array|string|\Phabstractic\Features\Zend\Config\Config $configuration, string $format = null, mixed $context = null) : boolean
Configure An Object
Expects an array for configuration however, you can also pass it a filepath where it will read the information from a file automatically detecting the format using the file extension. You can also pass a Zend/Config object already made.
You can also pass a format specifier (forced format) for use in a if $configuration is a string formatted with such information. E.G. to load from a string in the format ini:
$this->configure($configString, 'ini');
The $context argument is used for any additional reader constructor information, such as the constructor for the 'yaml' format.
NOTE: You can override/extend the classes used for reading formats by identifying an additional array in the property $this->configReaders. This will merge with the standard formats array.
| array|string|\Phabstractic\Features\Zend\Config\Config | $configuration | The objects configuration information. |
| string | $format | The forced format, or format for configuration string |
| mixed | $context | Any additional information for a reader constructor, such as needed for the YAML format. |
True if instantiated
saveSettings(string $file, \Phabstractic\Features\Zend\Config\Writer\WriterInterface $writer = null, boolean $exclusive = true, mixed $context = null)
Save an Object's Configuration to a File
Takes an objects $conf property and writes the information contained therein to a file with a format automatically specified by the filename.
It is possible to retrieve a string of a particular format from this method by specifying the filename '#string' with an extension indicating the desired format, such as '#string.json'.
The $context argument is used for any additional reader constructor information, such as the constructor for the 'yaml' format.
NOTE: You can override/extend the classes used for writing formats by identifying an additional array in the property $this->configWriters. This will merge with the standard formats array.
| string | $file | The file path to write to, or '#string.ext' |
| \Phabstractic\Features\Zend\Config\Writer\WriterInterface | $writer | The optional writer object supplied to use (such as a MySQL writer) |
| boolean | $exclusive | Argument provided to toFile(), file exclusive lock when writing |
| mixed | $context | Any additionla writer constructor information (YAML) |
getSettings(string $format, $context = null) : string|boolean
Retrieve an Object's Configuration Information As String
This is a shortcut to ::saveSettings() which specifies a format and forces the return of a string, using the #string.ext filename -see documentation for ::saveSettings()-
| string | $format | The format to return, must be supported by ::saveSettings(), use $this->configWriters to support additional formats. |
| $context |
The formatted string, or false otherwise
processSettings(\Phabstractic\Features\Zend\Config\Processor\ProcessorInterface $processor)
Process an Object's Configuration
This uses a Zend\Config\Processor implementation to process the configuration information, such as constants. The processor must be supplied and implement ProcessorInterface
NOTE: Edits the $conf object in place.
| \Phabstractic\Features\Zend\Config\Processor\ProcessorInterface | $processor | The given processor object |
current() : mixed
Return the current \Iterator value
$this->pos is an index of the keys of the map, NOT it's values. This means that any given key's actual value will be the self::VALUE index in the values member. Thus:
VALUES[ KEY[pos][INDEX]]
The value currently being pointed to by \Iterator
__construct(array $values = array(), array $options = array())
The Map Constructor
This constructor is a beast. It takes several forms of input, but it generally boils down to an array of values that will be turned into key/value pairs, and an array of options.
The key/value pair is constructed according to the array elements data type.
Currently the allowed data types are: stdClass (->key, and ->value) array ('key'/0, 'value'/1) string keySELF::SEPARATORvalue the actual key and value of the element otherwise
Currently available options: strict => whether to output errors or remain silent (and return empties) typed => check the types of keys in comparisons (unique)
| array | $values | The values, as outlined above, for the Map laid out in key/value pairs |
| array | $options | The options for the Map as outlined above |
find(mixed $key) : mixed
The 'get' function of the Map object
This technically 'finds' the value for a given key in the morass of internal counters that is the Map object, so it is named 'find', but it essentially 'gets' the associated value
$map->find($key) = $map[$key]
| mixed | $key | The key to find the value for |
if the key doesn't exist and 'strict' is set
The value associated with the given key
findReference(mixed $key) : mixed
The 'get' function of the Map object, as reference
This technically 'finds' the value for a given key in the morass of internal counters that is the Map object, so it is named 'find', but it essentially 'gets' the associated value
$map->find($key) = $map[$key]
| mixed | $key | The key to find the value for |
if the key doesn't exist and 'strict' is set
The value associated with the given key
offsetSet(integer $key, mixed $value) : integer|null
Set the offset in the map to the provided value
| integer | $key | The index to the list item |
| mixed | $value | The value to set to |
if the value doesn't meet restrictions
difference() : \Phabstractic\Data\Types\Map
The difference between Map(s), takes a variable number of arguments (> 1)
if less than two arguments are provided
A difference map (containing all the entries from the first argument not present in others)
intersect() : \Phabstractic\Data\Types\Map
The intersection between Map(s), takes a variable number of arguments (> 1)
if less than two arguments are provided
the intersection of the arguments: all the values present in all the parameters
combine(array $keys, array $values, $strict = false) : false|\Phabstractic\Data\Types\Map
Handy function that takes an array of keys (of any type), and assigns them in a Map to $values
| array | $keys | The keys of the map |
| array | $values | The values to be associated with the keys (in order) |
| $strict |
returns false on failure (non-matching arrays)
countValues(\Phabstractic\Data\Types\Map $map) : \Phabstractic\Data\Types\Map
"returns an array using the values of the input array as keys and their frequency in input as values."
This is where Maps really shine, as they can accept keys that are not strings and integers
| \Phabstractic\Data\Types\Map | $map | The map to analyze |
merge() : \Phabstractic\Data\Types\Map
Merge two or more Maps, just like array_merge
if less than two arguments are provided
index(mixed $key) : integer|null
Return the internal index of a key
This value is the index of ->values as held by a ->key[]
| mixed | $key | The key we are calculating the index for |
when 'strict' and no such key exists
The internal index, linking the map key to the map value
mapArgs(array $args) : array
Utility function for the static functions
This turns all the given arguments of a function into Maps
This simplified operations as they only have to act on Map objects
| array | $args | The arguments to turn into Map objects |
An array of Map objects constructed from the arguments