README

Data-structure

一套用于不可变数据操作的实用类。

• 安装指南
• 示例
• 贡献

安装

使用 Composer 安装包

composer require miquido/data-structure

或直接将此行添加到您的 composer.json 文件中

"miquido/data-structure": "dev-master"

示例

• Map
• MapCollection
• StringCollection
• IntegerCollection
• NumberCollection
• ObjectCollection
• Value
• ScalarValue
• StringValue
• NumberValue
• CollectionValue

重要！所有类中的所有方法都是不可变的 - 它们不会修改对象的内部状态，而是返回一个新的类实例，具有新的状态。

Map

关联数组的不可变包装。

<?php

use Miquido\DataStructure\Map\Map;

$map = new Map(['name' => 'John', 'surname' => 'Smith', 'age' => 30]);
$map->count(); // 3
$map->has('name'); // true
$map->hasAll('name', 'email'); // false
$map->hasOneOf('name', 'email'); // true
$map->get('name'); // 'John'
$map->keys(); // new StringCollection('name', 'surname', 'age')
$map->values(); // ['John', 'Smith', 30]
$map->toArray(); // ['name' => 'John', 'surname' => 'Smith', 'age' => 30]

// remove() returns new Map without provided keys,
// in example below: new Map(['surname' => 'Smith'])
$map->remove('age', 'name');

// set() returns new Map(['name' => 'John', 'surname' => 'Smith', 'age' => 30, 'email' => 'john@smith'])
// if key already exists set() overwrites current value 
$map->set('email', 'john@smith');

// pick() creates new Map with selected keys
$map->pick('name', 'age'); // new Map(['name' => 'John', 'age' => 30])

// filterByKeys() returns new Map with values for which callback returns true
// similar methods: filter() and filterByKeys()
$map->filterByKeys(function (string $key): bool { 
    return \strpos($key, 'name') !== false; 
});

查看所有可用方法，请参阅 Miquido\DataStructure\Map\MapInterface

MapCollection

<?php

use Miquido\DataStructure\Map\MapCollection;
use Miquido\DataStructure\Map\Map;
use Miquido\DataStructure\Map\MapInterface;

$user1 = new Map(['id' => 1, 'name' => 'John']);
$user2 = new Map(['id' => 2, 'name' => 'James']);

$collection = new MapCollection($user1, $user2);
$collection->count(); // 2
$collection->getAll(); // [$user1, $user2]
$collection->toArray(); // [['id' => 1, 'name' => 'John'], ['id' => 2, 'name' => 'James']]

// map() transforms all items in collection via callback
// in example below: map() creates new MapCollection containing Map objects with capitalized names 
$collection->map(function (MapInterface $user): MapInterface {
    return $user->set('name', $user->getValue('name')->toStringValue()->toUpper());
});

// filter() returns new MapCollection with Map objects  for which callback returns true
$collection->filter(function (MapInterface $user): bool {
    return $user->getValue('id')->int() > 1;
});

// return first matching Map object, or throws Miquido\DataStructure\Exception\ItemNotFoundException  
$collection->find(function (MapInterface $user): bool {
    return $user->getValue('id')->int() > 1; 
});

查看所有可用方法，请参阅 Miquido\DataStructure\Map\MapCollectionInterface

StringCollection

表示包含一些有用方法的字符串数组。

<?php

use Miquido\DataStructure\TypedCollection\StringCollection;

$strings = new StringCollection('lorem', 'ipsum', 'dolor');
$strings->count(); // 3
$strings->includes('ipsum'); // true
$strings->join('-'); // 'lorem-ipsum-dolor'
$strings->values(); // ['lorem', 'ipsum', 'dolor']

// all methods below return new StringCollection with modified state 
$strings->push('sit', 'amet'); // new StringCollection('lorem', 'ipsum', 'dolor', 'sit', 'amet')
$strings->remove('ipsum', 'lorem'); // new StringCollection('dolor')
$strings->map('strrev'); // new StringCollection('merol', 'muspi', 'rolod')
$strings->toLowerCaseAll(); // alias to $strings->map('mb_strtolower')  
$strings->toUpperCaseAll(); // alias to $strings->map('mb_strtoupper')  
$strings->trimAll(); // alias to $strings->map('trim')  

查看所有可用方法，请参阅 Miquido\DataStructure\TypedCollection\StringCollectionInterface

IntegerCollection

表示包含一些有用方法的整数数组。

<?php

use Miquido\DataStructure\TypedCollection\IntegerCollection;

$integers = new IntegerCollection(1, 1, 2, 2);
$integers->count(); // 4
$integers->values(); // [1, 1, 2, 2]
$integers->includes(1); // true
$integers->push(3); // new IntegerCollection(1, 1, 2, 2, 3)
$integers->unique(); // new IntegerCollection(1, 2)

