README

#Readme

##可枚举实用工具

可枚举实用工具库提供了一个方便的方式来操作集合。此库包含：

• 一个使用Enumerable的String类，增加了更多精彩的方法
• 一个帮助你快速利用Enumerable的Collection类
• 一个索引过的Collection的Dictionary类
• 一个如果你不喜欢String类的话，可以使用的StringUtility类

它受到了.NET框架中Linq可枚举类扩展的启发。

##安装

您需要在PHP 5.4下运行。

您可以简单地下载源代码或使用composer获取包。

快速概览

大多数时候，您将仅使用Collection类来处理大多数用例

<?php

use BCC\EnumerableUtility\Collection;

$values = new Collection(array(1, 2, 3));

// gets event/odd values
$values->where(function($item) { return $item % 2; });

// project the squared values
$values->select(function($item) { return $item*$item; });

// order
$values->orderByDescending();

// paginate
$values->skip(30)->take(10);

Enumerable函数

以下是当前实现的功能列表

• aggregate: 对元素应用累加函数
• all: 对每个元素验证闭包，如果全部匹配则返回true
• any: 对每个元素验证闭包，如果至少有一个匹配则返回true
• average: 计算元素的平均值
• contains: 告诉元素是否包含在可枚举中
• count: 计数元素数量
• distinct: 将元素集合减少到不同的元素
• each: 将闭包应用于元素集合，您可以安全地通过引用获取项目
• elementAt: 获取指定位置的元素
• first: 获取第一个元素，可以使用闭包
• groupBy: 按组对元素进行分组
• join: 根据匹配的键关联两个集合的元素
• last: 获取第一个元素，可以使用闭包
• max: 获取具有最大值的元素
• min: 获取具有最小值的元素
• orderBy: 对元素进行排序，可以添加副排序
• orderByDescending: 以降序对元素进行排序
• reverse: 反转元素顺序
• select: 投影每个元素
• selectMany: 投影每个元素并展平结果
• skip: 跳过指定数量的元素
• skipWhile: 在闭包满足条件时跳过元素
• sum: 计算元素的总和
• take: 选取指定数量的元素
• takeWhile: 在闭包满足条件时选取元素
• thenBy: 添加子排序
• thenByDescending: 添加子降序排序
• toDictionary: 将可枚举转换为字典
• where: 使用闭包减少元素集合

注意，当适用时，函数返回调用类的实例。

函数的使用

有时，您只想指定单个属性，然后是一个完整的闭包

<?php

$values->select(function($item) { return $item->address; });

希望有一个函数解析器机制，允许您缩短您的语法。

您可以简单地提供一个属性路径到您想要选择的字段

<?php

$values->select('address');

注意，字符串属性也支持

• 链式操作：address.city
• 数组遍历：phoneNumbers[2]
• 自动发现getter/haser/isser

属性路径来自symfony/property-access库。

您也可以提供一个表示表达式的数组

<?php

// select a path
$values->select(['i' => 'i.address');

// select the square
$values->average(['i' => 'i * i');

// select a multiplication by a variable
$values->select([
    'i' => 'i * m',
    'm' => 2,
]);

表达式来自symfony/expression-language库。

Collection类

在成为可枚举的背后，Collection有一些有用的函数

• add: 向集合添加项目
• addRange: 向集合中添加一组项目
• clear: 清空集合
• indexOf: 获取项目的元素
• insert: 在指定索引处插入元素
• remove: 删除项目
• removeAt: 删除指定索引处的元素

Dictionary 类

除了是可枚举的之外，Dictionary 类还有一些有用的函数

• keys: 获取键
• values: 获取值
• add: 使用给定的键添加项目
• clear: 清空字典
• containsKey: 验证键是否被使用
• containsValue: 验证值是否包含
• remove: 删除指定键的项目
• tryGetValue: 尝试获取指定键的值

String 类

String 类也是一个 Enumerable（理解为字符的可枚举），但它也添加了一些有用的方法。

这些灵感来源于.NET框架中的String类

• contains: 测试与给定字符串的匹配，可以是大小写不敏感的
• endsWith: 测试与给定字符串的匹配，可以是大小写不敏感的
• startsWith: 测试与给定字符串的匹配，可以是大小写不敏感的
• equals: 测试与给定字符串的匹配，可以是大小写不敏感的
• 静态 format: 对应于 sprintf
• indexOf: 获取给定字符串的索引，可以是大小写不敏感的
• insert: 在指定位置插入另一个字符串
• 静态 isNullOrEmpty: 测试给定的字符串是否为null或空
• 静态 isNullOrWhiteSpace: 测试给定的字符串是否为null或空白
• 静态 concatenate: 使用给定的分隔符连接字符串数组
• lastIndexOf: 获取给定字符串的最后一个索引，可以是大小写不敏感的
• padLeft: 填充字符串的左侧以匹配给定的长度，填充字符可以定义
• padRight: 填充字符串的右侧以匹配给定的长度，填充字符可以定义
• remove: 删除字符串的一部分
• replace: 替换字符串中的给定序列
• split: 使用给定分隔符分割字符串
• subString: 提取字符串的一部分
• toLower: 将字符串转换为小写
• toUpper: 将字符串转换为大写
• toCharArray: 转换为字符数组
• trim: 去除字符串，可以定义去除的字符
• trimEnd: 去除字符串的末尾，可以定义去除的字符
• trimStart: 去除字符串的开始部分，可以定义去除的字符

你现在可以这样做

<?php

use BCC\EnumerableUtility\String;

$string = new String('Hello world!');

$string = $string->replace('world', 'pineapple')       // replace world by pineapple
       ->toUpper()                                     // to upper case
       ->skip(6)                                       // skip the 6 first letters
       ->takeWhile(function($char) { $char != '!'; }); // take the rest while the char is different from '!'

echo $string; // PINEAPPLE

StringUtility 类

如果你不喜欢使用 String 类，你可以通过 StringUtility 类来访问所有的功能。它所做的一切只是内部将静态调用映射到 String 类

<?php

use \BCC\EnumerableUtility\StringUtility;

$string = 'Hello world!';

$string = StringUtility::replace  ($string, 'world', 'pineapple');              // replace world by pineapple
$string = StringUtility::toUpper  ($string);                                    // to upper case
$string = StringUtility::skip     ($string, 6);                                 // skip the 6 first letters
$string = StringUtility::takeWhile($string, function($char) { $char != '!'; }); // take the rest while the char is different from '!'

echo $string; // PINEAPPLE