From e691ac617d7d1eaac296d59cc3b6ac3a602fd68f Mon Sep 17 00:00:00 2001 From: James <5511220+Zamiell@users.noreply.github.com> Date: Tue, 19 Jul 2022 21:30:35 -0400 Subject: [PATCH 1/8] more luamap documentation --- docs/advanced/language-extensions.md | 32 ++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/advanced/language-extensions.md b/docs/advanced/language-extensions.md index 8b714f4..b5a047f 100644 --- a/docs/advanced/language-extensions.md +++ b/docs/advanced/language-extensions.md @@ -274,7 +274,7 @@ You can also map functions to table accessors (`__index` and `__newindex`). See ## Lua Table Types -The `LuaTable` type is provided to allow direct creation and manipulation of Lua tables. This is useful if you want to use a table that uses types other than string for its keys, as that is not supported by TypeScript. Calls to lua method tables are translated to simple lua: +The `LuaTable` type is provided to allow direct creation and manipulation of Lua tables. This is useful if you want to use a table that uses types other than string for its keys, as that is not supported by TypeScript. Calls to Lua method tables are translated to simple Lua: - `table.get(key)` Get a value by key -> `table[key]` - `table.set(key, value)` Set a value for key -> `table[key] = value` @@ -328,7 +328,7 @@ print(#tbl) -### Iterating +### Iterating over `LuaTable` To iterate over a `LuaTable`, use `for...of`. This will generate a `for...in` statement using `pairs()`. @@ -366,11 +366,31 @@ end ### `LuaMap` and `LuaSet` -Similar to `LuaTable`, the `LuaMap` and `LuaSet` types are provided to represent Lua tables used as a map or set. These are much more performant than the `Set`/`Map` classes, but do not come with all the same features (such as guaranteed insertion order). +Similar to `LuaTable`, the `LuaMap` and `LuaSet` types are provided to represent Lua tables that are used as a map or a set. These are more performant than the `Set`/`Map` classes, but do not come with all of the same features (such as guaranteed insertion order). -- `LuaMap` has the same methods as `LuaTable`, except that `table.get(key)` may also return `undefined`. -- `LuaSet`, instead of `table.get/table.set`, has `table.add(value)`, which translates to `table[value] = true`. -- There are also the readonly variants `ReadonlyLuaMap` and `ReadonlyLuaSet`. +- `LuaMap` has the same methods as `LuaTable`. The exception is that the type of the return value for the `get` method is `V | undefined` instead of `V`, which makes it similar to how a `Map` works. (For this reason, we recommend using `LuaMap` over `LuaTable`, as it provides compiler-safety guarantees whenever you access a value.) +- `LuaSet` does not have `get` and `set` methods. Instead, it has the `add` method, which transpiles to `table[value] = true`. +- TSTL also provides the read-only variants of `ReadonlyLuaMap` and `ReadonlyLuaSet`, if needed. + +#### Iterating over `LuaMap` & `LuaSet` + +If you need to iterate over a `LuaMap` or `LuaSet`, you do so "implicitly", in the same way that you would for `LuaTable`: + +```ts +const luaMap = new LuaMap(); +for (const [key, value] of luaMap) {} + +const luaSet = new LuaSet(); +for (const value of luaSet) {} +``` + +(Under the hood, both of these for loops would transpile to using `pairs` to iterate over the table.) + +#### Should I use `Map`/`Set` or `LuaMap`/`LuaSet`? + +In general, it is more painful to use `LuaMap` and `LuaSet`, since they don't have methods like `keys`, `values`, `entries`, and `clear`. Additionally, they don't have the `size` attribute to track how large the data structure is. Additionally, using them results in non-idiomatic TypeScript code that may be harder for others to read and understand. + +For these reasons, we recommend using the normal `Map` and `Set` in order to keep things simple. Only use `LuaMap` and `LuaSet` in critical spots where the extra performance boost will really make a difference. ### Custom Getters and Setters From 666fcffc3f4ed6908f449855c532a39bdc6a4984 Mon Sep 17 00:00:00 2001 From: James <5511220+Zamiell@users.noreply.github.com> Date: Tue, 19 Jul 2022 21:32:34 -0400 Subject: [PATCH 2/8] update --- docs/advanced/language-extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/language-extensions.md b/docs/advanced/language-extensions.md index b5a047f..89bf6ad 100644 --- a/docs/advanced/language-extensions.md +++ b/docs/advanced/language-extensions.md @@ -388,7 +388,7 @@ for (const value of luaSet) {} #### Should I use `Map`/`Set` or `LuaMap`/`LuaSet`? -In general, it is more painful to use `LuaMap` and `LuaSet`, since they don't have methods like `keys`, `values`, `entries`, and `clear`. Additionally, they don't have the `size` attribute to track how large the data structure is. Additionally, using them results in non-idiomatic TypeScript code that may be harder for others to read and understand. +In general, it is more painful to use `LuaMap` and `LuaSet`, since they don't have methods like `keys`, `values`, `entries`, and `clear`. Additionally, they don't have the `size` attribute to track how large the data structure is. Furthermore, using them results in non-idiomatic TypeScript code that may be harder for others to read and understand. For these reasons, we recommend using the normal `Map` and `Set` in order to keep things simple. Only use `LuaMap` and `LuaSet` in critical spots where the extra performance boost will really make a difference. From d5031ba1a1c3ece3138d0694f898a08e3242173c Mon Sep 17 00:00:00 2001 From: James <5511220+Zamiell@users.noreply.github.com> Date: Tue, 19 Jul 2022 22:22:07 -0400 Subject: [PATCH 3/8] Update language-extensions.md --- docs/advanced/language-extensions.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/advanced/language-extensions.md b/docs/advanced/language-extensions.md index 89bf6ad..9528fc4 100644 --- a/docs/advanced/language-extensions.md +++ b/docs/advanced/language-extensions.md @@ -388,9 +388,12 @@ for (const value of luaSet) {} #### Should I use `Map`/`Set` or `LuaMap`/`LuaSet`? -In general, it is more painful to use `LuaMap` and `LuaSet`, since they don't have methods like `keys`, `values`, `entries`, and `clear`. Additionally, they don't have the `size` attribute to track how large the data structure is. Furthermore, using them results in non-idiomatic TypeScript code that may be harder for others to read and understand. +`Map`/`Set` support more features than `LuaMap`/`LuaSet`. Namely, they have the `keys`, `entries`, `values`, and `clear` methods, a `size` attribute, and consistent iteration order (in the order of insertion). On the other hand, `LuaMap` and `LuaSet` transpile directly to a Lua table, so they are more lightweight. -For these reasons, we recommend using the normal `Map` and `Set` in order to keep things simple. Only use `LuaMap` and `LuaSet` in critical spots where the extra performance boost will really make a difference. +Thus, you might want to use `LuaMap`/`LuaSet`: +- when the table needs to be serialized +- when you need to interact with other Lua libraries +- when you are in critical paths where the performance really matters (measure first!) ### Custom Getters and Setters From f46cf2f482a0316f03851e701ede1cd37dce6cce Mon Sep 17 00:00:00 2001 From: James <5511220+Zamiell@users.noreply.github.com> Date: Tue, 19 Jul 2022 22:22:44 -0400 Subject: [PATCH 4/8] Update language-extensions.md --- docs/advanced/language-extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/language-extensions.md b/docs/advanced/language-extensions.md index 9528fc4..692cbeb 100644 --- a/docs/advanced/language-extensions.md +++ b/docs/advanced/language-extensions.md @@ -374,7 +374,7 @@ Similar to `LuaTable`, the `LuaMap` and `LuaSet` types are provided to represent #### Iterating over `LuaMap` & `LuaSet` -If you need to iterate over a `LuaMap` or `LuaSet`, you do so "implicitly", in the same way that you would for `LuaTable`: +If you need to iterate over a `LuaMap` or a `LuaSet`, you do so in roughly the same way that you would for `LuaTable`: ```ts const luaMap = new LuaMap(); From ae1298b18bd8e9e7066407a09a1822895e1c45fc Mon Sep 17 00:00:00 2001 From: James <5511220+Zamiell@users.noreply.github.com> Date: Tue, 19 Jul 2022 22:29:23 -0400 Subject: [PATCH 5/8] prettier --- docs/advanced/language-extensions.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/advanced/language-extensions.md b/docs/advanced/language-extensions.md index 692cbeb..e6179d3 100644 --- a/docs/advanced/language-extensions.md +++ b/docs/advanced/language-extensions.md @@ -378,10 +378,12 @@ If you need to iterate over a `LuaMap` or a `LuaSet`, you do so in roughly the s ```ts const luaMap = new LuaMap(); -for (const [key, value] of luaMap) {} +for (const [key, value] of luaMap) { +} const luaSet = new LuaSet(); -for (const value of luaSet) {} +for (const value of luaSet) { +} ``` (Under the hood, both of these for loops would transpile to using `pairs` to iterate over the table.) From 7985e6cd7194bc1f2b365ff3494df2ee63839630 Mon Sep 17 00:00:00 2001 From: James <5511220+Zamiell@users.noreply.github.com> Date: Tue, 19 Jul 2022 22:35:07 -0400 Subject: [PATCH 6/8] more prettier --- docs/advanced/language-extensions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/advanced/language-extensions.md b/docs/advanced/language-extensions.md index e6179d3..4a4096c 100644 --- a/docs/advanced/language-extensions.md +++ b/docs/advanced/language-extensions.md @@ -393,6 +393,7 @@ for (const value of luaSet) { `Map`/`Set` support more features than `LuaMap`/`LuaSet`. Namely, they have the `keys`, `entries`, `values`, and `clear` methods, a `size` attribute, and consistent iteration order (in the order of insertion). On the other hand, `LuaMap` and `LuaSet` transpile directly to a Lua table, so they are more lightweight. Thus, you might want to use `LuaMap`/`LuaSet`: + - when the table needs to be serialized - when you need to interact with other Lua libraries - when you are in critical paths where the performance really matters (measure first!) From 587d6f9fc425d5593d48692f912f4c7f2c5dc5d9 Mon Sep 17 00:00:00 2001 From: James <5511220+Zamiell@users.noreply.github.com> Date: Tue, 19 Jul 2022 22:36:32 -0400 Subject: [PATCH 7/8] Update language-extensions.md --- docs/advanced/language-extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/language-extensions.md b/docs/advanced/language-extensions.md index 4a4096c..781966c 100644 --- a/docs/advanced/language-extensions.md +++ b/docs/advanced/language-extensions.md @@ -396,7 +396,7 @@ Thus, you might want to use `LuaMap`/`LuaSet`: - when the table needs to be serialized - when you need to interact with other Lua libraries -- when you are in critical paths where the performance really matters (measure first!) +- when you are in a critical path where the performance would really matter (measure first!) ### Custom Getters and Setters From f8e891ee578c2805a5f977d7986ffcea27d65fb4 Mon Sep 17 00:00:00 2001 From: James <5511220+Zamiell@users.noreply.github.com> Date: Tue, 19 Jul 2022 22:56:36 -0400 Subject: [PATCH 8/8] Update language-extensions.md --- docs/advanced/language-extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/language-extensions.md b/docs/advanced/language-extensions.md index 781966c..3bfe1ac 100644 --- a/docs/advanced/language-extensions.md +++ b/docs/advanced/language-extensions.md @@ -396,7 +396,7 @@ Thus, you might want to use `LuaMap`/`LuaSet`: - when the table needs to be serialized - when you need to interact with other Lua libraries -- when you are in a critical path where the performance would really matter (measure first!) +- when you are in a critical path where the marginal improved performance would really matter (measure first!) ### Custom Getters and Setters