Collections 集合

每当您的结果返回多个值时，就会返回一个Collection的实例。您可以迭代遍历这个实例，并且该实例还提供了大量的方法函数。

当使用集合作为查询结果时，您可以像使用普通列表的集合一样对其进行迭代：

users = User.get() #== <masoniteorm.collections.Collection>
users.count() #== 50
users.pluck('email') #== <masoniteorm.collections.Collection> of emails

for user in users:
  user.email #== 'joe@masoniteproject.com'

支持的方法/函数

all

返回整个集合列表或字典：

users = User.get().all() #== [<app.User.User>, <app.User.User>]

Collection([1, 2, 3]).all() #== [1, 2, 3]

avg

返回集合中所有项目的平均值：

Collection([1, 2, 3, 4, 5]).avg() #== 3

如果集合包含嵌套对象或字典(例如，对于模型集合)，您必须传递一个键来确定要计算平均值的值：

average_price = Product.get().avg('price')

chunk

将一个集合分成多个给定大小的较小集合。使用生成器使每个块保持较小。
使用分块处理大量数据集合时能够极大的提升处理性能，节约内存占用。

collection = Collection([1, 2, 3, 4, 5, 6, 7])
chunks = collection.chunk(2).serialize() #== [[1, 2], [3, 4], [5, 6], [7]]

collapse

将多维数组合并转化为一个一维数组：

collection = Collection([[1, 2, 3], [4, 5, 6]])
collection.collapse().serialize() #== [1, 2, 3, 4, 5, 6]

contains

判断集合中是否包含指定项

collection = Collection(['foo', 'bar'])
collection.contains('foo') #== True

您还可以向 contains 方法传递一个键/值对，该方法将确定给定的键/值对是否存在于集合中。

最后，您还可以将回调传递给 contains 方法以执行自己的真实性测试：

collection = Collection([1, 2, 3, 4, 5])
collection.contains(lambda item: item > 5) #== False

count

返回集合中的项目总数。标准python方法len()也可以使用。

diff

对比一个集合和另一个集合，返回集合间的差集。

collection = Collection([1, 2, 3, 4, 5])
diff = collection.diff([2, 4, 6, 8])
diff.all() #== [1, 3, 5]

each

遍历集合中的项目并将每个项目传递给给定的回调：

posts.each(lambda post: post.author().save(author))

every

遍历集合中的项目并将每个项目传递给给定的回调：

collection = Collection([1, 2, 3])
collection.every(lambda x: x*2 ).all() #== [2, 4, 6]

filter

通过判断指定的条件，过滤符合筛选条件的项目：

collection = Collection([1, 2, 3, 4])
filtered = collection.filter(lambda item: item > 2)
filtered.all() #== [3, 4]

first

通过判断指定的条件，返回集合中第一个通过给定真值测试的元素。
如果没有给出参数，则返回集合中的第一个元素：

collection = Collection([1, 2, 3, 4])
collection.first(lambda item: item > 2)

flatten

将多维集合展平为一维：

collection = Collection([1, 2, [3, 4, 5, {'foo': 'bar'}]])
flattened = collection.flatten().all() #== [1, 2, 3, 4, 5, 'bar']

forget

将通过指定的键来移除集合中对应的元素：

collection = Collection([1, 2, 3, 4, 5])
collection.forget(1).all() #== [1,3,4,5]
collection.forget(0,2).all() #== [3,5]

与大多数其他集合方法不同， forget 不会返回一个修改后的新集合；它会直接修改原集合。

for_page

for_page 返回一个含有指定页码数集合项的新集合。这个方法接受页码数作为其第一个参数，每页显示的项数作为其第二个参数:

collection = Collection([1, 2, 3, 4, 5, 6, 7, 8, 9])
chunk = collection.for_page(2, 4).all() #== 4, 5, 6, 7

for_page(page, count) 参数为页码和每页显示的项目数。

get

返回指定键的集合项，如果该键在集合中不存在，则返回 None，你还可以传递一个可选参数来作为默认返回值：

collection = Collection([1, 2, 3])
collection.get(0) #== 1
collection.get(4) #== None
collection.get(4, 'default') #== 'default'

collection = Collection({"apples": 1, "cherries": 2})
collection.get("apples") #== 1

group_by

根据指定键对集合项进行分组:

collection = Collection([
  {"id": 1, "type": "a"},
  {"id": 2, "type": "b"},
  {"id": 3, "type": "a"}
])
collection.implode("type").all()
#== {'a': [{'id': 1, 'type': 'a'}, {'id': 4, 'type': 'a'}],
#    'b': [{'id': 2, 'type': 'b'}]}

