abstract rtconst class std::Map

sys::Obj
  std::Map

@Serializable

Map is a hash map of key/value pairs.

See examples.

add

abstract This add(Map^K key, Map^V val)

Add the specified key/value pair to the map. If the key is already mapped, then throw the ArgErr. Return this. If key does not return true for Obj.isImmutable, then throw NotImmutableErr. If key is null throw NullErr. Throw ReadonlyErr if readonly.

addAll

This addAll(Map<Map^K,Map^V> m)

Append the specified map to this map by adding every key/value in m in this map. If any key in m is already mapped then this method will fail (any previous keys will remain mapped potentially leaving this map in an inconsistent state). Return this. Throw ReadonlyErr if readonly. Also see setAll. This method is semanatically equivalent to:

m.each |v, k| { this.add(k, v) }

addIfNotNull

This addIfNotNull(Map^K key, Map^V? val)

Call add if val is non-null otherwise do nothing. Return this.

addList

This addList(List<Map^V> list, Func<Map^K,Map^V,Int>? c := null)

Add the specified list to this map where the values are the list items and the keys are derived by calling the specified function on each item. If the function is null, then the items themselves are used as the keys. If any key already mapped then this method will fail (any previous keys will remain mapped potentially leaving this map in an inconsistent state). Return this. Throw ReadonlyErr if readonly. Also see setList.

Examples:

m := [0:"0"]
m.addList(["1","2"]) |Str s->Int| { return s.toInt }
m  =>  [0:0, 1:1, 2:2]

all

Bool all(Func<Bool,Map^V,Map^K> c)

Return true if c returns true for all of the key/value pairs in the map. If the list is empty, return true. This method is readonly safe.

any

Bool any(Func<Bool,Map^V,Map^K> c)

Return true if c returns true for any of the key/value pairs in the map. If the map is empty, return false. This method is readonly safe.

clear

abstract This clear()

Remove all key/value pairs from the map. Return this. Throw ReadonlyErr if readonly.

containsKey

abstract Bool containsKey(Map^K key)

Return if the specified key is mapped. This method is readonly safe.

createEmpty

protected abstract This createEmpty()

defV

virtual Map^V? defV := null

The default value to use for get when a key isn't mapped. This field defaults to null. The value of def must be immutable or NotImmutableErr is thrown. Getting this field is readonly safe. Throw ReadonlyErr if set when readonly.

defVal

const static Map<Obj,Obj> defVal := Map<Obj,Obj>[:]

dup

virtual This dup()

Create a shallow duplicate copy of this Map. The keys and values themselves are not duplicated. This method is readonly safe.

each

abstract Void each(Func<Void,Map^V,Map^K> c)

Call the specified function for every key/value in the list. This method is readonly safe.

eachWhile

abstract Obj? eachWhile(Func<Obj?,Map^V,Map^K> c)

Iterate every key/value pair in the map until the function returns non-null. If function returns non-null, then break the iteration and return the resulting object. Return null if the function returns null for every key/value pair. This method is readonly safe.

equals

virtual override Bool equals(Obj? that)

Two Maps are equal if they have the same type and number of equal key/value pairs.

Examples:

a := Int:Str[1:"one", 2:"two"]
b := Int:Str[2:"two", 1:"one"]
c := Int:Str?[2:"two", 1:"one"]
a == b  =>  true
a == c  =>  false

exclude

This exclude(Func<Bool,Map^V,Map^K> c)

Return a new map containing the key/value pairs for which c returns false. If c returns true for every item, then return an empty list. The inverse of this method is findAll. If this map is ordered or caseInsensitive, then the resulting map is too. This method is readonly safe.

Example:

map := ["off":0, "slow":50, "fast":100]
map.exclude |Int v->Bool| { return v == 0 } => ["slow":50, "fast":100]

find

Map^V? find(Func<Bool,Map^V,Map^K> c)

Return the first value in the map for which c returns true. If c returns false for every pair, then return null. This method is readonly safe.

findAll

This findAll(Func<Bool,Map^V,Map^K> c)

Return a new map containing the key/value pairs for which c returns true. If c returns false for every item, then return an empty map. The inverse of this method is exclude. If this map is ordered or caseInsensitive, then the resulting map is too. This method is readonly safe.

get

@Operator
abstract Map^V? get(Map^K key, Map^V? defValue := this.defV)

Get the value for the specified key. If key is not mapped, then return the value of the def parameter. If def is omitted it defaults to the def field. This method is readonly safe. Shortcut is a[key].

getChecked

Map^V? getChecked(Map^K key, Bool checked := true)

Get the value for the specified key. If the key is not mapped then return null or raise UnknownKeyEr based on checked flag. This method is readonly safe.

getOrAdd

Map^V getOrAdd(Map^K key, Func<Map^V,Map^K> valFunc)

