starred/pkl
1
0
Fork 0
mirror of https://github.com/apple/pkl.git synced 2026-03-23 09:31:06 +01:00
Code Issues 198 Packages Projects Releases 10 Wiki Activity

Improve documentation about Set/Map ordering (#944)

Browse Source 
The language reference and stdlib are both slightly incorrect;
maps and sets are ordered when iterated on, but unordered in terms of
equality.
This commit is contained in:
Daniel Chao
2025-02-12 06:43:51 -08:00
committed by GitHub
parent 7ed710c226
commit 7c3f8ad261
2 changed files with 41 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/modules/language-reference/pages/index.adoc
View File

@@ -3539,9 +3539,7 @@ res6 = list.map((n) -> n * 3) // <6>
[[sets]]
=== Sets
A value of type link:{uri-stdlib-Set}[Set] is an ordered collection of unique _elements_.
A set's elements are eagerly evaluated.
A value of type link:{uri-stdlib-Set}[Set] is a collection of unique _elements_.
Sets are constructed with the `Set()` methodfootnote:soft-keyword[]:
@@ -3557,6 +3555,20 @@ res4 = Set(1, "x", 5.min, List(1, 2, 3)) // <4>
<3> result: same set of length 3
<4> result: heterogeneous set that contains a list as its last element
Sets retain the order of elements when constructed, which impacts how they are iterated over.
However, this order is not considered when determining equality of two sets.
[source%tested,{pkl}]
----
res1 = Set(4, 3, 2)
res2 = res1.first // <1>
res3 = res1.toListing() // <2>
res4 = Set(2, 3, 4) == res1 // <3>
----
<1> result: `4`
<2> result: `new Listing { 4; 3; 2 }`
<3> result: `true`
To compute the union of sets, use the `+` operator:
[source%tested,{pkl-expr}]
@@ -3584,7 +3596,7 @@ res4 = set.intersect(Set(3, 9, 2)) // <4>
[[maps]]
=== Maps
A value of type link:{uri-stdlib-Map}[Map] is an ordered collection of _values_ indexed by _key_.
A value of type link:{uri-stdlib-Map}[Map] is a collection of _values_ indexed by _key_.
A map's key-value pairs are called its _entries_.
Keys and values are eagerly evaluated.
@@ -3619,6 +3631,20 @@ Any Pkl value can be used as a map key:
Map(new Dynamic { name = "Pigeon" }, 10.gb)
----
Maps retain the order of entries when constructed, which impacts how they are iterated over.
However, this order is not considered when determining equality of two maps.
[source%tested,{pkl}]
----
res1 = Map(2, "hello", 1, "world")
res2 = res1.entries.first // <1>
res3 = res1.toMapping() // <2>
res4 = res1 == Map(1, "world", 2, "hello") // <3>
----
<1> result: `Pair(2, "hello")`
<2> result: `new Mapping { [2] = "hello"; [1] = "world" }`
<3> result: `true`
To merge maps, use the `+` operator:
[source%tested,{pkl}]

14
stdlib/base.pkl
View File

@@ -1,5 +1,5 @@
//===----------------------------------------------------------------------===//
// Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
// Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
@@ -3040,7 +3040,11 @@ external class List<out Element> extends Collection<Element> {
/// ```
external const function Set<Element>(elements: VarArgs<Element>): Set<Element>
/// An unordered collection of unique elements.
/// A collection of unique elements.
///
/// Sets retain the order of elements when constructed, which affects the how they are iterated
/// over.
/// However, ordering does not affect equality between two sets.
///
/// The following operators are supported for sets:
/// ```
@@ -3174,7 +3178,11 @@ external class Set<out Element> extends Collection<Element> {
/// ```
external const function Map<Key, Value>(keysAndValues: VarArgs<Key|Value>): Map<Key, Value>
/// An unordered mapping from keys to values.
/// A mapping from keys to values.
///
/// Maps retain the order of entries when constructed, which affects the how they are iterated
/// over.
/// However, ordering of entries does not affect equality between two maps.
///
/// The following operators are supported for maps:
/// ```