starred/pkl
1
0
Fork 0
mirror of https://github.com/apple/pkl.git synced 2026-03-22 00:59:17 +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}]