CMap - system.collections - [ Yii中文参考手册 ]

所有包 | 属性 | 方法

包	system.collections
继承	class CMap » CComponent
实现	IteratorAggregate, Traversable, ArrayAccess, Countable
子类	CAttributeCollection, CConfiguration, CCookieCollection, CFormElementCollection, CTypedMap
源自	1.0
版本	$Id: CMap.php 3518 2011-12-28 23:31:29Z alexander.makarow $
源码

CMap实现了一个键名－键值对的集合.

你可以通过使用 itemAt，add，以及remove访问，添加，删除项目。通过调用getCount可获得在map的项目数量。 CMap同样也可以像一个普通的数组使用，如

$map[$key]=$value; //添加一个键名－键值对
unset($map[$key]); //删除指定键名的键值
if(isset($map[$key])) //如果map包含键值
foreach($map as $key=>$value) //遍历map的项目
$n=count($map);  //返回map中的项目数

公共属性

属性	类型	描述	定义在
count	integer	返回map中的项目数。	CMap
iterator	CMapIterator	返回遍历这个列表的项目的迭代器。	CMap
keys	array	返回键名列表	CMap
readOnly	boolean	返回值说明这个列表是否为只读。默认为false。	CMap

公共方法

方法	描述	定义在
__call()	如果类中没有调的方法名，则调用这个方法。	CComponent
__construct()	构造方法。	CMap
__get()	返回一个属性值、一个事件处理程序列表或一个行为名称。	CComponent
__isset()	检查一个属性是否为null。	CComponent
__set()	设置一个组件的属性值。	CComponent
__unset()	设置一个组件的属性为null。	CComponent
add()	添加一个项目到map。	CMap
asa()	返回这个名字的行为对象。	CComponent
attachBehavior()	附加一个行为到组件。	CComponent
attachBehaviors()	附加一个行为列表到组件。	CComponent
attachEventHandler()	为事件附加一个事件处理程序。	CComponent
canGetProperty()	确定属性是否可读。	CComponent
canSetProperty()	确定属性是否可写。	CComponent
clear()	删除map中所有项目。	CMap
contains()		CMap
copyFrom()	将迭代器中的数据复制到map。	CMap
count()	返回map中的项目数。	CMap
detachBehavior()	从组件中分离一个行为。	CComponent
detachBehaviors()	从组件中分离所有行为。	CComponent
detachEventHandler()	分离一个存在的事件处理程序。	CComponent
disableBehavior()	禁用一个附加行为。	CComponent
disableBehaviors()	禁用组件附加的所有行为。	CComponent
enableBehavior()	启用一个附加行为。	CComponent
enableBehaviors()	启用组件附加的所有行为。	CComponent
evaluateExpression()	计算一个PHP表达式，或根据组件上下文执行回调。	CComponent
getCount()	返回map中的项目数。	CMap
getEventHandlers()	返回一个事件的附加处理程序列表。	CComponent
getIterator()	返回遍历这个列表的项目的迭代器。	CMap
getKeys()	返回返回键名列表	CMap
getReadOnly()	返回返回值说明这个列表是否为只读。默认为false。	CMap
hasEvent()	确定一个事件是否定义。	CComponent
hasEventHandler()	检查事件是否有附加的处理程序。	CComponent
hasProperty()	确定属性是否被定义。	CComponent
itemAt()	返回指定位置的项目。	CMap
mergeArray()	递归合并两个或多个数组。	CMap
mergeWith()	将迭代器的数据整合到map。	CMap
offsetExists()	返回值说明指定位置是否存在元素。	CMap
offsetGet()	返回值指定位置的元素。	CMap
offsetSet()	设置指定位置的元素。	CMap
offsetUnset()	删除指定位置的元素。	CMap
raiseEvent()	发起一个事件。	CComponent
remove()	根据键名从map中删除一个项目。	CMap
toArray()		CMap

受保护方法

方法	描述	定义在
setReadOnly()	设置设置这个列表是否为只读	CMap

属性详细

count 属性只读

public integer getCount()

返回map中的项目数。

iterator 属性只读

public CMapIterator getIterator()

返回遍历这个列表的项目的迭代器。此方法为接口IteratorAggregate强制要求实现。

keys 属性只读

public array getKeys()

返回键名列表

readOnly 属性

public boolean getReadOnly()
protected void setReadOnly(boolean $value)

返回值说明这个列表是否为只读。默认为false。

方法详细

__construct() 方法

public void __construct(array $data=NULL, boolean $readOnly=false)
$data	array	初始化的数据。默认为null，意味着没有初始化。
$readOnly	boolean	标识这个列表是否为只读。


public function __construct($data=null,$readOnly=false)
{
    if($data!==null)
        $this->copyFrom($data);
    $this->setReadOnly($readOnly);
}

构造方法。根据数组或者迭代对象初始化这个列表。

add() 方法

public void add(mixed $key, mixed $value)
$key	mixed	键名
$value	mixed	键值


public function add($key,$value)
{
    if(!$this->_r)
    {
        if($key===null)
            $this->_d[]=$value;
        else
            $this->_d[$key]=$value;
    }
    else
        throw new CException(Yii::t('yii','The map is read only.'));
}

添加一个项目到map。请注意，如果指定的键已经存在，旧值将被覆盖。

clear() 方法

public void clear()


public function clear()
{
    foreach(array_keys($this->_d) as $key)
        $this->remove($key);
}

删除map中所有项目。

contains() 方法

public boolean contains(mixed $key)
$key	mixed	键名
{return}	boolean	返回值说明map中是否包含指定键名对应的键值。


public function contains($key)
{
    return isset($this->_d[$key]) || array_key_exists($key,$this->_d);
}

copyFrom() 方法

public void copyFrom(mixed $data)
$data	mixed	要复制的数据, 只能是数组或者继承于Traversable的对象。


public function copyFrom($data)
{
    if(is_array($data) || $data instanceof Traversable)
    {
        if($this->getCount()>0)
            $this->clear();
        if($data instanceof CMap)
            $data=$data->_d;
        foreach($data as $key=>$value)
            $this->add($key,$value);
    }
    else if($data!==null)
        throw new CException(Yii::t('yii','Map data must be an array or an object implementing Traversable.'));
}

将迭代器中的数据复制到map。注意，列表中已经存在的数据会被首先删除。

count() 方法

public integer count()
{return}	integer	返回map中的项目数。


public function count()
{
    return $this->getCount();
}

返回map中的项目数。此方法为接口Countable强制要求实现。

getCount() 方法

public integer getCount()
{return}	integer	返回map中的项目数


public function getCount()
{
    return count($this->_d);
}

返回map中的项目数。

getIterator() 方法

public CMapIterator getIterator()
{return}	CMapIterator	返回遍历列表中元素的迭代器。


public function getIterator()
{
    return new CMapIterator($this->_d);
}

返回遍历这个列表的项目的迭代器。此方法为接口IteratorAggregate强制要求实现。

getKeys() 方法

public array getKeys()
{return}	array	返回键名列表


public function getKeys()
{
    return array_keys($this->_d);
}

getReadOnly() 方法

public boolean getReadOnly()
{return}	boolean	返回值说明这个列表是否为只读。默认为false。


public function getReadOnly()
{
    return $this->_r;
}

itemAt() 方法

public mixed itemAt(mixed $key)
$key	mixed	项目的索引值
{return}	mixed	返回指定位置的元素，如果这个位置没有元素存在，则返回null。


public function itemAt($key)
{
    if(isset($this->_d[$key]))
        return $this->_d[$key];
    else
        return null;
}

返回指定位置的项目。　这个方法跟offsetGet是完全一样的。

mergeArray() 方法

public static array mergeArray(array $a, array $b)
$a	array	要被合并的数组
$b	array	要进行合并的数组。你可以通过第三，四。。。指定额外。
{return}	array	返回合并后的数组（原数组不会发生改变。）


public static function mergeArray($a,$b)
{
    $args=func_get_args();
    $res=array_shift($args);
    while(!empty($args))
    {
        $next=array_shift($args);
        foreach($next as $k => $v)
        {
            if(is_integer($k))
                isset($res[$k]) ? $res[]=$v : $res[$k]=$v;
            else if(is_array($v) && isset($res[$k]) && is_array($res[$k]))
                $res[$k]=self::mergeArray($res[$k],$v);
            else
                $res[$k]=$v;
        }
    }
    return $res;
}

