Provide a common container for a set of models. More...

Inheritance diagram for P4_Iterator:

Public Member Functions
	__construct ($models=null)
	Create a new model iterator.
	current ()
	Return the value of the array element that's currently being pointed to by the internal pointer.
	filterByCallback ($callback, $params=null, $options=array())
	Filter items of this instance by callback function.
	first ()
	Get the value of the first element.
	getProperties ()
	Get all properties of this iterator.
	getProperty ($name)
	Get a particular property value of this iterator.
	hasProperty ($name)
	Check if iterator has a particular property.
	invoke ($functionName, $params=array())
	Will run the specified function on each entry in the iterator, optionally passing arguments.
	key ()
	Return the key of the array element that's currently being pointed to by the internal pointer.
	keys ()
	Get all of the keys for all of the entries in this iterator.
	last ()
	Get the value of the last element.
	merge (P4_Iterator $iterator)
	Merges the passed iterator's values into this iterator.
	next ()
	Overwrite next() method to return current value or false.
	offsetSet ($key, $model)
	Set the model under the given key.
	rewind ()
	Overwrite rewind() method to reset array pointer.
	seek ($position)
	Seek to an absolute position.
	setProperties (array $properties)
	Set iterator properties.
	setProperty ($name, $value)
	Set a particular property of this iterator.
Public Attributes
const	FILTER_COPY = 'COPY'
const	FILTER_INVERSE = 'INVERSE'
Protected Attributes
	$_allowedModelClass = 'P4_ConnectedInterface'
	Define the type of models we want to accept in this iterator.
	$_properties = array()
	Store custom iterator properties.

Detailed Description

Provide a common container for a set of models.

Advantage of extending ArrayIterator is that php built-in array-walk functions reset(), next(), key(), current() can be replaced by class-implemented counterparts and vice versa. In other words, if $iterator is an instance of P4_Iterator class then $iterator->next() and next($iterator) are equivalent and same for all other pairs.

Copyright:: 2011-2012 Perforce Software. All rights reserved

License:: Please see LICENSE.txt in top-level folder of this distribution.

Version:: 2012.2/486814

Constructor & Destructor Documentation

P4_Iterator::__construct ( $ models = null )

Create a new model iterator.

If an array of models is given, populate from the array.

Parameters:

array $models optional - the set of models to contain.

    {
        if (isset($models) && is_array($models)) {
            foreach ($models as $model) {
                if (!$model instanceof $this->_allowedModelClass) {
                    throw new InvalidArgumentException("Models array contains one or more invalid elements.");
                }
            }
            parent::__construct($models);
        } else {
            parent::__construct(array());
        }
    }

Member Function Documentation

P4_Iterator::current ( )

Return the value of the array element that's currently being pointed to by the internal pointer.

It does not move the pointer in any way.

Returns:: P4_Model

    {
        return current($this);
    }

P4_Iterator::filterByCallback	(	$	callback,
		$	params = `null`,
		$	options = `array()`
	)

Filter items of this instance by callback function.

Callback must be callable function with at least one parameter represents the allowed model class instance.

Additional parameters can be set in params, in this case callback will be called with model instance parameter followed by params.

Item (model) is acceptable if and only if callback function with item passed as first parameter returns true.

Valid filter options are:

FILTER_INVERSE - inverse filtering behavior - acceptable items are removed FILTER_COPY - return a filtered copy without modifying original

Parameters:

callback	$callback	callback function to determine if item is acceptable
mixed	$params	optional additional callback parameters
string \| array	$options	optional - one or more filtering options

Returns:: P4Cms_Model_Iterator provides fluent interface

    {
        if (!is_callable($callback)) {
            throw new Exception('Callback for P4Cms_Model_Iterator must be callable function.');
        }

        $copy = new static;

        // remove items where callback returns false
        foreach ($this->getArrayCopy() as $key => $model) {

            $passesFilter = call_user_func_array($callback, array($model, $params));

            // inverse behavior if FILTER_INVERSE option is set
            if (in_array(self::FILTER_INVERSE, $options)) {
                $passesFilter = !$passesFilter;
            }

            if (!$passesFilter && !in_array(static::FILTER_COPY, $options, true)) {
                $this->offsetUnset($key);
            } else if ($passesFilter && in_array(static::FILTER_COPY, $options, true)) {
                $copy[$key] = $model;
            }
        }

        return in_array(static::FILTER_COPY, $options, true) ? $copy : $this;
    }

P4_Iterator::first ( )

Get the value of the first element.

Returns:: P4_ModelInterface

    {
        $this->rewind();
        return $this->current();
    }

P4_Iterator::getProperties ( )

Get all properties of this iterator.

Returns:: array all properties set to this iterator

    {
        return $this->_properties;
    }

P4_Iterator::getProperty ( $ name )

Get a particular property value of this iterator.

Parameters:

string $name name of the property to get the value of

Returns:: mixed the value of the property name

Exceptions:

InvalidArgumentException if the property name does not exist

    {
        // return property value if it was set, otherwise throw an exception
        if ($this->hasProperty($name)) {
            return $this->_properties[$name];
        }

        throw new InvalidArgumentException(
            "Cannot find iterator property '$name'. Property was not set."
        );
    }

P4_Iterator::hasProperty ( $ name )

Check if iterator has a particular property.

Parameters:

string $name the property name to check for the existence of

Returns:: boolean true if the iterator has the named property, false otherwise.

    {
        return array_key_exists($name, $this->_properties);
    }

P4_Iterator::invoke	(	$	functionName,
		$	params = `array()`
	)

Will run the specified function on each entry in the iterator, optionally passing arguments.

An array of function return values will be returned.

Parameters:

string	$functionName	The name of the function to execute
array	$params	Optional array of paramaters to pass the function

Returns:: array Array of return values

Exceptions:

InvalidArgumentException If any entry lacks the specified function

    {
        $results = array();

        foreach ($this as $entry) {
            if (!is_object($entry) || !method_exists($entry, $functionName)) {
                throw new InvalidArgumentException(
                    'One or more entries lack the specified function'
                );
            }

            $results[] = call_user_func_array(array($entry, $functionName), $params);
        }

        return $results;
    }

P4_Iterator::key ( )

Return the key of the array element that's currently being pointed to by the internal pointer.

It does not move the pointer in any way.

Returns:: string|integer|null

    {
        return key($this);
    }

P4_Iterator::keys ( )

Get all of the keys for all of the entries in this iterator.

Returns:: array a list of the keys in the iterator.

    {
        return array_keys($this->getArrayCopy());
    }

P4_Iterator::last ( )

Get the value of the last element.

Returns:: P4_ModelInterface

    {
        end($this);
        return $this->current();
    }

P4_Iterator::merge ( P4_Iterator $ iterator )

Merges the passed iterator's values into this iterator.

If the input iterator has the same string keys, then the later value for that key will overwrite the previous one. If, however, the key are numeric, the later value will not overwrite the original value, but will be appended.

Parameters:

P4_Iterator $iterator The new values to merge in

Returns:: P4_Model_Iterator provides fluent interface

    {
        foreach ($iterator as $key => $value) {
            if (is_int($key)) {
                $this[] = $value;
            } else {
                $this[$key] = $value;
            }
        }

        return $this;
    }

P4_Iterator::next ( )

Overwrite next() method to return current value or false.

If php built-in next() function is not called then array pointer is not advanced and other php array-walk functions like current() or key() won't work.

Returns:: false | mixed

    {
        parent::next();
        next($this);
        return $this->valid() ? $this->current() : false;
    }

P4_Iterator::offsetSet	(	$	key,
		$	model
	)

Set the model under the given key.

Parameters:

string \| integer	$key	the key to store the model under.
P4_Model	$model	the model to store.

Returns:: void

    {
        if (!$model instanceof $this->_allowedModelClass) {
            throw new InvalidArgumentException("Invalid model supplied.");
        }
        return parent::offsetSet($key, $model);
    }

P4_Iterator::rewind ( )

Overwrite rewind() method to reset array pointer.

If php built-in reset() function is not called then array pointer is not advanced and other php array-walk functions like current() or key() won't work.

    {
        parent::rewind();
        reset($this);
    }

P4_Iterator::seek ( $ position )

Seek to an absolute position.

Parameters:

integer $position the numeric position to seek to.

    {
        if (!is_integer($position)) {
            throw new OutOfBoundsException('Invalid seek position.');
        }
        $this->rewind();
        $current = 0;
        while ($current < $position && $this->valid()) {
            $this->next();
            $current++;
        }
        if (!$this->valid()) {
            throw new OutOfBoundsException('Invalid seek position.');
        }
    }

P4_Iterator::setProperties ( array $ properties )

Set iterator properties.

Parameters:

array $properties array with properties to set

Returns:: P4_Iterator provides a fluent interface

    {
        $this->_properties = $properties;

        return $this;
    }

P4_Iterator::setProperty	(	$	name,
		$	value
	)

Set a particular property of this iterator.

Parameters:

string	$name	name of the property to set the value of
mixed	$value	value to set

Returns:: P4_Iterator provides a fluent interface

    {
        $this->_properties[$name] = $value;

        return $this;
    }

Member Data Documentation

P4_Iterator::$_allowedModelClass = 'P4_ConnectedInterface' [protected]

Define the type of models we want to accept in this iterator.

Reimplemented in P4_Model_Iterator, and P4Cms_Model_Iterator.

P4_Iterator::$_properties = array() [protected]

Store custom iterator properties.

const P4_Iterator::FILTER_COPY = 'COPY'

const P4_Iterator::FILTER_INVERSE = 'INVERSE'

The documentation for this class was generated from the following file:

Iterator.php

P4_Iterator Class Reference

Public Member Functions

Public Attributes

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation