map

clear

|Map| -> Map

Clears the map by removing all of its elements, and returns the map.

Example

x = {x: -1, y: 42}
x.clear()
#: {}
x
#: {}

contains_key

|Map, key: Any| -> Bool

Returns true if the map contains a value with the given key, and false otherwise.

extend

|Map, new_entries: Iterable| -> Map

Extends the map with the output of the iterator, and returns the map.

Example

x = {foo: 42, bar: 99}
x.extend {baz: 123}
#: {foo: 42, bar: 99, baz: 123}
x.baz
#: 123

x = {}
x.extend 'abc'.each |c| c, '{c}!'
#: {a: 'a!', b: 'b!', c: 'c!'}
x.c
#: c!

See also

• map.insert

get

|Map, key: Any| -> Any

|Map, key: Any, default: Any| -> Any

Returns the value corresponding to the given key, or the provided default value if the map doesn't contain the key.

If no default value is provided then null is returned.

Example

x = {hello: -1}
x.get 'hello'
#: -1

x.get 'goodbye'
#: null

x.get 'goodbye', 'byeeee'
#: byeeee

x.insert 99, 'xyz'
x.get 99
#: xyz

See also

• map.get_index

get_index

|Map, index: Number| -> Tuple

|Map, index: Number, default: Any| -> Tuple

Returns the entry at the given index as a key/value tuple, or the provided default value if the map doesn't contain an entry at that index.

If no default value is provided then null is returned.

Example

x = {foo: -1, bar: -2}
x.get_index 1
#: ('bar', -2)

x.get_index -99
#: null

x.get_index 99, 'xyz'
#: xyz

See also

• map.get

get_meta

|Map| -> Map

Returns a Map that contains the input's Meta Map, and no data.

Example

my_map =
  data: 42
  @type: 'My Map'

meta = map.get_meta my_map

map.keys(my_map).count()
#: 1
map.keys(meta).count()
#: 0

koto.type meta
#: My Map

See also

• map.with_meta

insert

|Map, key: Any, value: Any| -> Any

Inserts an entry into the map with the given key and value.

|Map, key: Any| -> Any

Inserts an entry into the map with the given key, and null as its value.

If the key already existed in the map, then the old value is returned. If the key didn't already exist, then null is returned.

See the language guide for a description of the types of values that can be used as map keys.

Example

x = {hello: -1}

x.insert 'hello', 99 # -1 already exists at `hello`, so it's returned here
#: -1

x.hello # hello is now 99
#: 99

x.insert 'goodbye', 123 # No existing value at `goodbye`, so null is returned
#: null

x.goodbye
#: 123

x.insert 123, 'hi!' # Numbers can be used as map keys
#: null

x.get 123
#: hi!

x.insert ('a', 'b'), -1 # Tuples can be used as map keys
#: null

x.get ('a', 'b')
#: -1

See also

• map.get
• map.remove
• map.update

is_empty

|Map| -> Bool

Returns true if the map contains no entries, otherwise false.

Example

{}.is_empty()
#: true

{hello: -1}.is_empty()
#: false

keys

|Map| -> Iterator

Returns an iterator that iterates in order over the map's keys.

Example

m =
  hello: -1
  goodbye: 99

x = m.keys()

x.next().get()
#: hello

x.next().get()
#: goodbye

x.next()
#: null

See also

• map.values

remove

|Map, key: Any| -> Any

Removes the entry that matches the given key.

If the entry existed then its value is returned, otherwise null is returned.

Example

x =
  hello: -1
  goodbye: 99

x.remove 'hello'
#: -1

x.remove 'xyz'
#: null

x.remove 'goodbye'
#: 99

x.is_empty()
#: true

See also

• map.insert

sort

|Map| -> Map

Sorts the map's entries in place by key, and then returns the map.

|
  Map,
  sort_key: |key: Any, value: Any| -> Any
| -> Null

Sorts the map's entries in place based on the output of calling a 'sort' function for each entry, and then returns the map.

The entry's key and value are passed into the sort_key function as separate arguments.

The function's result is cached, so it only gets called once per entry.

Example

x =
  hello: 123
  bye: -1
  tschüss: 99

# Sort the map by key
x.sort()
#: {bye: -1, hello: 123, tschüss: 99}

# Sort the map by value
x.sort |_, value| value
#: {bye: -1, tschüss: 99, hello: 123}

# Sort the map by reversed key length
x.sort |key, _| -(size key)
#: {tschüss: 99, hello: 123, bye: -1}

update

|Map, key: Any, updater: |Any| -> Any| -> Any

Updates the value associated with a given key by calling the updater function.

If an entry exists with the given key, then updater will be called with the existing entry's value, and the result of the function will replace the existing value.

If no entry exists with the given key, then updater will be called with null, and the result will be inserted into the map as a new entry.

The return value is the result of calling the updater function.

|Map, key: Any, default: Any, updater: |Any| -> Any| -> Any

This variant of update takes a default value that is provided to the updater function if no entry exists with the given key.

Example

x =
  hello: -1
  goodbye: 99

x.update 'hello', |n| n * 2
#: -2
x.hello
#: -2

x.update 'tschüss', 10, |n| n * 10
#: 100
x.tschüss
#: 100

See also

• map.insert

values

|Map| -> Iterator

Returns an iterator that iterates in order over the map's values.

Example

m =
  hello: -1
  goodbye: 99

x = m.values()

x.next().get()
#: -1

x.next().get()
#: 99

x.next()
#: null

See also

• map.keys

with_meta

|data: Map, meta: Map| -> Map

Returns a new Map that contains the data from the first argument, along with the Meta Map from the second argument.

Example

my_meta =
  @type: 'MyMeta'

x = {foo: 42}.with_meta my_meta

koto.type x
#: MyMeta

See also

• map.get_meta