Merge pull request #696 from fitzgen/more-examples-for-guide

More examples for guide

examples/guide-supported-types-examples/bool.js

@@ -0,0 +1,9 @@
+import {
+  take_char_by_value,
+  return_char,
+} from './guide_supported_types_examples';
+
+take_bool_by_value(true);
+
+let b = return_bool();
+console.log(typeof b); // "boolean"

examples/guide-supported-types-examples/boxed_js_value_slice.js

@@ -0,0 +1,22 @@
+import {
+  take_boxed_js_value_slice_by_value,
+  return_boxed_js_value_slice,
+  take_option_boxed_js_value_slice,
+  return_option_boxed_js_value_slice,
+} from './guide_supported_types_examples';
+
+take_boxed_js_value_slice_by_value([null, true, 2, {}, []]);
+
+let values = return_boxed_js_value_slice();
+console.log(values instanceof Array); // true
+
+take_option_boxed_js_value_slice(null);
+take_option_boxed_js_value_slice(undefined);
+take_option_boxed_js_value_slice([1, 2, 3]);
+
+let maybeValues = return_option_boxed_js_value_slice();
+if (maybeValues == null) {
+  // ...
+} else {
+  console.log(maybeValues instanceof Array); // true
+}

examples/guide-supported-types-examples/char.js

@@ -0,0 +1,9 @@
+import {
+  take_char_by_value,
+  return_char,
+} from './guide_supported_types_examples';
+
+take_char_by_value('a');
+
+let c = return_char();
+console.log(typeof c); // "string"

examples/guide-supported-types-examples/exported_types.js

@@ -1 +1,14 @@
-console.log("todo")
+import {
+  ExportedRustType,
+  exported_type_by_value,
+  exported_type_by_shared_ref,
+  exported_type_by_exclusive_ref,
+  return_exported_type,
+} from './guide_supported_types_examples';
+
+let rustThing = return_exported_type();
+console.log(rustThing instanceof ExportedRustType); // true
+
+exported_type_by_value(rustThing);
+exported_type_by_shared_ref(rustThing);
+exported_type_by_exclusive_ref(rustThing);

examples/guide-supported-types-examples/imported_types.js

@@ -10,8 +10,7 @@ imported_type_by_value(new SomeJsType());
 imported_type_by_shared_ref(new SomeJsType());
 
 let x = return_imported_type();
-console.log(x instanceof SomeJsType);
+console.log(x instanceof SomeJsType); // true
-// true
 
 take_option_imported_type(null);
 take_option_imported_type(undefined);
@@ -21,6 +20,5 @@ let y = return_option_imported_type();
 if (y == null) {
   // ...
 } else {
-  console.log(y instanceof SomeJsType);
+  console.log(y instanceof SomeJsType); // true
-  // true
 }

examples/guide-supported-types-examples/js_value.js

@@ -0,0 +1,10 @@
+import {
+  take_js_value_by_value,
+  take_js_value_by_shared_ref,
+  return_js_value,
+} from './guide_supported_types_examples';
+
+take_js_value_by_value(42);
+take_js_value_by_shared_ref('hello');
+
+let v = return_js_value();

examples/guide-supported-types-examples/src/bool.rs

@@ -0,0 +1,9 @@
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+pub fn take_bool_by_value(x: bool) {}
+
+#[wasm_bindgen]
+pub fn return_bool() -> bool {
+    true
+}

examples/guide-supported-types-examples/src/boxed_js_value_slice.rs

@@ -0,0 +1,17 @@
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+pub fn take_boxed_js_value_slice_by_value(x: Box<[JsValue]>) {}
+
+#[wasm_bindgen]
+pub fn return_boxed_js_value_slice() -> Box<[JsValue]> {
+    vec![JsValue::NULL, JsValue::UNDEFINED].into_boxed_slice()
+}
+
+#[wasm_bindgen]
+pub fn take_option_boxed_js_value_slice(x: Option<Box<[JsValue]>>) {}
+
+#[wasm_bindgen]
+pub fn return_option_boxed_js_value_slice() -> Option<Box<[JsValue]>> {
+    None
+}

examples/guide-supported-types-examples/src/char.rs

@@ -0,0 +1,9 @@
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+pub fn take_char_by_value(x: char) {}
+
+#[wasm_bindgen]
+pub fn return_char() -> char {
+    '🚀'
+}

examples/guide-supported-types-examples/src/exported_types.rs

@@ -1,6 +1,20 @@
 use wasm_bindgen::prelude::*;
 
 #[wasm_bindgen]
