Abstract Map Class in PHP

Object that maps keys to values we will call 'map'. We will define a general interface for implementing concreate maps. Our map will not be able to hold duplicate keys which means that each key can map at most to one value. When we are talking about value we actually mean object references.

Here is the source for the abstract map. Most of the methods are abstract and need to be implemented by inheriting classes. Abstract methods throw error 'Operation not supported.'. The code runs under PHP 4 and PHP 5.

/**
 * PHP4
 * PHP5
 *
 * Abstract Map Class
 *
 * An object that maps keys to values. A map cannot contain duplicate keys;
 * each key can map to at most one value.
 *
 * @author Ivan Georgiev
 * @abstract
 */
class ig_util_AbstractMap {
 
	/**
	 * Removes all of the mappings from this map (optional operation).
	 * @return void
	 * @abstract
	 */
	function clear() {
		trigger_error('Operation not supported', E_USER_WARNING);
	}
 
	/**
	 * Returns a shallow copy of this AbstractMap instance: the keys and values
	 * themselves are not cloned.
	 *
	 * @return ig_util_AbstractMap
	 */
	function & clone() {
		$class = get_class($this);
		$cloneMap =& new $class();
		$cloneMap->putAll($this);
		return $cloneMap;
	}
 
	/**
	 * Returns true if this map contains a mapping for the specified key.
	 *
	 * @param string $key
	 * @return boolean
	 */
	function containsKey($key) {
		return in_array($key, $this->keyArray());
	}
 
	/**
	 * Returns true if this map maps one or more keys to the specified value.
	 *
	 * @param Object $value
	 * @return boolean
	 */
	function containsValue(&$value) {
		$isFound = false;
		foreach($this->keyArray() as $key) {
			$storedValue =& $this->get($key);
			if ($this->_areSame($value, $storedValue)) {
				$isFound = true;
				break;
			}
		}
		return $isFound;
	}
 
	/**
	 * Returns the value to which the specified key is mapped, or FALSE if
	 * this map contains no mapping for the key.
	 *
	 * @param string $key
	 * @return Object
	 * @abstract
	 */
	function & get($key) {
		trigger_error('Operation not supported', E_USER_WARNING);
	}
 
	/**
	 * Returns true if this map contains no key-value mappings.
	 *
	 * @return boolean
	 * @abstract
	 */
	function isEmpty() {
		trigger_error('Operation not supported', E_USER_WARNING);
	}
 
	/**
	 * Returns an array view of the keys contained in this map.
	 *
	 * @return array
	 * @abstract
	 */
	function keyArray() {
		trigger_error('Operation not supported', E_USER_WARNING);
	}
 
	/**
	 * Associates the specified value with the specified key in this map.
	 *
	 * @return void
	 * @abstract
	 */
	function put($key, &$value) {
		trigger_error('Operation not supported', E_USER_WARNING);
	}
 
	/**
	 * Copies all of the mappings from the specified map to this map
	 * (optional operation).
	 *
	 * @param ig_util_AbstractMap $map
	 * @return void
	 */
	function putAll(&$map) {
		foreach($map->keyArray() as $copyKey) {
			$this->put($copyKey, $map->get($copyKey));
		}
	}
 
	/**
	 * Removes the mapping for a key from this map if it is present.
	 *
	 * @return void
	 * @abstract
	 */
	function remove($key) {
		trigger_error('Operation not supported', E_USER_WARNING);
	}
 
	/**
	 * Returns the number of key-value mappings in this map.
	 *
	 * @return int
	 * @abstract
	 */
	function size() {
		trigger_error('Operation not supported', E_USER_WARNING);
	}
 
	/**
	 * Returns a string representation of this map.
	 *
	 * @return string
	 */
	function toString() {
		$result = '';
		foreach($this->keyArray() as $key) {
			$obj =& $this->get($key);
			if ( $result!='') $result .= ',';
			if (method_exists($obj, 'toString')) {
				$objValue = $obj->toString();
			} else if (method_exists($obj, '__toString')) {
				$objValue = $obj->__toString();
			} else {
				$objValue = 'Object ' . get_class($obj);
			}
			$result .= '\'' . addcslashes($key, '\'') . '\':';
			$result .= '\'' . addcslashes($objValue, '\'') . '\'';
		}
		$result = '{' . $result . '}';
		return $result;
	}
 
	/**
	 * Returns true if the two references point to the same object.
	 *
	 * @param Object $obj1
	 * @param Object $obj2
	 * @return boolean
	 * @access protected
	 */
	function _areSame(&$obj1, &$obj2) {
		$key = uniqid('_ig_same_check_' . get_class($this));
		while (isset($obj1->$key) && isset($obj2->$key)) {
			$key .= '_';
		}
		$obj1->$key = true;
		$areSame = isset($obj2->$key);
		unset($obj1->key);
		return $areSame;
	}
 
}

Known implementations: Associative array map in PHP

See also: Associative array map in PHP, Associative array map in PHP Unit Tests

Resumes