递归合并两个或多个数组。如果每个数组都包含着相同索引的元素，则后面的会覆盖前面的（这个跟array_merge_recursive有区别）。如果两个数组的元素是数组，且是相同的键名，则会进行递归合并。对于以数字作为键名的元素，后面数组的元素会添加到前面的数组里面。

参见

mergeWith

mergeWith() 方法

public void mergeWith(mixed $data, boolean $recursive=true)
$data	mixed	要合并的数据, 只能是数组或者继承于Traversable的对象
$recursive	boolean	标识是否进行递归合并。


public function mergeWith($data,$recursive=true)
{
    if(is_array($data) || $data instanceof Traversable)
    {
        if($data instanceof CMap)
            $data=$data->_d;
        if($recursive)
        {
            if($data instanceof Traversable)
            {
                $d=array();
                foreach($data as $key=>$value)
                    $d[$key]=$value;
                $this->_d=self::mergeArray($this->_d,$d);
            }
            else
                $this->_d=self::mergeArray($this->_d,$data);
        }
        else
        {
            foreach($data as $key=>$value)
                $this->add($key,$value);
        }
    }
    else if($data!==null)
        throw new CException(Yii::t('yii','Map data must be an array or an object implementing Traversable.'));
}

将迭代器的数据整合到map。

如果源中的的键值相同，map中的现有元素将被覆盖。如果合并是递归的，执行下面的算法：

map的数据保存为$a，源数据保存为$b；
如果$a和$b都存在相同的字符串键索引的数组，数组将使用这种算法进行合并；
任何在$b中以整数作为索引的元素，都会直接在$a中重新进行索引，然后加到$a里面；
任何在$b中以字符串作为索引的元素，会覆盖那些在$a中相同索引值的元素；

offsetExists() 方法

public boolean offsetExists(mixed $offset)
$offset	mixed	要检查的位置
{return}	boolean


public function offsetExists($offset)
{
    return $this->contains($offset);
}

返回值说明指定位置是否存在元素。此方法为接口ArrayAccess强制要求实现。

offsetGet() 方法

public mixed offsetGet(integer $offset)
$offset	integer	要检查的位置。
{return}	mixed	返回这个位置的元素，如果该位置不存在元素，则返回null。


public function offsetGet($offset)
{
    return $this->itemAt($offset);
}

返回值指定位置的元素。此方法为接口ArrayAccess强制要求实现。

offsetSet() 方法

public void offsetSet(integer $offset, mixed $item)
$offset	integer	要设置元素的位置
$item	mixed	元素对象


public function offsetSet($offset,$item)
{
    $this->add($offset,$item);
}

设置指定位置的元素。此方法为接口ArrayAccess强制要求实现。

offsetUnset() 方法

public void offsetUnset(mixed $offset)
$offset	mixed	要删除的元素的位置。


public function offsetUnset($offset)
{
    $this->remove($offset);
}

删除指定位置的元素。此方法为接口ArrayAccess强制要求实现。

remove() 方法

public mixed remove(mixed $key)
$key	mixed	要删除的项目的键名
{return}	mixed	返回已经删除的值，如果没有这样的项目存在，则返回null。


public function remove($key)
{
    if(!$this->_r)
    {
        if(isset($this->_d[$key]))
        {
            $value=$this->_d[$key];
            unset($this->_d[$key]);
            return $value;
        }
        else
        {
            // it is possible the value is null, which is not detected by isset
            unset($this->_d[$key]);
            return null;
        }
    }
    else
        throw new CException(Yii::t('yii','The map is read only.'));
}

根据键名从map中删除一个项目。

setReadOnly() 方法

protected void setReadOnly(boolean $value)
$value	boolean	设置这个列表是否为只读


protected function setReadOnly($value)
{
    $this->_r=$value;
}

toArray() 方法

public array toArray()
{return}	array	数组中的项目列表


public function toArray()
{
    return $this->_d;
}