Bladeren bron

docs: Add section about reading values from the stack

Ole 9 jaren geleden
bovenliggende
commit
14ce5159be
1 gewijzigde bestanden met toevoegingen van 33 en 2 verwijderingen
  1. 33 2
      docs/mkdocs/usage.md

+ 33 - 2
docs/mkdocs/usage.md

@@ -40,11 +40,10 @@ std::tuple<T>    | yes      | no       | *depends on the tuple contents*
 **Note:** Some numeric types have a different size than their matching Lua type - they will be
 truncated during push or read operations.
 
-# From C++ to Lua
+# Pushing C++ values
 When pushing values onto the stack you can either use
 [Value<T>::push](/reference/structluwra_1_1Value.html#aa376d68285606c206562b822e8187384) or the more
 convenient [push](/reference/namespaceluwra.html#ae8e7eab11fc2cf3f258ffd81571066fa).
-See these examples:
 
 ```c++
 // Push an integer
@@ -59,3 +58,35 @@ luwra::push(lua, false);
 // Push a string
 luwra::push(lua, "Hello World");
 ```
+
+This produces the following stack layout:
+
+Absolute Position | Relative Position | Value
+------------------|-------------------|------
+1                 | -4                | `1338`
+2                 | -3                | `13.37`
+3                 | -2                | `false`
+4                 | -1                | `"Hello World"`
+
+It is possible to provide a template parameter to `push` to enforce pushing a specific type.
+In most cases you are probably better off by letting the compiler infer the template parameter.
+
+# Reading Lua values
+Simple retrieval of Lua values is done using
+[read<T>](/reference/namespaceluwra.html#a4fe4e574680cf54a0f8d958740eb90ab). Consider the
+stack layout from the previous example. This is how you would retrieve a value from the stack.
+
+```c++
+// Retrieve the integer at position 1
+int value = luwra::read<int>(lua, 1);
+
+// Similiar with a relative index
+int value = luwra::read<int>(lua, -4);
+```
+
+# Read and type errors
+What happens when a value which you are trying to read mismatches the expected type or cannot be
+converted to it? Most `Value<T>` specializations use Lua's `luaL_check*` functions to retrieve
+the values from the stack. This means that no exceptions will be thrown - instead the error handling
+is delegated to the Lua VM. Have a look at the
+[error handling documentation](http://www.lua.org/manual/5.3/manual.html#4.6) for more information.