查看所有可用方法，请参阅 Miquido\DataStructure\TypedCollection\IntegerCollectionInterface

NumberCollection

类似于 IntegerCollection，但也允许浮点数。

<?php

use Miquido\DataStructure\TypedCollection\NumberCollection;

$integers = new NumberCollection(1.1, 1.2, 2.1, 2.1);
$integers->count(); // 4
$integers->values(); // [1.1, 1.2, 2.1, 2.1]
$integers->includes(1.1); // true
$integers->push(3.5); // new NumberCollection(1.1, 1.2, 2.1, 2.1, 3.5)
$integers->unique(); // new NumberCollection(1.1, 1.2, 2.1)

查看所有可用方法，请参阅 Miquido\DataStructure\TypedCollection\NumberCollectionInterface

ObjectCollection

<?php

use Miquido\DataStructure\TypedCollection\ObjectCollection;

class User 
{
    public $id;
    public $name;
    
    public function __construct(int $id, string $name) 
    {
        $this->id = $id;
        $this->name = $name;
    }
}

$user1 = new User(1, 'John');
$user2 = new User(2, 'James');
$collection = new ObjectCollection($user1, $user2);
$collection->count(); // 2
$collection->getAll(); // [$user1, $user2]

// returns new Map(['john' => $user1, 'james' => $user2]) 
$collection->toMap(function (User $user): string {
    // callback has to provide a unique key for each object
    return \strtolower($user->name);
});

查看所有可用方法，请参阅 Miquido\DataStructure\TypedCollection\ObjectCollectionInterface

Value

表示混合值，当你的数据来自未知来源且你想获取特定数据类型时很有用。

请参阅以下示例

<?php

use Miquido\DataStructure\Value\Value;

$value = new Value('lorem ipsum');
$value->getRawValue(); // 'lorem ipsum'
$value->string(); // 'lorem ipsum'
$value->toScalarValue(); // new ScalarValue('lorem ipsum')
$value->toStringValue(); // new StringValue('lorem ipsum')
$value->toCollectionValue(); // new CollectionValue(['lorem ipsum'])

<?php

use Miquido\DataStructure\Value\Value;

$value = new Value(1537791526);
$value->string(); // '1537791526'
$value->int(); // 1537791526
$value->toNumberValue(); // new NumberValue(1537791526)
$value->dateTime()->format('Y-m-d'); // '2018-09-24'

它还可以解析字符串到布尔值

<?php

use Miquido\DataStructure\Value\Value;

$value = new Value('false');
$value->bool(); // string parsing is enabled by default, false - string is parsed, so 'false' 'no' 'null' or '0' are casted to false
$value->bool(false); // when string parsing is disabled it will return true - because 'false' is not an empty string

<?php

use Miquido\DataStructure\Value\Value;

$value = new Value(['lorem', 'ipsum']);
$value->toCollectionValue()->strings(); // new StringCollection('lorem', 'ipsum')

查看所有可用方法，请参阅 Miquido\DataStructure\Value\ValueInterface

CollectionValue

类似于 Value，但其接口仅限于对多个值的操作。

查看所有可用方法，请参阅 Miquido\DataStructure\Value\Collection\CollectionValueInterface

ScalarValue

类似于 Value，但其接口仅限于对标量值的操作。

查看所有可用方法，请参阅 Miquido\DataStructure\Value\Scalar\ScalarValueInterface

StringValue

将字符串封装到具有一些有用方法的对象中。

<?php

use Miquido\DataStructure\Value\Scalar\String\StringValue;

$string = new StringValue('lorem ipsum');
$string->get(); // returns raw string
$string->toUpper()->get(); // 'LOREM IPSUM'
$string->split(' ')->values(); // ['lorem', 'ipsum']

// map() returns new StringValue with a string returned from a callback
$string->map(function (string $value): string {
    return strrev($value);
});
$string->map('strrev'); // alternative way to write a callback

查看所有可用方法，请参阅 Miquido\DataStructure\Value\Scalar\String\StringValueInterface

NumberValue

将数字封装到对象中。

<?php

use Miquido\DataStructure\Value\Scalar\Number\NumberValue;

$number = new NumberValue(-1);
$number->float(); // cast to float
$number->int(); // cast to int

// map() returns new NumberValue(1)
$number->map(function (float $value): float {
    return abs($value);
});

查看所有可用方法，请参阅 Miquido\DataStructure\Value\Scalar\Number\NumberValueInterface

贡献

欢迎提交拉取请求、修复错误和问题报告。在提出更改之前，请通过创建问题来讨论您的更改。