implode

使用指定的字符串将集合的值连接起来。

collection = Collection(['foo', 'bar', 'baz'])
collection.implode() #== foo,bar,baz
collection.implode('-') #== foo-bar-baz

如果集合包含字典或对象，则必须传递希望连接的属性的键：

collection = Collection([
    {'account_id': 1, 'product': 'Desk'},
    {'account_id': 2, 'product': 'Chair'}
])
collection.implode(key='product') #== Desk,Chair
collection.implode(" - ", key='product') #== Desk - Chair

is_empty

如果集合为空，则返回 True ；否则，返回 False：

Collection([]).is_empty() #== True

last

通过判断指定的条件，返回集合中最后一个通过给定真值测试的元素。

如果没有给出参数，则返回集合中的最后一个元素：

collection = Collection([1, 2, 3, 4])
last = collection.last(lambda item: item < 3) #== 2

map

遍历集合并将每个值传递给给定的回调。回调函数可以自由地修改项并返回它一个由修改项组成的新集合：

collection = Collection([1, 2, 3, 4])
multiplied = collection.map(lambda item: item * 2).all() #== [2, 4, 6, 8]

如果你想修改原集合，请使用 transform 方法。

map_into

遍历集合并将每个值强制转换为给定的类：

collection = Collection([1,2])
collection.map_into(str).all() #== ["1", "2"]

你还可以指定类方法。并将一些附加的参数传递给这个方法：

class Point:
    @classmethod
    def as_dict(cls, coords, one_dim=False):
        if one_dim:
            return {"X": coords[0]}
        return {"X": coords[0], "Y": coords[1]}

collection = Collection([(1,2), (3,4)])
collection.map_into(Point, "as_dict") #== [{'X': 1, 'Y': 2}, {'X': 3, 'Y': 4}]
collection.map_into(Point, "as_dict", one_dim=True) #== [{'X': 1}, {'X': 3}]

max

检索集合中的最大值：

collection = Collection([1,2,3])
collection.max() #== 3

如果集合包含字典或对象，则必须传递用于计算最大值的键：

collection = Collection([
    {'product_id': 1, 'product': 'Desk'},
    {'product_id': 2, 'product': 'Chair'}
    {'product_id': 3, 'product': 'Table'}
])
collection.max("product_id") #== 3

merge

将给定的列表合并到集合中：

collection = Collection(['Desk', 'Chair'])
collection.merge(['Bookcase', 'Door'])
collection.all() #== ['Desk', 'Chair', 'Bookcase', 'Door']

与大多数集合的方法不同的是， merge 不会返回修改后的新集合；它会直接修改原集合。

pluck

获取集合中指定键对应的所有值：

collection = Collection([
    {'product_id': 1, 'product': 'Desk'},
    {'product_id': 2, 'product': 'Chair'}
    {'product_id': 3, 'product': None}
])

plucked = collection.pluck('product').all() #== ['Desk', 'Chair', None]

可以指定一个键，以使用指定的键将集合提取到词典中

collection.pluck("product", "product_id") #== {1: 'Desk', 2: 'Chair', 3: None}

您可以传递 keep_nulls=False 来删除集合中的 None 值。

collection.pluck("product", keep_nulls=False) #== ['Desk', 'Chair']

pop

删除并返回集合中的最后一项：

collection = Collection([1, 2, 3, 4, 5])
collection.pop() #== 5
collection.all() #== [1, 2, 3, 4]

prepend

将一个元素添加到集合的开头：

collection = Collection([1, 2, 3, 4])
collection.prepend(0)
collection.all() #== [0, 1, 2, 3, 4]

pull

通过指定的键从集合中移除并返回一个元素：

collection = Collection([1, 2, 3, 4])
collection.pull(1) #== 2
collection.all() #== [1, 3, 4]

collection = Collection({'apple': 1, 'cherry': 3, 'lemon': 2})
collection.pull('cherry') #== 3
collection.all() #== {'apple': 1, 'lemon': 2}

push

将一个元素附加到集合的末尾：

collection = Collection([1, 2, 3, 4])
collection.push(5)
collection.all() #== [1, 2, 3, 4, 5]

put

设置集合指定键对应的值：

collection = Collection([1, 2, 3, 4])
collection.put(1, 5)
collection.all() #== [1, 5, 3, 4]

collection = Collection({'apple': 1, 'cherry': 3, 'lemon': 2})
collection.put('cherry', 0)
collection.all() #== {'apple': 1, 'cherry': 0, 'lemon': 2}

random

从集合中返回一个随机项

user = User.all().random() #== returns a random User instance