Get the value for the specified key, or if it doesn't exist then automatically add it. The value function is called to get the value to add, it is only called if the key is not mapped. Throw ReadonlyErr if readonly only if add is required.

getOrThrow

Map^V getOrThrow(Obj key)

Get the value for the specified key or if key is not mapped then raise UnknownKeyErr. This method is readonly safe.

hash

virtual override Int hash()

Return platform dependent hashcode based on hash of the keys and values.

isEmpty

Bool isEmpty()

Return if size() == 0. This method is readonly safe.

isImmutable

abstract override Bool isImmutable()

isRO

abstract Bool isRO()

Return if this Map is readonly. A readonly Map is guaranteed to be immutable (although its values may be mutable themselves). Any attempt to modify a readonly Map will result in ReadonlyErr. Use rw to get a read-write Map from a readonly Map. Methods documented as "readonly safe" may be used safely with a readonly Map. This method is readonly safe.

isRW

Bool isRW()

Return if this Map is read-write. A read-write Map is mutable and may be modified. Use r`o` to get a readonly Map from a read-write Map. This method is readonly safe.

join

virtual Str join(Str separator, Func<Str,Map^V,Map^K>? c := null)

Return a string by concatenating each key/value pair using the specified separator string. If c is non-null then it is used to format each pair into a string, otherwise "$k: $v" is used. This method is readonly safe.

Example:

keys

abstract List<Map^K> keys()

Get a list of all the mapped keys. This method is readonly safe.

make

static new make(Int capacity := 16)

Constructor

map

Map<Map^K,Obj?> map(Func<Obj?,Map^V,Map^K> c)

Create a new map with the same keys, but apply the specified closure to generate new values. The new mapped is typed based on the return type of c. If this map is ordered or caseInsensitive, then the resulting map is too. This method is readonly safe.

Example:

m := [2:2, 3:3, 4:4]
x := m.map |Int v->Int| { return v*2 }
x => [2:4, 3:6, 4:8]

modify

protected abstract Void modify()

privateMake

new privateMake()

reduce

Obj? reduce(Obj? init, Func<Obj?,Obj?,Map^V,Map^K> c)

Reduce is used to iterate through every value in the map to reduce the map into a single value called the reduction. The initial value of the reduction is passed in as the init parameter, then passed back to the closure along with each item. This method is readonly safe.

Example:

m := ["2":2, "3":3, "4":4]
m.reduce(100) |Obj r, Int v->Obj| { return (Int)r + v } => 109

remove

abstract Map^V? remove(Map^K key)

Remove the key/value pair identified by the specified key from the map and return the value. If the key was not mapped then return null. Throw ReadonlyErr if readonly.

ro

abstract This ro()

Get a readonly Map instance with the same contents as this Map (although its values may be mutable themselves). If this Map is already readonly, then return this. Only methods documented as "readonly safe" may be used safely with a readonly Map, all others will throw ReadonlyErr. This method is readonly safe.

rw

abstract This rw()

Get a read-write, mutable Map instance with the same contents as this Map. If this Map is already read-write, then return this. This method is readonly safe.

set

@Operator
abstract This set(Map^K key, Map^V val)

Set the value for the specified key. If the key is already mapped, this overwrites the old value. If key is not yet mapped this adds the key/value pair to the map. Return this. If key does not return true for Obj.isImmutable, then throw NotImmutableErr. If key is null throw NullErr. Throw ReadonlyErr if readonly.

setAll

This setAll(Map<Map^K,Map^V> m)

Append the specified map to this map by setting every key/value in m in this map. Keys in m not yet mapped are added and keys already mapped are overwritten. Return this. Throw ReadonlyErr if readonly. Also see addAll. This method is semanatically equivalent to:

m.each |v, k| { this.set(k, v) }

setList

This setList(List<Map^V> list, Func<Map^K,Map^V,Int>? c := null)

Add the specified list to this map where the values are the list items and the keys are derived by calling the specified function on each item. If the function is null, then the items themselves are used as the keys. If any key already mapped then it is overwritten. Return this. Throw ReadonlyErr if readonly. Also see addList.

Examples:

m := [0:"0", 2:"old"]
m.setList(["1","2"]) |Str s->Int| { return s.toInt }
m  =>  [0:0, 1:1, 2:2]

size

abstract Int size()

Get the number of key/value pairs in the list. This method is readonly safe.

toCode

Str toCode()

Get this map as a Fantom expression suitable for code generation. The individual keys and values must all respond to the toCode method.

toImmutable

abstract override Map<Map^K,Map^V> toImmutable()

toStr

virtual override Str toStr()

Return a string representation the Map. This method is readonly safe.

vals

abstract List<Map^V> vals()

Get a list of all the mapped values. This method is readonly safe.