TempMail/vendor/qingbing/php-helper/src/lib/CList.php

<?php
/**
 * Link         :   http://www.phpcorner.net
 * User         :   qingbing<780042175@qq.com>
 * Date         :   2018-12-10
 * Version      :   1.0
 */

namespace Helper;

use Abstracts\Base;
use Traversable;

/**
 * \ArrayAccess 将数组提供出来像数组一样使用
 * $myList['name'] = $obj; 对应使用 \ArrayAccess.offsetSet($offset, $value)
 * $obj = $myList['name']; 对应使用 \ArrayAccess.offsetGet($offset)
 * isset($myList['name']); 对应使用 \ArrayAccess.offsetExists($offset)
 * unset($myList['name']); 对应使用 \ArrayAccess.offsetUnset($offset)
 *
 * \Countable 将提供对象的countable功能
 * count($myList); 将对应使用 \Countable.count()
 *
 * \IteratorAggregate 将提供对象支持 foreach 等的迭代操作
 * foreach($myList as $key=>$value); 对应使用 \IteratorAggregate.getIterator(),返回必须可迭代
 *
 * Class CList
 * @package Helper
 */
class CList extends Base implements \ArrayAccess, \Countable, \IteratorAggregate
{
    /* @var array list的对象集合 */
    private $_data = [];
    /* @var int 列表当前的统计数量 */
    private $_count = 0;
    /* @var bool list是否只读，默认可读写 */
    private $_readOnly = false;

    /**
     * 构造函数
     * @param mixed $data
     * @param bool $readOnly
     * @throws Exception
     */
    public function __construct($data = null, $readOnly = false)
    {
        if (null !== $data) {
            $this->copyFrom($data);
        }
        $this->setReadOnly($readOnly);
    }

    /**
     * 返回 list 是否只读
     * @return boolean
     */
    public function getReadOnly()
    {
        return $this->_readOnly;
    }

    /**
     * 设置 list 是否只读
     * @param boolean $readOnly
     */
    public function setReadOnly($readOnly)
    {
        $this->_readOnly = $readOnly;
    }

    /**
     * 从可迭代数据中复制成 list
     * @param mixed $data
     * @throws Exception
     */
    public function copyFrom($data)
    {
        if (is_array($data) || ($data instanceof \Traversable)) {
            if ($this->_count > 0) {
                $this->clear();
            }
            if ($data instanceof CList) {
                $data = $data->_data;
            }
            foreach ($data as $item) {
                $this->push($item);
            }
        } elseif ($data !== null) {
            throw new Exception('实例化列表参数必须是数组或可遍历的对象', 100100501);
        }
    }

    /**
     * list 合并
     * @param mixed $data
     * @throws Exception
     */
    public function mergeWith($data)
    {
        if (is_array($data) || ($data instanceof \Traversable)) {
            if ($data instanceof CList) {
                $data = $data->_data;
            }
            foreach ($data as $item) {
                $this->push($item);
            }
        } elseif ($data !== null) {
            throw new Exception('列表合并参数必须是数组或可遍历的对象', 100100502);
        }
    }

    /**
     * 获取 list 的长度
     * @return int
     */
    public function getCount()
    {
        return $this->count();
    }

    /**
     * 返回元素在 list 中的索引
     * @param mixed $item
     * @return int|mixed 未找到返回-1
     */
    protected function indexOf($item)
    {
        if (false !== ($index = array_search($item, $this->_data, true)))
            return $index;
        else
            return -1;
    }

    /**
     * 在指定位置插入一个元素
     * @param int $index
     * @param mixed $item
     * @throws Exception
     */
    protected function insertAt($index, $item)
    {
        if ($this->getReadOnly()) {
            throw new Exception('只读list，不允许执行插入操作', 100100503);
        }

        if ($this->_count === $index) {
            $this->_data[$this->_count++] = $item;
        } elseif ($index >= 0 && $index < $this->_count) {
            array_splice($this->_data, $index, 0, [$item]);
            $this->_count++;
        } else {
            throw new Exception(str_cover('List索引"{index}"已超出范围', [
                '{index}' => $index,
            ]), 100100504);
        }
    }

    /**
     * 删除一个 list 元素，并返回这个元素
     * @param int $index
     * @return mixed
     * @throws Exception
     */
    protected function removeAt($index)
    {
        if ($this->getReadOnly()) {
            throw new Exception('只读list，不允许执行移除操作', 100100505);
        }

        if ($index >= 0 && $index < $this->_count) {
            $this->_count--;
            if ($index === $this->_count) {
                return array_pop($this->_data);
            } else {
                $item = $this->_data[$index];
                array_splice($this->_data, $index, 1);
                return $item;
            }
        } else {
            throw new Exception(str_cover('List索引"{index}"已超出范围', [
                '{index}' => $index,
            ]), 100100506);
        }
    }

    /**
     * 获取 list 中指定索引的元素
     * @param int $index
     * @return mixed
     * @throws Exception
     */
    protected function itemAt($index)
    {
        if (isset($this->_data[$index])) {
            return $this->_data[$index];
        } elseif ($index >= 0 && $index < $this->_count) {
            return $this->_data[$index];
        } else {
            throw new Exception(str_cover('List索引"{index}"已超出范围', [
                '{index}' => $index,
            ]), 100100507);
        }
    }

    /**
     * 返回是否包含元素
     * @param mixed $item
     * @return boolean
     */
    public function contains($item)
    {
        return $this->indexOf($item) >= 0;
    }

    /**
     * 添加一个元素，返回添加的元素索引
     * @param mixed $item
     * @return int
     * @throws Exception
     */
    public function push($item)
    {
        $this->insertAt($this->_count, $item);
        return $this->_count - 1;
    }

    /**
     * 移除最后的元素，并返回
     * @return mixed
     * @throws Exception
     */
    public function pop()
    {
        return $this->removeAt($this->_count - 1);
    }

    /**
     * 向列表头添加一个元素，成功返回添加的元素索引
     * @param mixed $item
     * @return int
     * @throws Exception
     */
    public function unshift($item)
    {
        $this->insertAt(0, $item);
        return 0;
    }

    /**
     * 移除第一个元素，并返回
     * @return mixed
     * @throws Exception
     */
    public function shift()
    {
        return $this->removeAt(0);
    }

    /**
     * 删除一个元素，返回元素在 list 中的索引，未找到返回 false
     * @param mixed $item
     * @return bool|int|mixed
     * @throws Exception
     */
    public function remove($item)
    {
        if (($index = $this->indexOf($item)) >= 0) {
            $this->removeAt($index);
            return $index;
        } else
            return false;
    }

    /**
     * 清除 list 的所有元素
     * @throws Exception
     */
    public function clear()
    {
        for ($i = $this->_count - 1; $i >= 0; $i--) {
            $this->removeAt($i);
        }
    }

    /**
     * Whether a offset exists
     * @link http://php.net/manual/en/arrayaccess.offsetexists.php
     * @param mixed $offset <p>
     * An offset to check for.
     * </p>
     * @return boolean true on success or false on failure.
     * </p>
     * <p>
     * The return value will be casted to boolean if non-boolean was returned.
     * @since 5.0.0
     */
    public function offsetExists($offset)
    {
        return ($offset >= 0 && $offset < $this->_count);
    }

    /**
     * Offset to retrieve
     * @link http://php.net/manual/en/arrayaccess.offsetget.php
     * @param mixed $offset <p>
     * The offset to retrieve.
     * </p>
     * @return mixed Can return all value types.
     * @since 5.0.0
     * @throws Exception
     */
    public function offsetGet($offset)
    {
        return $this->itemAt($offset);
    }

    /**
     * Offset to set
     * @link http://php.net/manual/en/arrayaccess.offsetset.php
     * @param mixed $offset <p>
     * The offset to assign the value to.
     * </p>
     * @param mixed $value <p>
     * The value to set.
     * </p>
     * @return void
     * @since 5.0.0
     * @throws Exception
     */
    public function offsetSet($offset, $value)
    {
        if (null === $offset || $offset === $this->_count) {
            $this->insertAt($this->_count, $value);
        } else {
            $this->removeAt($offset);
            $this->insertAt($offset, $value);
        }
    }

    /**
     * Offset to unset
     * @link http://php.net/manual/en/arrayaccess.offsetunset.php
     * @param mixed $offset <p>
     * The offset to unset.
     * </p>
     * @return void
     * @since 5.0.0
     * @throws Exception
     */
    public function offsetUnset($offset)
    {
        $this->removeAt($offset);
    }

    /**
     * Count elements of an object
     * @link http://php.net/manual/en/countable.count.php
     * @return int The custom count as an integer.
     * </p>
     * <p>
     * The return value is cast to an integer.
     * @since 5.1.0
     */
    public function count()
    {
        return $this->_count;
    }

    /**
     * Retrieve an external iterator
     * @link http://php.net/manual/en/iteratoraggregate.getiterator.php
     * @return Traversable An instance of an object implementing <b>Iterator</b> or
     * <b>Traversable</b>
     * @since 5.0.0
     */
    public function getIterator()
    {
        return new CListIterator($this->_data);
    }
}