| Return type | Name and parameters |
|---|---|
boolean | any(Closure predicate)Iterates over the entries of a map, and checks whether a predicate isvalid for at least one entry. |
boolean | asBoolean()Coerce a map instance to a boolean value. |
Map | asImmutable()A convenience method for creating an immutable Map. |
Map | asSynchronized()A convenience method for creating a synchronized Map. |
Object | asType(Class clazz)Coerces this map to the given type, using the map's keys as the publicmethod names, and values as the implementation. |
Map | asUnmodifiable()Creates an unmodifiable view of a Map. |
List | collect(Closure transform)Iterates through this Map transforming each map entry into a new value using the transform closurereturning a list of transformed values. |
Object | collect(Object collector,Closure transform)Iterates through this Map transforming each map entry into a new value using the transform closurereturning thecollector with all transformed values added to it. |
Map | collectEntries(Closure transform)Iterates through this Map transforming each entry using the transform closureand returning a map of the transformed entries. |
Map | collectEntries(Map collector,Closure transform)Iterates through this Map transforming each map entry using the transform closurereturning a map of the transformed entries. |
List | collectMany(Closure projection)Projects each item from a source map to a result collection and concatenates (flattens) the resultingcollections adding them into a collection. |
Object | collectMany(Object collector,Closure projection)Projects each item from a source map to a result collection and concatenates (flattens) the resultingcollections adding them into the collector. |
Number | count(Closure closure)Counts the number of occurrences which satisfy the given closure from inside this map. |
Object | count(Object initialCount,Closure closure)Counts the number of occurrences which satisfy the given closure from inside this map. |
Map | countBy(Closure closure)Groups the members of a map into groups determined by thesupplied mapping closure and counts the frequency of the created groups. |
Map | drop(int num)Drops the given number of key/value pairs from the head of this map if they are available. |
Map | dropWhile(Closure condition)Create a suffix of the given Map by dropping as many entries as possible from thefront of the original Map such that calling the given closure condition evaluates totrue when passed each of the dropped entries (or key/value pairs). |
Map | each(Closure closure)Allows a Map to be iterated through using a closure. |
Map | eachWithIndex(Closure closure)Allows a Map to be iterated through using a closure. |
boolean | equals(Map other)Compares two Maps treating coerced numerical values as identical. |
boolean | every(Closure predicate)Iterates over the entries of a map, and checks whether a predicate isvalid for all entries. |
Entry | find(Closure closure)Finds the first entry matching the closure condition. |
Map | findAll(Closure closure)Finds all entries matching the closure condition. |
Object | findResult(Closure condition)Returns the first non-null closure result found by passing each map entry to the closure, otherwise null is returned. |
Object | findResult(Object defaultResult,Closure condition)Returns the first non-null closure result found by passing each map entry to the closure, otherwise the defaultResult is returned. |
Collection | findResults(Closure filteringTransform)Iterates through the map transforming items using the supplied closureand collecting any non-null results. |
Object | get(Object key,Object defaultValue)Looks up an item in a Map for the given key and returns the corresponding value. |
Object | getAt(Object key)Support the subscript operator for a Map. |
Map | groupBy(Closure closure)Groups the members of a map into sub maps determined by thesupplied mapping closure. |
Map | groupBy(Object closures)Groups the members of a map into sub maps determined by the suppliedmapping closures. |
Map | groupBy(List closures)Groups the members of a map into sub maps determined by the suppliedmapping closures. |
Map | groupEntriesBy(Closure closure)Groups all map entries into groups determined by thesupplied mapping closure. |
Object | inject(Object initialValue,Closure closure)Iterates through the given Map, passing in the initial value tothe 2-arg Closure along with the first item (or 3-arg Closure along with the first key and value). |
Map | intersect(Map right)Create a Map composed of the intersection of both maps. |
boolean | isCase(Object switchValue)'Case' implementation for maps which tests the groovy truthvalue obtained using the 'switch' operand as key. |
boolean | isNotCase(Object switchValue) |
Map | leftShift(Map other)Overloads the left shift operator to provide an easy way to putone maps entries into another map. |
Map | leftShift(Entry entry)Overloads the left shift operator to provide an easy way to appendMap.Entry values to a Map. |
Entry | max(Closure closure)Selects an entry in the map having the maximumcalculated value as determined by the supplied closure. |
Entry | min(Closure closure)Selects an entry in the map having the minimumcalculated value as determined by the supplied closure. |
Map | minus(Map removeMe)Create a Map composed of the entries of the first map minus theentries of the given map. |
String | plus(GString right)Appends a GString to the literal of the Map instance. |
String | plus(String right)Appends a String to the literal of the Map instance. |
Map | plus(Collection entries)Returns a new Map containing all entries fromself andentries,giving precedence toentries. |
Map | plus(Map right)Returns a new Map containing all entries fromleft andright,giving precedence toright. |
Map | putAll(Collection entries)Provides an easy way to append multiple Map.Entry values to a Map. |
Object | putAt(Object key,Object value)A helper method to allow maps to work with subscript operators |
boolean | removeAll(Closure condition)Modifies this map by removing the elements that are matched according to thespecified closure condition. |
boolean | retainAll(Closure condition)Modifies this map so that it retains only its elements that are matchedaccording to the specified closure condition. |
Map | reverseEach(Closure closure)Allows a Map to be iterated through in reverse order using a closure. |
Map | sort()Sorts the elements from the given map into a new ordered Map usingthe natural ordering of the keys to determine the ordering. |
Map | sort(Closure closure)Sorts the elements from the given map into a new ordered map usingthe closure as a comparator to determine the ordering. |
Map | sort(Comparator comparator)Sorts the elements from the given map into a new ordered Map usingthe specified key comparator to determine the ordering. |
SpreadMap | spread()Synonym forMap#toSpreadMap(). |
Map | subMap(Object[] keys)Creates a sub-Map containing the given keys. |
Map | subMap(Collection keys)Creates a sub-Map containing the given keys. |
Map | take(int num)Returns a new map containing the first num elements from the head of this map. |
Map | takeWhile(Closure condition)Returns the longest prefix of this Map where each entry (or key/value pair) whenpassed to the given closure evaluates to true. |
String | toMapString()Returns the string representation of this map. |
String | toMapString(int maxSize)Returns the string representation of this map. |
Map | toSorted()Sorts the elements from the given map into a new ordered map usinga NumberAwareComparator on map entry values to determine the resulting order. |
Map | toSorted(Closure condition)Sorts the elements from the given map into a new ordered map usingthe supplied Closure condition as a comparator to determine the ordering. |
Map | toSorted(Comparator comparator)Sorts the elements from the given map into a new ordered map usingthe supplied comparator to determine the ordering. |
SpreadMap | toSpreadMap()Returns a new SpreadMap from this map. |
Map | withDefault(boolean autoGrow, boolean autoShrink,Closure init)Wraps a map using the decorator pattern with a wrapper that intercepts all callsto get(key) andput(key, value). |
Map | withDefault(Closure init)Wraps a map using the decorator pattern with a wrapper that intercepts all callsto get(key). |
Iterates over the entries of a map, and checks whether a predicate isvalid for at least one entry. If theclosure takes one parameter then it will be passed the Map.Entryotherwise if the closure takes two parameters then it will bepassed the key and the value.
assert [2:3, 4:5, 5:10].any { key, value-> key * 2 == value }assert ![2:3, 4:5, 5:10].any { entry-> entry.key == entry.value * 2 }predicate - the 1 or 2 arg closure predicate used for matchingCoerce a map instance to a boolean value.A map is coerced to false if it's empty, and to true otherwise.
assert [:] as Boolean == falseassert [a:2] as Boolean == true
A convenience method for creating an immutable Map.
A convenience method for creating a synchronized Map.
Coerces this map to the given type, using the map's keys as the publicmethod names, and values as the implementation. Typically the valuewould be a closure which behaves like the method implementation.
clazz - the target typeCreates an unmodifiable view of a Map.
Iterates through this Map transforming each map entry into a new value using thetransform closurereturning a list of transformed values.
assert [a:1, b:2].collect { key, value-> key*value } == ["a", "bb"]assert [3:20, 2:30].collect { entry-> entry.key * entry.value } == [60, 60]transform - the transformation closure which can take one (Map.Entry) or two (key, value) parametersIterates through this Map transforming each map entry into a new value using thetransform closurereturning thecollector with all transformed values added to it.
assert [a:1, b:2].collect( [] as HashSet ) { key, value-> key*value } == ["a", "bb"] as Setassert [3:20, 2:30].collect( [] as HashSet ) { entry-> entry.key * entry.value } == [60] as Setcollector - the Collection to which transformed values are addedtransform - the transformation closure which can take one (Map.Entry) or two (key, value) parametersIterates through this Map transforming each entry using thetransform closureand returning a map of the transformed entries.
assert [a:1, b:2].collectEntries { key, value-> [value, key] } == [1:'a', 2:'b']assert [a:1, b:2].collectEntries { key, value-> [(value*10): key.toUpperCase()] } == [10:'A', 20:'B']Note: When using the list-style of result, the behavior is 'def (key, value) = listResultFromClosure'.While we strongly discourage using a list of size other than 2, Groovy's normal semantics apply in this case;throwing away elements after the second one and using null for the key or value for the case of a shortened list.If your Map doesn't support null keys or values, you might get a runtime error, e.g. NullPointerException or IllegalArgumentException.transform - the closure used for transforming, which can take one (Map.Entry) or two (key, value) parameters and should return a Map.Entry, a Map or a two-element list containing the resulting key and valueIterates through this Map transforming each map entry using thetransform closurereturning a map of the transformed entries.
assert [a:1, b:2].collectEntries( [:] ) { k, v-> [v, k] } == [1:'a', 2:'b']assert [a:1, b:2].collectEntries( [30:'C'] ) { key, value-> [(value*10): key.toUpperCase()] } == [10:'A', 20:'B', 30:'C']Note: When using the list-style of result, the behavior is 'def (key, value) = listResultFromClosure'.While we strongly discourage using a list of size other than 2, Groovy's normal semantics apply in this case;throwing away elements after the second one and using null for the key or value for the case of a shortened list.If your collector Map doesn't support null keys or values, you might get a runtime error, e.g. NullPointerException or IllegalArgumentException.collector - the Map into which the transformed entries are puttransform - the closure used for transforming, which can take one (Map.Entry) or two (key, value) parameters and should return a Map.Entry, a Map or a two-element list containing the resulting key and valueProjects each item from a source map to a result collection and concatenates (flattens) the resultingcollections adding them into a collection.
def map = [bread:3, milk:5, butter:2]def result = map.collectMany{ k, v-> k.startsWith('b') ? k.toList() : [] }assert result == ['b', 'r', 'e', 'a', 'd', 'b', 'u', 't', 't', 'e', 'r']projection - a projecting Closure returning a collection of itemsProjects each item from a source map to a result collection and concatenates (flattens) the resultingcollections adding them into thecollector.
def map = [bread:3, milk:5, butter:2]def result = map.collectMany(['x']){ k, v-> if (k.startsWith('b')) k.toList() }assert result == ['x', 'b', 'r', 'e', 'a', 'd', 'b', 'u', 't', 't', 'e', 'r']collector - an initial collection to add the projected items toprojection - a projecting Closure returning a collection of itemsCounts the number of occurrences which satisfy the given closure from inside this map.If the closure takes one parameter then it will be passed the Map.Entry.Otherwise, the closure should take two parameters and will be passed the key and value.
Example usage:
assert [a:1, b:1, c:2, d:2].count{ k,v-> k == 'a'|| v == 2 } == 3closure - a 1 or 2 arg Closure condition applying on the entriesCounts the number of occurrences which satisfy the given closure from inside this map.If the closure takes one parameter then it will be passed the Map.Entry.Otherwise, the closure should take two parameters and will be passed the key and value.
Example usage:
assert [a:1, b:1, c:2, d:2].count(100G){ k,v-> k == 'a'|| v == 2 } == 103GinitialCount - start counting from this valueclosure - a 1 or 2 arg Closure condition applying on the entriesGroups the members of a map into groups determined by thesupplied mapping closure and counts the frequency of the created groups.The closure will be passed a Map.Entry orkey and value (depending on the number of parameters the closure accepts)and should return the key that each item should be grouped under. Theresulting map will have an entry for each 'group' key returned by theclosure, with values being the frequency counts for that 'group'.
def result = [a:1,b:2,c:3,d:4,e:5].countBy { it.value % 2 }assert result == [0:2, 1:3]closure - a closure mapping entries to frequency count keysDrops the given number of key/value pairs from the head of this map if they are available.
def strings = [ 'a':10, 'b':20, 'c':30 ]assert strings.drop( 0 ) == [ 'a':10, 'b':20, 'c':30 ]assert strings.drop( 2 ) == [ 'c':30 ]assert strings.drop( 5 ) == [:]If the map instance does not have ordered keys, then this function could drop a random
numentries. Groovy by default uses LinkedHashMap, so this shouldn't be an issue in the main.num - the number of elements to drop from this mapnum ones, or else the empty map, if this map has less thannum elements.Create a suffix of the given Map by dropping as many entries as possible from thefront of the original Map such that calling the given closure condition evaluates totrue when passed each of the dropped entries (or key/value pairs).
def shopping = [milk:1, bread:2, chocolate:3]assert shopping.dropWhile{ it.key.size()< 6 } == [chocolate:3]assert shopping.dropWhile{ it.value % 2 } == [bread:2, chocolate:3]assert shopping.dropWhile{ k, v-> k.size() + v<= 7 } == [chocolate:3]If the map instance does not have ordered keys, then this function could appear to drop randomentries. Groovy by default uses LinkedHashMap, so this shouldn't be an issue in the main.condition - a 1 (or 2) arg Closure that must evaluate to true for the entry (or key and value) to continue dropping elementsAllows a Map to be iterated through using a closure. If theclosure takes one parameter then it will be passed the Map.Entryotherwise if the closure takes two parameters then it will bepassed the key and the value.
def result = ""[a:1, b:3].each { key, value-> result += "$key$value" }assert result == "a1b3"def result = ""[a:1, b:3].each { entry-> result += entry }assert result == "a=1b=3"In general, the order in which the map contents are processedcannot be guaranteed. In practise, specialized forms of Map,e.g. a TreeMap will have its contents processed according tothe natural ordering of the map.closure - the 1 or 2 arg closure applied on each entry of the mapAllows a Map to be iterated through using a closure. If theclosure takes two parameters then it will be passed the Map.Entry andthe item's index (a counter starting at zero) otherwise if the closuretakes three parameters then it will be passed the key, the value, andthe index.
def result = ""[a:1, b:3].eachWithIndex { key, value, index-> result += "$index($key$value)" }assert result == "0(a1)1(b3)"def result = ""[a:1, b:3].eachWithIndex { entry, index-> result += "$index($entry)" }assert result == "0(a=1)1(b=3)"closure - a 2 or 3 arg Closure to operate on each itemCompares two Maps treating coerced numerical values as identical.
Example usage:
assert [a:2, b:3] == [a:2L, b:3.0]
other - the Map being compared toIterates over the entries of a map, and checks whether a predicate isvalid for all entries. If theclosure takes one parameter then it will be passed the Map.Entryotherwise if the closure takes two parameters then it will bepassed the key and the value.
def map = [a:1, b:2.0, c:2L]assert !map.every { key, value-> value instanceof Integer }assert map.every { entry-> entry.value instanceof Number }predicate - the 1 or 2 arg Closure predicate used for matchingFinds the first entry matching the closure condition.If the closure takes two parameters, the entry key and value are passed.If the closure takes one parameter, the Map.Entry object is passed.
assert [a:1, b:3].find { it.value == 3 }.key == "b"closure - a 1 or 2 arg Closure conditionFinds all entries matching the closure condition. If theclosure takes one parameter then it will be passed the Map.Entry.Otherwise if the closure should take two parameters, which will bethe key and the value.
If theself map is one of TreeMap, LinkedHashMap, Hashtableor Properties, the returned Map will preserve that type, otherwise a HashMap willbe returned.
Example usage:
def result = [a:1, b:2, c:4, d:5].findAll { it.value % 2 == 0 }assert result.every { it instanceof Map.Entry }assert result*.key == ["b", "c"]assert result*.value == [2, 4]closure - a 1 or 2 arg Closure condition applying on the entriesReturns the first non-null closure result found by passing each map entry to the closure, otherwise null is returned.If the closure takes two parameters, the entry key and value are passed.If the closure takes one parameter, the Map.Entry object is passed.
assert "Found b:3" == [a:1, b:3].findResult { if (it.value == 3) return "Found ${it.key}:${it.value}" }assert null == [a:1, b:3].findResult { if (it.value == 9) return "Found ${it.key}:${it.value}" }assert "Found a:1" == [a:1, b:3].findResult { k, v-> if (k.size() + v == 2) return "Found $k:$v" }condition - a 1 or 2 arg Closure that returns a non-null value when processing should stop and a value should be returnedReturns the first non-null closure result found by passing each map entry to the closure, otherwise the defaultResult is returned.If the closure takes two parameters, the entry key and value are passed.If the closure takes one parameter, the Map.Entry object is passed.
assert "Found b:3" == [a:1, b:3].findResult("default") { if (it.value == 3) return "Found ${it.key}:${it.value}" }assert "default" == [a:1, b:3].findResult("default") { if (it.value == 9) return "Found ${it.key}:${it.value}" }assert "Found a:1" == [a:1, b:3].findResult("default") { k, v-> if (k.size() + v == 2) return "Found $k:$v" }defaultResult - an Object that should be returned if all closure results are nullcondition - a 1 or 2 arg Closure that returns a non-null value when processing should stop and a value should be returnedIterates through the map transforming items using the supplied closureand collecting any non-null results.If the closure takes two parameters, the entry key and value are passed.If the closure takes one parameter, the Map.Entry object is passed.
Example:
def map = [a:1, b:2, hi:2, cat:3, dog:2]def result = map.findResults { k, v-> k.size() == v ? "Found $k:$v" : null }assert result == ["Found a:1", "Found hi:2", "Found cat:3"]filteringTransform - a 1 or 2 arg Closure that should return either a non-null transformed value or null for items which should be discardedLooks up an item in a Map for the given key and returns the corresponding value.If there is no entry for the given key return instead the default value andalso add the key and default value to the map.
def map=[:]map.get("a", []) << 5assert map == [a:[5]]For a method which doesn't mutate the map, consider instead using Map#getOrDefault(Object, Object)or consider using Groovy's MapWithDefault often instantiated using Map#withDefault(Closure)or with more options Map#withDefault(boolean, boolean, Closure).key - the key to look up the valuedefaultValue - the value to return and add to the map for this key if there is no entry for the given keySupport the subscript operator for a Map.
def map = [a:10]assert map["a"] == 10
key - an Object as a key for the mapGroups the members of a map into sub maps determined by thesupplied mapping closure. The closure will be passed a Map.Entry orkey and value (depending on the number of parameters the closure accepts)and should return the key that each item should be grouped under. Theresulting map will have an entry for each 'group' key returned by theclosure, with values being the map members from the original map thatbelong to each group. (If instead of a map, you want a list of map entriesuse {code}groupEntriesBy{code}.)
If theself map is one of TreeMap, Hashtable or Properties,the returned Map will preserve that type, otherwise a LinkedHashMap willbe returned.
def result = [a:1,b:2,c:3,d:4,e:5,f:6].groupBy { it.value % 2 }assert result == [0:[b:2, d:4, f:6], 1:[a:1, c:3, e:5]]closure - a closure mapping entries on keysGroups the members of a map into sub maps determined by the suppliedmapping closures. Each closure will be passed a Map.Entry or key andvalue (depending on the number of parameters the closure accepts) andshould return the key that each item should be grouped under. Theresulting map will have an entry for each 'group path' returned by allclosures, with values being the map members from the original map thatbelong to each such 'group path'.If theself map is one of TreeMap, Hashtable, or Properties,the returned Map will preserve that type, otherwise a LinkedHashMap willbe returned.
def result = [a:1,b:2,c:3,d:4,e:5,f:6].groupBy({ it.value % 2 }, { it.key.next() })assert result == [1:[b:[a:1], d:[c:3], f:[e:5]], 0:[c:[b:2], e:[d:4], g:[f:6]]]If an empty array of closures is supplied the IDENTITY Closure will be used.closures - an array of closures that map entries on keysGroups the members of a map into sub maps determined by the suppliedmapping closures. Each closure will be passed a Map.Entry or key andvalue (depending on the number of parameters the closure accepts) andshould return the key that each item should be grouped under. Theresulting map will have an entry for each 'group path' returned by allclosures, with values being the map members from the original map thatbelong to each such 'group path'.If theself map is one of TreeMap, Hashtable, or Properties,the returned Map will preserve that type, otherwise a LinkedHashMap willbe returned.
def result = [a:1,b:2,c:3,d:4,e:5,f:6].groupBy([{ it.value % 2 }, { it.key.next() }])assert result == [1:[b:[a:1], d:[c:3], f:[e:5]], 0:[c:[b:2], e:[d:4], g:[f:6]]]If an empty list of closures is supplied the IDENTITY Closure will be used.closures - a list of closures that map entries on keysGroups all map entries into groups determined by thesupplied mapping closure. The closure will be passed a Map.Entry orkey and value (depending on the number of parameters the closure accepts)and should return the key that each item should be grouped under. Theresulting map will have an entry for each 'group' key returned by theclosure, with values being the list of map entries that belong to eachgroup. (If instead of a list of map entries, you want an actual mapuse {code}groupBy{code}.)
def result = [a:1,b:2,c:3,d:4,e:5,f:6].groupEntriesBy { it.value % 2 }assert result[0]*.key == ["b", "d", "f"]assert result[1]*.value == [1, 3, 5]closure - a 1 or 2 arg Closure mapping entries on keysIterates through the given Map, passing in the initial value tothe 2-arg Closure along with the first item (or 3-arg Closure along with the first key and value).The result is passed back (injected) intothe closure along with the second item. The new result is injected back intothe closure along with the third item and so on until the entire collectionhas been used. Also known asfoldLeft orreduce in functional parlance.Examples:
def map = [a:1, b:2, c:3]assert map.inject([]) { list, k, v-> list + [k] * v} == ['a', 'b', 'b', 'c', 'c', 'c']initialValue - some initial valueclosure - a 2 or 3 arg ClosureCreate a Map composed of the intersection of both maps.Any entries that exist in both maps are added to the resultant map.
assert [4:4,5:5] == [1:1,2:2,3:3,4:4,5:5].intersect([4:4,5:5,6:6,7:7,8:8])
assert [1: 1, 2: 2, 3: 3, 4: 4].intersect( [1: 1.0, 2: 2, 5: 5] ) == [1:1, 2:2]
right - a map'Case' implementation for maps which tests the groovy truthvalue obtained using the 'switch' operand as key.For example:
switch( 'foo' ) { case [foo:true, bar:false]: assert true break default: assert false}switchValue - the switch valueOverloads the left shift operator to provide an easy way to putone maps entries into another map. This allows the compact syntaxmap1 << map2; otherwise it's just a synonym forputAll though it returns the original map rather thanbeing avoid method. Example usage:
def map = [a:1, b:2]map << [c:3, d:4]assert map == [a:1, b:2, c:3, d:4]
other - another Map whose entries should be added to the original Map.Overloads the left shift operator to provide an easy way to appendMap.Entry values to a Map.
entry - a Map.Entry to be added to the Map.Selects an entry in the map having the maximumcalculated value as determined by the supplied closure.If more than one entry has the maximum value,an arbitrary choice is made between the entries having the maximum value.
If the closure has two parametersit is used like a traditional Comparator. I.e. it should compareits two parameters for order, returning a negative integer,zero, or a positive integer when the first parameter is less than,equal to, or greater than the second respectively. Otherwise,the Closure is assumed to take a single parameter and return aComparable (typically an Integer) which is then used forfurther comparison. An example:
def zoo = [monkeys:6, lions:5, tigers:7]def mostCommonEntry = zoo.max{ it.value }assert mostCommonEntry.value == 7def leastCommonEntry = zoo.max{ a, b-> b.value<=> a.value } // double negative!assert leastCommonEntry.value == 5Edge case for multiple max values:def zoo = [monkeys:6, lions:5, tigers:7]def lengthOfNamePlusNumber = { e-> e.key.size() + e.value }def ans = zoo.max(lengthOfNamePlusNumber) // one of [monkeys:6, tigers:7]assert lengthOfNamePlusNumber(ans) == 13closure - a 1 or 2 arg Closure used to determine the correct orderingSelects an entry in the map having the minimumcalculated value as determined by the supplied closure.If more than one entry has the minimum value,an arbitrary choice is made between the entries having the minimum value.
If the closure has two parametersit is used like a traditional Comparator. I.e. it should compareits two parameters for order, returning a negative integer,zero, or a positive integer when the first parameter is less than,equal to, or greater than the second respectively. Otherwise,the Closure is assumed to take a single parameter and return aComparable (typically an Integer) which is then used forfurther comparison.
def zoo = [monkeys:6, lions:5, tigers:7]def leastCommonEntry = zoo.min{ it.value }assert leastCommonEntry.value == 5def mostCommonEntry = zoo.min{ a, b-> b.value<=> a.value } // double negative!assert mostCommonEntry.value == 7Edge case for multiple min values:def zoo = [monkeys:6, lions:5, tigers:7]def lastCharOfName = { e-> e.key[-1] }def ans = zoo.min(lastCharOfName) // some random entryassert lastCharOfName(ans) == 's'closure - a 1 or 2 arg Closure used to determine the correct orderingCreate a Map composed of the entries of the first map minus theentries of the given map.
removeMe - the entries to remove from the mapAppends a GString to the literal of the Map instance.
assert '[a:1] is a map' == [a:1] + " is ${'a'} map"right - a GStringAppends a String to the literal of the Map instance.
assert '[a:1] is a map' == [a:1] + ' is a map'
right - a StringReturns a newMap containing all entries fromself andentries,giving precedence toentries. Any keys appearing in both Mapswill appear in the resultant map with values from theentriesoperand. Ifself map is one of TreeMap, LinkedHashMap, Hashtableor Properties, the returned Map will preserve that type, otherwise a HashMap willbe returned.
entries - a Collection of Map.Entry items to be added to the Map.Returns a newMap containing all entries fromleft andright,giving precedence toright. Any keys appearing in both Mapswill appear in the resultant map with values from therightoperand. If theleft map is one of TreeMap, LinkedHashMap, Hashtableor Properties, the returned Map will preserve that type, otherwise a HashMap willbe returned.
Roughly equivalent toMap m = new HashMap(); m.putAll(left); m.putAll(right); return m;but with some additional logic to preserve theleft Map type for common cases asdescribed above.
assert [a:10, b:20] + [a:5, c:7] == [a:5, b:20, c:7]
right - a MapProvides an easy way to append multiple Map.Entry values to a Map.
entries - a Collection of Map.Entry items to be added to the Map.A helper method to allow maps to work with subscript operators
key - an Object as a key for the mapvalue - the value to put into the mapModifies this map by removing the elements that are matched according to thespecified closure condition. If the closure takes one parameter then it will bepassed theMap.Entry. Otherwise the closure should take two parameters, whichwill be the key and the value.
def map = [a:1, b:2]map.removeAll { k,v-> k == 'b' }assert map == [a:1]See alsofindAll when wanting to produce a new map containing itemswhich match some criteria but leaving the original map unchanged.condition - a 1 or 2 arg Closure condition applying on the entriesModifies this map so that it retains only its elements that are matchedaccording to the specified closure condition. In other words, removes fromthis map all of its elements that don't match. If the closure takes oneparameter then it will be passed theMap.Entry. Otherwise the closure shouldtake two parameters, which will be the key and the value.
def map = [a:1, b:2]map.retainAll { k,v-> k == 'b' }assert map == [b:2]See alsofindAll when wanting to produce a new map containing itemswhich match some criteria but leaving the original map unchanged.condition - a 1 or 2 arg Closure condition applying on the entriesAllows a Map to be iterated through in reverse order using a closure.In general, the order in which the map contents are processedcannot be guaranteed. In practise, specialized forms of Map,e.g. a TreeMap will have its contents processed according to thereverse of the natural ordering of the map.
closure - the 1 or 2 arg closure applied on each entry of the mapSorts the elements from the given map into a new ordered Map usingthe natural ordering of the keys to determine the ordering.The original map is unchanged.
map = [ba:3, cz:6, ab:5].sort()assert map*.value == [5, 3, 6]
Sorts the elements from the given map into a new ordered map usingthe closure as a comparator to determine the ordering.The original map is unchanged.
def map = [a:5, b:3, c:6, d:4].sort { a, b-> a.value<=> b.value }assert map == [b:3, d:4, a:5, c:6]closure - a Closure used as a comparatorSorts the elements from the given map into a new ordered Map usingthe specified key comparator to determine the ordering.The original map is unchanged.
def map = [ba:3, cz:6, ab:5].sort({ a, b-> a[-1]<=> b[-1] } as Comparator)assert map*.value == [3, 5, 6]comparator - a ComparatorSynonym forMap#toSpreadMap().
Creates a sub-Map containing the given keys. This method is similar toList.subList() but uses keys rather than index ranges. The originalmap is unaltered.
def orig = [1:10, 2:20, 3:30, 4:40]assert orig.subMap([1, 3] as int[]) == [1:10, 3:30]assert orig.subMap([2, 4] as Integer[]) == [2:20, 4:40]assert orig.size() == 4
keys - an array of keysCreates a sub-Map containing the given keys. This method is similar toList.subList() but uses keys rather than index ranges.
assert [1:10, 2:20, 4:40].subMap( [2, 4] ) == [2:20, 4:40]
keys - a Collection of keysReturns a new map containing the firstnum elements from the head of this map.If the map instance does not have ordered keys, then this function could return a randomnumentries. Groovy by default uses LinkedHashMap, so this shouldn't be an issue in the main.
def strings = [ 'a':10, 'b':20, 'c':30 ]assert strings.take( 0 ) == [:]assert strings.take( 2 ) == [ 'a':10, 'b':20 ]assert strings.take( 5 ) == [ 'a':10, 'b':20, 'c':30 ]
num - the number of elements to take from this mapnum elements of this map, or else the whole map if it has less thannum elements.Returns the longest prefix of this Map where each entry (or key/value pair) whenpassed to the given closure evaluates to true.
def shopping = [milk:1, bread:2, chocolate:3]assert shopping.takeWhile{ it.key.size()< 6 } == [milk:1, bread:2]assert shopping.takeWhile{ it.value % 2 } == [milk:1]assert shopping.takeWhile{ k, v-> k.size() + v<= 7 } == [milk:1, bread:2]If the map instance does not have ordered keys, then this function could appear to take randomentries. Groovy by default uses LinkedHashMap, so this shouldn't be an issue in the main.condition - a 1 (or 2) arg Closure that must evaluate to true for the entry (or key and value) to continue taking elementsReturns the string representation of this map. The string displays thecontents of the map, i.e.[one:1, two:2, three:3].
Returns the string representation of this map. The string displays thecontents of the map, i.e.[one:1, two:2, three:3].
maxSize - stop after approximately this many characters and append '...'Sorts the elements from the given map into a new ordered map usinga NumberAwareComparator on map entry values to determine the resulting order.NumberAwareComparator has special treatment for numbers but otherwise uses thenatural ordering of the Iterator elements. The original map is unchanged.
def map = [a:5L, b:3, c:6, d:4.0].toSorted()assert map.toString() == '[b:3, d:4.0, a:5, c:6]'
Sorts the elements from the given map into a new ordered map usingthe supplied Closure condition as a comparator to determine the ordering. The original map is unchanged.
If the closure has two parameters it is used like a traditional Comparator. I.e. it should compareits two entry parameters for order, returning a negative integer, zero, or a positive integer when thefirst parameter is less than, equal to, or greater than the second respectively. Otherwise,the Closure is assumed to take a single entry parameter and return a Comparable (typically an Integer)which is then used for further comparison.
def map = [a:5, b:3, c:6, d:4].toSorted { a, b-> a.value<=> b.value }assert map.toString() == '[b:3, d:4, a:5, c:6]'condition - a Closure used as a comparatorSorts the elements from the given map into a new ordered map usingthe supplied comparator to determine the ordering. The original map is unchanged.
def keyComparator = [compare: { e1, e2-> e1.key<=> e2.key }] as Comparatordef valueComparator = [compare: { e1, e2-> e1.value<=> e2.value }] as Comparatordef map1 = [a:5, b:3, d:4, c:6].toSorted(keyComparator)assert map1.toString() == '[a:5, b:3, c:6, d:4]'def map2 = [a:5, b:3, d:4, c:6].toSorted(valueComparator)assert map2.toString() == '[b:3, d:4, a:5, c:6]'comparator - a Comparator used for the comparisonReturns a newSpreadMap from this map.
The example below shows the various possible use cases:
def fn(Map m) { return m.a + m.b + m.c + m.d }assert fn(a:1, b:2, c:3, d:4) == 10assert fn(a:1, *:[b:2, c:3], d:4) == 10assert fn([a:1, b:2, c:3, d:4].toSpreadMap()) == 10assert fn((['a', 1, 'b', 2, 'c', 3, 'd', 4] as Object[]).toSpreadMap()) == 10assert fn(['a', 1, 'b', 2, 'c', 3, 'd', 4].toSpreadMap()) == 10assert fn(['abcd'.toList(), 1..4].transpose().flatten().toSpreadMap()) == 10Note that toSpreadMap() is not normally used explicitly but under the covers by Groovy.Wraps a map using the decorator pattern with a wrapper that intercepts all callstoget(key) andput(key, value).If an unknown key is found forget, a default value will be returned.The default value will be the result of calling the supplied Closure with the keyas the parameter to the Closure.IfautoGrow is set, the value will be stored into the map.IfautoShrink is set, then an attempt toput the default valueinto the map is ignored and indeed any existing value would be removed.If you wish the backing map to be as small as possible, consider settingautoGrowtofalse andautoShrink totrue.This keeps the backing map as small as possible, i.e. sparse, but also means thatcontainsKey,keySet,size, and other methodswill only reflect the sparse values.If you are wrapping an immutable map, you should setautoGrowandautoShrink tofalse.In this scenario, theget method is essentially a shorthandfor callinggetOrDefault with the default value supplied once as a Closure.Example usage:
// sparse map exampledef answers = [life: 100].withDefault(false, true){ 42 }assert answers.size() == 1assert answers.foo == 42assert answers.size() == 1answers.life = 42answers.putAll(universe: 42, everything: 42)assert answers.size() == 0// immutable map exampledef certainties = [death: true, taxes: true].asImmutable().withDefault(false, false){ false }assert certainties.size() == 2assert certainties.wealth == falseassert certainties.size() == 2autoGrow - whether calling get could potentially grow the map if the key isn't foundautoShrink - whether calling put with the default value could potentially shrink the mapinit - a Closure which is passed the unknown keyWraps a map using the decorator pattern with a wrapper that intercepts all callstoget(key). If an unknown key is found, a default value will bestored into the Map before being returned. The default value stored will be theresult of calling the supplied Closure with the key as the parameter to the Closure.Example usage:
def map = [a:1, b:2].withDefault{ k-> k.toCharacter().isLowerCase() ? 10 : -10 }def expected = [a:1, b:2, c:10, D:-10]assert expected.every{ e-> e.value == map[e.key] }def constMap = [:].withDefault{ 42 }assert constMap.foo == 42assert constMap.size() == 1init - a Closure which is passed the unknown key