Merge pull request #13 from jonas-schievink/example

Add a few examples

src/lua.rs

@@ -168,6 +168,23 @@ pub struct LuaString<'lua>(LuaRef<'lua>);
 
 impl<'lua> LuaString<'lua> {
     /// Get a `&str` slice if the Lua string is valid UTF-8.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate rlua;
+    /// # use rlua::*;
+    /// # fn main() {
+    /// let lua = Lua::new();
+    /// let globals = lua.globals().unwrap();
+    ///
+    /// let version: LuaString = globals.get("_VERSION").unwrap();
+    /// assert!(version.to_str().unwrap().contains("Lua"));
+    ///
+    /// let non_utf8: LuaString = lua.eval(r#"  "test\xff"  "#).unwrap();
+    /// assert!(non_utf8.to_str().is_err());
+    /// # }
+    /// ```
     pub fn to_str(&self) -> LuaResult<&str> {
         let lua = self.0.lua;
         unsafe {
@@ -494,6 +511,26 @@ impl<'lua> LuaFunction<'lua> {
     ///     return function() f(...) end
     /// end
     /// ```
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate rlua;
+    /// # use rlua::*;
+    ///
+    /// # fn main() {
+    /// let lua = Lua::new();
+    /// let globals = lua.globals().unwrap();
+    ///
+    /// // Bind the argument `123` to Lua's `tostring` function
+    /// let tostring: LuaFunction = globals.get("tostring").unwrap();
+    /// let tostring_123: LuaFunction = tostring.bind(123i32).unwrap();
+    ///
+    /// // Now we can call `tostring_123` without arguments to get the result of `tostring(123)`
+    /// let result: String = tostring_123.call(()).unwrap();
+    /// assert_eq!(result, "123");
+    /// # }
+    /// ```
     pub fn bind<A: ToLuaMulti<'lua>>(&self, args: A) -> LuaResult<LuaFunction<'lua>> {
         unsafe extern "C" fn bind_call_impl(state: *mut ffi::lua_State) -> c_int {
             let nargs = ffi::lua_gettop(state);
@@ -569,6 +606,34 @@ impl<'lua> LuaThread<'lua> {
     ///
     /// If the thread calls `coroutine.yield`, returns the values passed to `yield`. If the thread
     /// `return`s values from its main function, returns those.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # extern crate rlua;
+    /// # use rlua::*;
+    ///
+    /// # fn main() {
+    /// let lua = Lua::new();
+    /// let thread: LuaThread = lua.eval(r#"
+    ///     coroutine.create(function(arg)
+    ///         assert(arg == 42)
+    ///         local yieldarg = coroutine.yield(123)
+    ///         assert(yieldarg == 43)
+    ///         return 987
+    ///     end)
+    /// "#).unwrap();
+    ///
+    /// assert_eq!(thread.resume::<_, u32>(42).unwrap(), 123);
+    /// assert_eq!(thread.resume::<_, u32>(43).unwrap(), 987);
+    ///
+    /// // The coroutine has now returned, so `resume` will fail
+    /// match thread.resume::<_, u32>(()) {
+    ///     Err(LuaError(LuaErrorKind::CoroutineInactive, _)) => {},
+    ///     unexpected => panic!("unexpected result {:?}", unexpected),
+    /// }
+    /// # }
+    /// ```
     pub fn resume<A, R>(&self, args: A) -> LuaResult<R>
     where
         A: ToLuaMulti<'lua>,