diff --git a/doc/site/core/index.markdown b/doc/site/core/index.markdown index f8353e62..3a2dfe0a 100644 --- a/doc/site/core/index.markdown +++ b/doc/site/core/index.markdown @@ -1,4 +1,24 @@ ^title Core Library ^category core -**TODO** \ No newline at end of file +Because Wren is designed for [embedding in applications][embedding], its core +library is minimal and is focused on working with objects within Wren. For +stuff like file IO, graphics, etc., it is up to the host application to provide +interfaces for this. + +All Wren source files automatically have access to the following classes: + +* [Bool](bool.html) +* [Class](class.html) +* [Fiber](fiber.html) +* [Fn](fn.html) +* [List](list.html) +* [Map](map.html) +* [Null](null.html) +* [Num](num.html) +* [Object](object.html) +* [Range](range.html) +* [Sequence](sequence.html) +* [String](string.html) + +[embedding]: ../embedding-api.html \ No newline at end of file diff --git a/doc/site/core/list.markdown b/doc/site/core/list.markdown index 2e7e5863..14ded6dc 100644 --- a/doc/site/core/list.markdown +++ b/doc/site/core/list.markdown @@ -7,7 +7,7 @@ An indexable contiguous collection of elements. More details [here](../lists.htm ### **add**(item) -Appends `item` onto the end of the list. +Appends `item` to the end of the list. ### **clear** @@ -28,12 +28,36 @@ for iterating over the elements in the list. ### **removeAt**(index) -**TODO** +Removes the element at `index`. If `index` is negative, it counts backwards +from the end of the list where `-1` is the last element. All trailing elements +are shifted up to fill in where the removed element was. + + :::dart + var list = ["a", "b", "c", "d"] + list.removeAt(1) + IO.print(list) // "[a, c, d]". + +It is a runtime error if the index is not an integer or is out of bounds. ### **[**index**]** operator -**TODO** +Gets the element at `index`. If `index` is negative, it counts backwards from +the end of the list where `-1` is the last element. + + :::dart + var list = ["a", "b", "c"] + IO.print(list[1]) // "b". + +It is a runtime error if the index is not an integer or is out of bounds. ### **[**index**]=**(item) operator -**TODO** +Replaces the element at `index` with `item`. If `index` is negative, it counts +backwards from the end of the list where `-1` is the last element. + + :::dart + var list = ["a", "b", "c"] + list[1] = "new" + IO.print(list) // "[a, new, c]". + +It is a runtime error if the index is not an integer or is out of bounds. diff --git a/doc/site/core/map.markdown b/doc/site/core/map.markdown new file mode 100644 index 00000000..189f58b2 --- /dev/null +++ b/doc/site/core/map.markdown @@ -0,0 +1,53 @@ +^title Map Class +^category core + +An associative collection that maps keys to values. More details [here](../maps.html). + +### **clear** + +Removes all entries + +### **count** + +The number of entries in the map. + +### **keys** + +A [Sequence](sequence.html) that can be used to iterate over the keys in the +map. Note that iteration order is undefined. All keys will be iterated over, +but may be in any order, and may even change between invocations of Wren. + +### **iterate**(iterator), **iteratorValue**(iterator) + +Implements the [iterator protocol](../control-flow.html#the-iterator-protocol) +for iterating over the elements in the list. + +### **removeAt**(key) + +### **values** + +A [Sequence](sequence.html) that can be used to iterate over the values in the +map. Note that iteration order is undefined. All values will be iterated over, +but may be in any order, and may even change between invocations of Wren. + +If multiple keys are associated with the same value, the value will appear +multiple times in the sequence. + +### **[**key**]** operator + +Gets the value associated with `key` in the map. If `key` is not present in the +map, returns `null`. + + :::dart + var map = {"george": "harrison", "ringo": "starr"} + IO.print(map["ringo"]) // "starr". + IO.print(map["pete"]) // "null". + +### **[**key**]=**(value) operator + +Associates `value` with `key` in the map. If `key` was already in the map, this +replaces the previous association. + +It is a runtime error if the key is not a [Bool](bool.html), +[Class](class.html), [Null](null.html), [Num](num.html), [Range](range.html), +or [String](string.html). diff --git a/doc/site/maps.markdown b/doc/site/maps.markdown index bf0ca205..badd0397 100644 --- a/doc/site/maps.markdown +++ b/doc/site/maps.markdown @@ -1,5 +1,44 @@ ^title Maps ^category types -Wren will have a built-in hash table type similar to objects in JavaScript and -tables in Lua, but they haven't been implemented yet. \ No newline at end of file +A map is an *associative* collection. It holds a set of entries, each of which +maps a *key* to a *value*. The same data structure has a variety of names in +other languages: hash table, dictionary, association, table, etc. + +You can create a map by placing a series of comma-separated entries inside +curly braces. Each entry is a key and a value separated by a colon: + + :::dart + { + "george": "harrison", + "john": "lennon", + "paul": mccartney", + "ringo": "starr" + } + +This creates a map that maps the first names of the Beatles to their last +names. Here, we're using strings for both keys and values. + +Values can be any Wren object, and multiple keys may map to the same value. + +Keys have a few limitations. They must be one of the immutable built-in [value +types](values.html) in Wren. In other words, a number, string, range, bool, or +`null`. You can also use a [class object](classes.html) as a key. Any given key +can only be present in the map once. If you use it twice, the latter replaces +the former's value. + +## Adding entries + +**TODO** + +## Looking up values + +**TODO** + +## Removing entries + +**TODO** + +## Iterating over the contents + +**TODO** diff --git a/doc/site/template-core.html b/doc/site/template-core.html index 1452859c..64b1f38c 100644 --- a/doc/site/template-core.html +++ b/doc/site/template-core.html @@ -31,6 +31,7 @@