-pub struct RustType {
+pub struct ExportedRustType {
     inner: u32,
 }
+
+#[wasm_bindgen]
+pub fn exported_type_by_value(x: ExportedRustType) {}
+
+#[wasm_bindgen]
+pub fn exported_type_by_shared_ref(x: &ExportedRustType) {}
+
+#[wasm_bindgen]
+pub fn exported_type_by_exclusive_ref(x: &mut ExportedRustType) {}
+
+#[wasm_bindgen]
+pub fn return_exported_type() -> ExportedRustType {
+    unimplemented!()
+}

examples/guide-supported-types-examples/src/js_value.rs

@@ -0,0 +1,12 @@
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+pub fn take_js_value_by_value(x: JsValue) {}
+
+#[wasm_bindgen]
+pub fn take_js_value_by_shared_ref(x: &JsValue) {}
+
+#[wasm_bindgen]
+pub fn return_js_value() -> JsValue {
+    JsValue::NULL
+}

examples/guide-supported-types-examples/src/lib.rs

@@ -5,3 +5,9 @@ extern crate wasm_bindgen;
 
 pub mod imported_types;
 pub mod exported_types;
+pub mod str;
+pub mod string;
+pub mod char;
+pub mod bool;
+pub mod js_value;
+pub mod boxed_js_value_slice;

examples/guide-supported-types-examples/src/str.rs

@@ -0,0 +1,4 @@
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+pub fn take_str_by_shared_ref(x: &str) {}

examples/guide-supported-types-examples/src/string.rs

@@ -0,0 +1,17 @@
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+pub fn take_string_by_value(x: String) {}
+
+#[wasm_bindgen]
+pub fn return_string() -> String {
+    "hello".into()
+}
+
+#[wasm_bindgen]
+pub fn take_option_string(x: Option<String>) {}
+
+#[wasm_bindgen]
+pub fn return_option_string() -> Option<String> {
+    None
+}

examples/guide-supported-types-examples/str.js

@@ -0,0 +1,5 @@
+import {
+  take_str_by_shared_ref,
+} from './guide_supported_types_examples';
+
+take_str_by_shared_ref('hello');

examples/guide-supported-types-examples/string.js

@@ -0,0 +1,22 @@
+import {
+  take_string_by_value,
+  return_string,
+  take_option_string,
+  return_option_string,
+} from './guide_supported_types_examples';
+
+take_string_by_value('hello');
+
+let s = return_string();
+console.log(typeof s); // "string"
+
+take_option_string(null);
+take_option_string(undefined);
+take_option_string('hello');
+
+let t = return_option_string();
+if (t == null) {
+  // ...
+} else {
+  console.log(typeof s); // "string"
+}

guide/src/reference/types.md

@@ -26,7 +26,7 @@ JavaScript.
 
 | `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` return value | JavaScript representation |
 |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| Yes | Yes | Yes | Yes | Yes | Yes | Instances of a `wasm-bindgen`-generated JavaScript `class Whatever { ... }` |
+| Yes | Yes | Yes | Yes | No | No | Instances of a `wasm-bindgen`-generated JavaScript `class Whatever { ... }` |
 
 ### Example Rust Usage
 
@@ -44,13 +44,25 @@ JavaScript.
 
 | `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` return value | JavaScript representation |
 |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| No | Yes | No | Yes | Yes | No | JavaScript string value |
+| No | Yes | No | No | No | No | JavaScript string value |
 
 Copies the string's contents back and forth between the JavaScript
 garbage-collected heap and the Wasm linear memory with `TextDecoder` and
 `TextEncoder`. If you don't want to perform this copy, and would rather work
 with handles to JavaScript string values, use the `js_sys::JsString` type.
 
+### Example Rust Usage
+
+```rust
+{{#include ../../../examples/guide-supported-types-examples/src/str.rs}}
+```
+
+### Example JavaScript Usage
+
+```js
+{{#include ../../../examples/guide-supported-types-examples/str.js}}
+```
+
 ## `String`
 
 | `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` return value | JavaScript representation |
@@ -61,23 +73,71 @@ Copies the string's contents back and forth between the JavaScript
 garbage-collected heap and the Wasm linear memory with `TextDecoder` and
 `TextEncoder`
 
+### Example Rust Usage
+
+```rust
+{{#include ../../../examples/guide-supported-types-examples/src/string.rs}}
+```
+
+### Example JavaScript Usage
+
+```js
+{{#include ../../../examples/guide-supported-types-examples/string.js}}
+```
+
 ## `char`
 
 | `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` return value | JavaScript representation |
 |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
 | Yes | No | No | Yes | No | No | A JavaScript string value |
 
+### Example Rust Usage
+
+```rust
+{{#include ../../../examples/guide-supported-types-examples/src/char.rs}}
+```
+
+### Example JavaScript Usage
+
+```js
+{{#include ../../../examples/guide-supported-types-examples/char.js}}
+```
+
 ## `bool`
 
 | `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` return value | JavaScript representation |
 |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
 | Yes | No | No | Yes | No | No | A JavaScript boolean value |
 
+### Example Rust Usage
+
+```rust
+{{#include ../../../examples/guide-supported-types-examples/src/bool.rs}}
+```
+
+### Example JavaScript Usage
+
+```js
+{{#include ../../../examples/guide-supported-types-examples/bool.js}}
+```
+
 ## `wasm_bindgen::JsValue`
 
 | `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` return value | JavaScript representation |
 |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| Yes | Yes | Yes | Yes | No | No | Any JavaScript value |
+| Yes | Yes | No | Yes | No | No | Any JavaScript value |
+
+### Example Rust Usage
+
+```rust
+{{#include ../../../examples/guide-supported-types-examples/src/js_value.rs}}
+```
+
+### Example JavaScript Usage
+
+```js
+{{#include ../../../examples/guide-supported-types-examples/js_value.js}}
+```
 
 ## `Box<[JsValue]>`
 
@@ -85,6 +145,18 @@ garbage-collected heap and the Wasm linear memory with `TextDecoder` and
 |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
 | Yes | No | No | Yes | Yes | Yes | A JavaScript `Array` object |
 
+### Example Rust Usage
+
+```rust
+{{#include ../../../examples/guide-supported-types-examples/src/boxed_js_value_slice.rs}}
+```
+
+### Example JavaScript Usage
+
+```js
+{{#include ../../../examples/guide-supported-types-examples/boxed_js_value_slice.js}}
+```
+
 ## `*const T` `*mut T`
 
 | `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` return value | JavaScript representation |