azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document functions which return set or map preserving the order of elements/entries.

Browse Source 
#KT-11632 Fixed
This commit is contained in:
Ilya Gorbunov
2016-05-05 15:21:02 +03:00
parent b5e5c6f4d0
commit d646afabb2
11 changed files with 326 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt
+63 -10
View File
@@ -10,7 +10,12 @@ fun generators(): List<GenericFunction> {
only(Iterables, Collections, Sets, Sequences)
doc { "Returns a list containing all elements of the original collection and then the given [element]." }
doc(Sets) { "Returns a set containing all elements of the original set and then the given [element]." }
doc(Sets) {
"""
Returns a set containing all elements of the original set and then the given [element] if it isn't already in this set.
The returned set preserves the element iteration order of the original set.
"""
}
doc(Sequences) { "Returns a sequence containing all elements of the original sequence and then the given [element]." }
returns("List<T>")
@@ -45,7 +50,12 @@ fun generators(): List<GenericFunction> {
// TODO: use build scope function when available
// TODO: use immutable sets when available
returns("SELF", Sets, Sequences)
doc(Sets) { "Returns a set containing all elements of the original set and then the given [element]." }
doc(Sets) {
"""
Returns a set containing all elements of the original set and then the given [element] if it isn't already in this set.
The returned set preserves the element iteration order of the original set.
"""
}
body(Sets) {
"""
val result = LinkedHashSet<T>(mapCapacity(size + 1))
@@ -95,7 +105,13 @@ fun generators(): List<GenericFunction> {
}
// TODO: use immutable set builder when available
doc(Sets) { "Returns a set containing all elements both of the original set and the given [elements] collection." }
doc(Sets) {
"""
Returns a set containing all elements of the original set and the given [elements] collection,
which aren't already in this set.
The returned set preserves the element iteration order of the original set.
"""
}
body(Sets) {
"""
val result = LinkedHashSet<T>(mapCapacity(elements.collectionSizeOrNull()?.let { this.size + it } ?: this.size * 2))
@@ -144,7 +160,13 @@ fun generators(): List<GenericFunction> {
return result
"""
}
doc(Sets) { "Returns a set containing all elements both of the original set and the given [elements] array." }
doc(Sets) {
"""
Returns a set containing all elements of the original set and the given [elements] array,
which aren't already in this set.
The returned set preserves the element iteration order of the original set.
"""
}
body(Sets) {
"""
val result = LinkedHashSet<T>(mapCapacity(this.size + elements.size))
@@ -194,7 +216,13 @@ fun generators(): List<GenericFunction> {
}
// TODO: use immutable set builder when available
doc(Sets) { "Returns a set containing all elements both of the original set and the given [elements] sequence." }
doc(Sets) {
"""
Returns a set containing all elements of the original set and the given [elements] sequence,
which aren't already in this set.
The returned set preserves the element iteration order of the original set.
"""
}
body(Sets) {
"""
val result = LinkedHashSet<T>(mapCapacity(this.size * 2))
@@ -224,7 +252,12 @@ fun generators(): List<GenericFunction> {
only(Iterables, Sets, Sequences)
doc { "Returns a list containing all elements of the original collection without the first occurrence of the given [element]." }
doc(Sets) { "Returns a set containing all elements of the original set except the given [element]." }
doc(Sets) {
"""
Returns a set containing all elements of the original set except the given [element].
The returned set preserves the element iteration order of the original set.
"""
}
doc(Sequences) { "Returns a sequence containing all elements of the original sequence without the first occurrence of the given [element]." }
returns("List<T>")
@@ -247,7 +280,12 @@ fun generators(): List<GenericFunction> {
}
returns("SELF", Sets, Sequences)
doc(Sets) { "Returns a set containing all elements of the original set except the given [element]." }
doc(Sets) {
"""
Returns a set containing all elements of the original set except the given [element].
The returned set preserves the element iteration order of the original set.
"""
}
body(Sets) {
"""
val result = LinkedHashSet<T>(mapCapacity(size))
@@ -288,7 +326,12 @@ fun generators(): List<GenericFunction> {
"""
}
doc(Sets) { "Returns a set containing all elements of the original set except the elements contained in the given [elements] collection." }
doc(Sets) {
"""
Returns a set containing all elements of the original set except the elements contained in the given [elements] collection.
The returned set preserves the element iteration order of the original set.
"""
}
body(Sets) {
"""
val other = elements.convertToSetForSetOperationWith(this)
@@ -340,7 +383,12 @@ fun generators(): List<GenericFunction> {
return this.filterNot { it in other }
"""
}
doc(Sets) { "Returns a set containing all elements of the original set except the elements contained in the given [elements] array." }
doc(Sets) {
"""
Returns a set containing all elements of the original set except the elements contained in the given [elements] array.
The returned set preserves the element iteration order of the original set.
"""
}
body(Sets) {
"""
val result = LinkedHashSet<T>(this)
@@ -386,7 +434,12 @@ fun generators(): List<GenericFunction> {
return this.filterNot { it in other }
"""
}
doc(Sets) { "Returns a set containing all elements of the original set except the elements contained in the given [elements] sequence." }
doc(Sets) {
"""
Returns a set containing all elements of the original set except the elements contained in the given [elements] sequence.
The returned set preserves the element iteration order of the original set.
"""
}
body(Sets) {
"""
val result = LinkedHashSet<T>(this)
libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt
+2
View File
@@ -294,6 +294,7 @@ fun mapping(): List<GenericFunction> {
"""
Groups ${f.element.pluralize()} of the original ${f.collection} by the key returned by the given [keySelector] function
applied to each ${f.element} and returns a map where each group key is associated with a list of corresponding ${f.element.pluralize()}.
The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}.
@sample test.collections.CollectionTest.groupBy
"""
}
@@ -339,6 +340,7 @@ fun mapping(): List<GenericFunction> {
Groups values returned by the [valueTransform] function applied to each ${f.element} of the original ${f.collection}
by the key returned by the given [keySelector] function applied to the ${f.element}
and returns a map where each group key is associated with a list of corresponding values.
The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}.
@sample test.collections.CollectionTest.groupByKeysAndValues
"""
}
libraries/tools/kotlin-stdlib-gen/src/templates/Sets.kt
+26 -5
View File
@@ -7,7 +7,12 @@ fun sets(): List<GenericFunction> {
templates add f("toMutableSet()") {
exclude(Strings)
doc { f -> "Returns a mutable set containing all distinct ${f.element.pluralize()} from the given ${f.collection}." }
doc { f ->
"""
Returns a mutable set containing all distinct ${f.element.pluralize()} from the given ${f.collection}.
The returned set preserves the element iteration order of the original ${f.collection}.
"""
}
returns("MutableSet<T>")
body {
"""
@@ -24,7 +29,6 @@ fun sets(): List<GenericFunction> {
return set
"""
}
doc(Sequences) { "Returns a mutable set containing all distinct elements from the given sequence." }
body(Sequences) {
"""
val set = LinkedHashSet<T>()
@@ -90,7 +94,14 @@ fun sets(): List<GenericFunction> {
templates add f("union(other: Iterable<T>)") {
infix(true)
exclude(Strings, Sequences)
doc { "Returns a set containing all distinct elements from both collections." }
doc { f ->
"""
Returns a set containing all distinct elements from both collections.
The returned set preserves the element iteration order of the original ${f.collection}.
Those elements of the [other] collection that are unique are iterated in the end
in the order of the [other] collection.
"""
}
returns("Set<T>")
body {
"""
@@ -104,7 +115,12 @@ fun sets(): List<GenericFunction> {
templates add f("intersect(other: Iterable<T>)") {
infix(true)
exclude(Strings, Sequences)
doc { "Returns a set containing all elements that are contained by both this set and the specified collection." }
doc { f ->
"""
Returns a set containing all elements that are contained by both this set and the specified collection.
The returned set preserves the element iteration order of the original ${f.collection}.
"""
}
returns("Set<T>")
body {
"""
@@ -118,7 +134,12 @@ fun sets(): List<GenericFunction> {
templates add f("subtract(other: Iterable<T>)") {
infix(true)
exclude(Strings, Sequences)
doc { "Returns a set containing all elements that are contained by this set and not contained by the specified collection." }
doc { f ->
"""
Returns a set containing all elements that are contained by this ${f.collection} and not contained by the specified collection.
The returned set preserves the element iteration order of the original ${f.collection}.
"""
}
returns("Set<T>")
body {
"""
libraries/tools/kotlin-stdlib-gen/src/templates/Snapshots.kt
+9 -1
View File
@@ -21,7 +21,12 @@ fun snapshots(): List<GenericFunction> {
}
templates add f("toSet()") {
doc { f -> "Returns a [Set] of all ${f.element.pluralize()}." }
doc { f ->
"""
Returns a [Set] of all ${f.element.pluralize()}.
The returned set preserves the element iteration order of the original ${f.collection}.
"""
}
returns("Set<T>")
body(Iterables) {
"""
@@ -168,6 +173,7 @@ fun snapshots(): List<GenericFunction> {
Returns a [Map] containing key-value pairs provided by [transform] function
applied to ${f.element.pluralize()} of the given ${f.collection}.
If any of two pairs would have the same key the last one gets added to the map.
The returned map preserves the entry iteration order of the original ${f.collection}.
"""
}
body {
@@ -231,6 +237,7 @@ fun snapshots(): List<GenericFunction> {
Returns a [Map] containing the ${f.element.pluralize()} from the given ${f.collection} indexed by the key
returned from [keySelector] function applied to each ${f.element}.
If any two ${f.element.pluralize()} would have the same key returned by [keySelector] the last one gets added to the map.
The returned map preserves the entry iteration order of the original ${f.collection}.
"""
}
returns("Map<K, T>")
@@ -301,6 +308,7 @@ fun snapshots(): List<GenericFunction> {
"""
Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to ${f.element.pluralize()} of the given ${f.collection}.
If any two ${f.element.pluralize()} would have the same key returned by [keySelector] the last one gets added to the map.
The returned map preserves the entry iteration order of the original ${f.collection}.
"""
}
returns("Map<K, V>")