ceylon.language.Map.ceylon Maven / Gradle / Ivy
"""A collection which maps _keys_ to _items_, where a key
can map to at most one item. Each such mapping may be
represented by an [[Entry]]. Thus, each distinct key
occurs in at most one entry. Two
non-[[identical|Identifiable]] keys are considered
distinct only if they are unequal, according to their own
definition of [[value equality|Object.equals]].
A `Map` is a [[Collection]] of its `Entry`s, and a
[[Correspondence]] from keys to items.
A new `Map` may be obtained by calling the function
[[ceylon.language::map]].
value settings = map { "lang"->"en_AU", "loc"->"ES" };
The [[emptyMap]] is a `Map` with no entries.
The presence of an entry in a map may be tested using the
`in` operator:
if ("lang"->"en_AU" in settings) { ... }
The entries of the map may be iterated using `for`:
for (key->item in settings) { ... }
The item for a key may be obtained using the item
operator:
String lang = settings["lang"] else "en_US";
An implementation of `Map` may compare keys for equality
using [[Object.equals]] or [[Comparable.compare]]."""
see (`class Entry`, `function package.map`,
`function forKey`, `function forItem`,
`function byItem`, `function byKey`,
`value emptyMap`)
tagged("Collections")
shared interface Map
satisfies CollectionItem> &
Correspondence
given Key satisfies Object {
"Returns the item of the entry with the given [[key]],
or `null` if there is no entry with the given `key` in
this map."
see (`function getOrDefault`)
shared actual formal Item? get(Object key);
"Determines if there is an entry in this map with the
given [[key]]."
see (`function contains`)
shared actual formal Boolean defines(Object key);
"Returns the item of the entry with the given [[key]],
or the given [[default]] if there is no entry with the
given `key` in this map.
For maps with non-null items, the expression:
map.getOrDefault(key, def)
is equivalent to this common idiom:
map[key] else def
However, when the map has null items, `getOrDefault()`
will preserve them.
Note that high-quality implementations of `Map` should
refine this default implementation."
see (`function get`)
since("1.2.0")
shared default Item|Default getOrDefault
(Object key, Default default) {
if (defines(key)) {
if (exists item = get(key)) {
return item;
}
else {
assert (is Item null);
return null;
}
}
else {
return default;
}
}
function lookup(Object key)
=> getOrDefault(key, Missing.instance);
"Determines if the given [[value|entry]] is an [[Entry]]
belonging to this map."
see (`function defines`)
shared actual default Boolean contains(Object entry) {
if (is Object->Anything entry) {
value key -> it = entry;
if (defines(key)) {
value item = get(key);
return
if (exists it, exists item)
then item == it
else it exists == item exists;
}
}
return false;
}
distinct => this;
shared actual {Item>*}
defaultNullElements(Default defaultValue)
given Default satisfies Object => this;
"A shallow copy of this map, that is, a map with the
same entries as this map, which do not change if the
entries in this map change."
shared actual default Map clone()
=> package.map(this);
"A [[Collection]] containing the keys of this map."
//TODO: should be a Set
shared actual default Collection keys
=> object extends Object()
satisfies Set {
contains(Object key) => outer.defines(key);
iterator() => outer.map(Entry.key).iterator();
size => outer.size;
empty => outer.empty;
clone() => set(this);
};
"A [[Collection]] containing the items stored in this
map. An element can be stored under more than one key
in the map, and so it can occur more than once in the
resulting collection."
since("1.1.0")
shared default Collection- items => Items();
"A bag of items."
class Items() extends Object()
satisfies Collection
- {
contains(Object item)
=> outer.any((_->it)
=> if (exists it) then it==item
else false);
iterator() => outer.map(Entry.item).iterator();
size => outer.size;
empty => outer.empty;
clone() => [*this];
//implement hash and equals for bag semantics
hash => frequencies().hash;
equals(Object that)
=> if (is Items that)
then frequencies()==that.frequencies()
else false;
}
"Invert this map, producing a new immutable map where
the keys of the new map are the non-null items of this
map, and each item of the new map is a nonempty
sequence of keys of this map.
For example, the expression:
{ \"fee\", \"fi\", \"fo\", \"fum\", \"foo\" }
.tabulate(String.size)
.inverse()
produces the map
`{ 2->[\"fo\", \"fi\"], 3->[ \"fum\", \"fee\", \"foo\"] }`.
The order of keys in the key sequences is not defined
and should not be relied upon.
This is an eager operation, and the resulting map does
not reflect changes to this map."
since("1.2.0")
shared default Map
inverse()
=> coalescedMap
.summarize>
(Entry.item, (keys, key->_)
=> ElementEntry(keys, key))
//not very useful, since the entries of a
//map don't usually have a very meaningful
//order (except for TreeMaps!)
//but we do need to convert it to a Sequence
.mapItems((_, item) => item.reversedSequence());
"Two maps are considered equal iff they have the same
_entry sets_. The entry set of a `Map` is the set of
`Entry`s belonging to the map. Therefore, the maps are
equal iff they have same set of `keys`, and for every
key in the key set, the maps have equal items."
shared actual default Boolean equals(Object that) {
if (is Map that,
that.size==size) {
for (key -> thisItem in this) {
value thatItem = that[key];
if (exists thisItem, exists thatItem) {
if (thatItem!=thisItem) {
return false;
}
}
else if (thisItem exists!=thatItem exists) {
return false;
}
}
else {
return true;
}
}
else {
return false;
}
}
shared actual default Integer hash {
variable value hashCode = 0;
for (elem in this) {
hashCode += elem.hash;
}
return hashCode;
}
"Produces a map with the same [[keys]] as this map. For
every key, the item is the result of applying the given
[[transformation|Map.mapItems.mapping]] function to its
associated item in this map. This is a lazy operation,
returning a view of this map."
shared default
Map mapItems(
"The function that transforms a key/item pair of
this map, producing the item of the resulting map."
Result mapping(Key key, Item item))
given Result satisfies Object //TODO: remove this constraint!
=> object
extends Object()
satisfies Map {
defines(Object key) => outer.defines(key);
shared actual Result? get(Object key) {
if (is Key key) {
return
switch (item = outer.lookup(key))
case (Missing.instance) null
else mapping(key, item);
}
else {
return null;
}
}
shared actual Result|Default
getOrDefault
(Object key, Default default) {
if (is Key key) {
return
switch (item = outer.lookup(key))
case (Missing.instance) default
else mapping(key, item);
}
else {
return default;
}
}
function mapEntry(Key->Item entry)
=> entry.key
-> mapping(entry.key, entry.item);
iterator() => outer.map(mapEntry).iterator();
size => outer.size;
keys => outer.keys;
clone() => outer.clone().mapItems(mapping);
};
"Produces a map containing the elements of this map,
after replacing every `null` item in the map with the
[[given default value|defaultValue]]. The item `null`
does not ocur in the resulting map."
see (`value coalescedMap`)
since("1.2.0")
shared default
Map
defaultNullItems(
"A default value that replaces `null` items."
Default defaultValue)
given Default satisfies Object
=> mapItems((key, elem)
=> elem else defaultValue);
"Produces a map by applying a [[filtering]] function
to the [[keys]] of this map. This is a lazy operation,
returning a view of this map."
since("1.1.0")
shared default
Map filterKeys(
"The predicate function that filters the keys of
this map, determining if there is a corresponding
entry in the resulting map."
Boolean filtering(Key key))
=> object
extends Object()
satisfies Map {
get(Object key)
=> if (is Key key, filtering(key))
then outer[key]
else null;
defines(Object key)
=> if (is Key key, filtering(key))
then outer.defines(key)
else false;
shared actual Item|Default
getOrDefault
(Object key, Default default)
=> if (is Key key, filtering(key))
then outer.getOrDefault(key, default)
else default;
iterator()
=> outer.filter(forKey(filtering))
.iterator();
clone() => outer.clone().filterKeys(filtering);
};
"Produces a map whose keys are the union of the keys
of this map, with the keys of the given [[map|other]].
For any given key in the resulting map, its associated
item is the item associated with the key in the given
map, if any, or the item associated with the key in
this map otherwise.
That is, for any `key` in the resulting patched map:
map.patch(other)[key] == other.getOrDefault(key, map[key])
This is a lazy operation producing a view of this map
and the given map."
since("1.1.0")
shared default
Map
patch
(Map other)
given OtherKey satisfies Object
=> object
extends Object()
satisfies Map {
defines(Object key)
=> other.defines(key) ||
outer.defines(key);
get(Object key)
=> switch (result = other.lookup(key))
case (Missing.instance) outer.get(key)
else result;
shared actual OtherItem|Item|Default
getOrDefault
(Object key, Default default)
=> switch (result = other.lookup(key))
case (Missing.instance)
outer.getOrDefault(key, default)
else result;
clone() => outer.clone().patch(other.clone());
contains(Object entry)
=> if (is Object->Anything entry)
then entry in other ||
!other.defines(entry.key)
&& entry in outer
else false;
//efficient when map is much smaller than outer,
//which is probably the common case
size => outer.size +
other.keys.count(not(outer.defines));
iterator()
=> ChainedIterator(other,
outer.filter(not(other.contains)));
};
"A map with every entry of this map whose item is
non-null."
see (`function defaultNullItems`)
since("1.2.0")
shared default
Map coalescedMap
=> object
extends Object()
satisfies Map {
defines(Object key) => outer[key] exists;
get(Object key) => outer[key] of ?;
shared actual Default|Item&Object
getOrDefault
(Object key, Default default)
=> outer.getOrDefault(key, default)
else default;
iterator()
=> { for (entry in outer)
if (exists it = entry.item)
entry.key -> it }
.iterator();
clone() => outer.clone().coalescedMap;
};
}
"Create a new immutable [[Map]] containing every [[Entry]]
produced by the given [[stream]], resolving items with
duplicate keys according to the given [[function|choosing]].
For example:
map { 1->\"hello\", 2->\"goodbye\" }
produces the map `{ 1->\"hello\", 2->\"goodbye\" }`.
This is an eager operation and the resulting map does not
reflect changes to the given [[stream]]."
since("1.2.0")
shared Map map(
"The stream of entries."
{Item>*} stream,
"A function that chooses between items with duplicate
keys. By default, the item that occurs _earlier_ in the
stream is chosen."
Item choosing(Item earlier, Item later) => earlier)
given Key satisfies Object
=> stream.summarize(Entry.key,
(Item? item, entry)
=> if (exists item)
then choosing(item, entry.item)
else entry.item);
"An immutable [[Map]] with no entries."
tagged("Collections")
shared object emptyMap
extends Object()
satisfies Map {
get(Object key) => null;
shared actual Default getOrDefault
(Object key, Default default) => default;
keys => emptySet;
items => emptySet;
clone() => this;
iterator() => emptyIterator;
size => 0;
empty => true;
defines(Object index) => false;
contains(Object element) => false;
containsAny({Object*} elements) => false;
containsEvery({Object*} elements) => false;
shared actual
Map mapItems
(Result mapping(Nothing key, Nothing item))
given Result satisfies Object //TODO: remove this constraint!
=> emptyMap;
count(Boolean selecting(Nothing->Nothing element)) => 0;
any(Boolean selecting(Nothing->Nothing element)) => false;
every(Boolean selecting(Nothing->Nothing element)) => true;
shared actual
Null find(Boolean selecting(Nothing->Nothing element))
=> null;
shared actual
Null findLast(Boolean selecting(Nothing->Nothing element))
=> null;
skip(Integer skipping) => this;
take(Integer taking) => this;
by(Integer step) => this;
shared actual
void each(void step(Nothing->Nothing element)) {}
}
class Missing of instance {
shared new instance {}
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy