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| -> Bool

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

extend

|Map, 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

get

|Map, Key| -> Value

|Map, Key, Value| -> Value

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

get_index

|Map, Number| -> Tuple

|Map, Number, Value| -> 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

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

insert

|Map, Key, Value| -> Value

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

|Map, Key| -> Value

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

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

remove

|Map, Key| -> Value

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

sort

|Map| -> Map

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

|Map, |Value, Value| -> Value| -> Null

Sorts the map's entries based on the output of calling a 'key' function for each entry, and returns the map. The entry's key and value are passed into the function as separate arguments.

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

Example

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

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

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

update

|Map, Key, |Value| -> Value| -> Value

Updates the value associated with a given key by calling a function with either the existing value, or Null if there isn't a matching entry.

The result of the function will either replace an existing value, or if no value existed then an entry will be inserted into the map with the given key and the function's result.

The function result is then returned from update.

|Map, Key, Value, |Value| -> Value| -> Value

This variant of update takes a default value that is provided to the function if a matching entry doesn't exist.

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

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

with_meta

|Map, 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

Docs Playground