你可以将一个整数传递给 random ，以指定要随机检索的项目数。当指定项目数时，将始终返回一个集合：

users = User.all().random(3) #== returns a Collection of 3 users
users.count() #== 3
users.all() #== returns a list of 3 users

如果集合长度小于指定的计数， random 方法将会抛出 ValueError 异常

reduce

将集合减少为单个值，将每次迭代的结果传递给后续迭代。

collection = Collection([1, 2, 3])
collection.reduce(lambda result, item: (result or 0) + item) #== 6

初始值默认为 0，但可以重写：

collection.reduce(lambda result, item: (result or 0) + item, 4) #== 10

reject

它与 filter 方法相反。它使用指定的回调过滤集合。如果应从结果集合中删除项目，则回调应返回 True ：

collection = Collection([1, 2, 3, 4])
filtered = collection.reject(lambda item: item > 2)
filtered.all() #== [1, 2]

与大多数集合的方法不同的是， reject 不会返回修改后的新集合；它会直接修改原集合。

reverse

反转集合项目排序：

collection = Collection([1, 2, 3])
collection.reverse().all() #== [3, 2, 1]

与大多数集合的方法不同的是， reverse 不会返回修改后的新集合；它会直接修改原集合。

serialize

将集合转换为 list。如果集合值为 ORM 模型 ，该模型将转换为字典：

collection = Collection([1, 2, 3])
collection.serialize() #== [1, 2, 3]

collection = Collection([User.find(1)])
collection.serialize() #== [{'id': 1, 'name': 'John', 'email': 'john.doe@masonite.com'}]

serialize 也会转换嵌套的对象，如果你想按原样获取，请使用 all 方法。

shift

从集合中移除并返回第一项：

collection = Collection([1, 2, 3, 4, 5])
collection.shift() #== 1
collection.all() #== [2, 3, 4, 5]

sort

对集合进行排序：

collection = Collection([5, 3, 1, 2, 4])
sorted = collection.sort()
sorted.all() #== [1, 2, 3, 4, 5]

sum

返回集合中所有项目的总和：

Collection([1, 2, 3, 4, 5]).sum() #== 15

如果集合包含字典或对象，则必须指定一个键来确定要对哪些值求和：

collection = Collection([
    {'name': 'JavaScript: The Good Parts', 'pages': 176},
    {'name': 'JavaScript: The Defnitive Guide', 'pages': 1096}
])
collection.sum('pages') #== 1272

take

返回具有指定项目数的新集合：

collection = Collection([0, 1, 2, 3, 4, 5])
chunk = collection.take(3)
chunk.all() #== [0, 1, 2]

您还可以传递一个负整数以从集合末尾获取指定数量的项目：

chunk = collection.chunk(-2)
chunk.all() #== [4, 5]

to_json

将集合转换为 JSON 类型：

collection = Collection([{'name': 'Desk', 'price': 200}])
collection.to_json() #== '[{"name": "Desk", "price": 200}]'

transform

迭代集合并将集合中的每个元素作为参数调用指定的回调函数。返回的值会替换原有的值：

collection = Collection([1, 2, 3, 4, 5])
collection.transform(lambda item: item * 2)
collection.all() #== [2, 4, 6, 8, 10]

transform 修改集合自身。如果你想生成新的集合，请使用 map 方法。

unique

返回集合中的唯一元素：

collection = Collection([1, 1, 2, 2, 3, 4, 2])
unique = collection.unique()
unique.all() #== [1, 2, 3, 4]

当集合内部为字典或者对象时，可以指定键值来决定唯一性：

collection = Collection([
    {'name': 'Sam', 'role': 'admin'},
    {'name': 'Joe', 'role': 'basic'},
    {'name': 'Joe', 'role': 'admin'},
])
unique = collection.unique('name')
unique.all()
# [
#     {'name': 'Sam', 'role': 'admin'},
#     {'name': 'Joe', 'role': 'basic'}
# ]

where

使用指定的键值对过滤集合：

collection = Collection([
    {'name': 'Desk', 'price': 200},
    {'name': 'Chair', 'price': 100},
    {'name': 'Bookcase', 'price': 150},
    {'name': 'Door', 'price': 100},
])
filtered = collection.where('price', 100)
filtered.all()
# [
#     {'name': 'Chair', 'price': 100},
#     {'name': 'Door', 'price': 100}
# ]

zip

将给定列表的值与对应索引处的集合值合并成键值对：

collection = Collection(['Chair', 'Desk'])
zipped = collection.zip([100, 200])
zipped.all() #== [('Chair', 100), ('Desk', 200)]

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/masonite/4.0/or...

译文地址：https://learnku.com/docs/masonite/4.0/or...