From 9c9e53485a2e47d898cae6d763b95c87eb837636 Mon Sep 17 00:00:00 2001
From: Nick Fitzgerald <fitzgen@gmail.com>
Date: Tue, 14 Aug 2018 17:15:01 -0700
Subject: [PATCH] guide: Add examples of boxed number slices

---
 .../bootstrap.js                              |  1 +
 .../boxed_number_slices.js                    | 22 +++++++++++++++++++
 .../src/boxed_number_slices.rs                | 17 ++++++++++++++
 .../guide-supported-types-examples/src/lib.rs |  1 +
 guide/src/reference/types.md                  | 19 +++++++++++++---
 5 files changed, 57 insertions(+), 3 deletions(-)
 create mode 100644 examples/guide-supported-types-examples/boxed_number_slices.js
 create mode 100644 examples/guide-supported-types-examples/src/boxed_number_slices.rs

diff --git a/examples/guide-supported-types-examples/bootstrap.js b/examples/guide-supported-types-examples/bootstrap.js
index 5202a4c2..59a2f964 100644
--- a/examples/guide-supported-types-examples/bootstrap.js
+++ b/examples/guide-supported-types-examples/bootstrap.js
@@ -8,3 +8,4 @@ import * as js_value from './js_value.js';
 import * as boxed_js_value_slice from './boxed_js_value_slice.js';
 import * as pointers from './pointers.js';
 import * as numbers from './numbers.js';
+import * as boxed_number_slices from './boxed_number_slices.js';
diff --git a/examples/guide-supported-types-examples/boxed_number_slices.js b/examples/guide-supported-types-examples/boxed_number_slices.js
new file mode 100644
index 00000000..1d3d27dd
--- /dev/null
+++ b/examples/guide-supported-types-examples/boxed_number_slices.js
@@ -0,0 +1,22 @@
+import {
+  take_boxed_number_slice_by_value,
+  return_boxed_number_slice,
+  take_option_boxed_number_slice,
+  return_option_boxed_number_slice,
+} from './guide_supported_types_examples';
+
+take_boxed_number_slice_by_value(new Uint8Array(100));
+
+let x = return_boxed_number_slice();
+console.log(x instanceof Uint32Array); // true
+
+take_option_boxed_number_slice(null);
+take_option_boxed_number_slice(undefined);
+take_option_boxed_number_slice(new Int16Array(256));
+
+let y = return_option_boxed_number_slice();
+if (y == null) {
+  // ...
+} else {
+  console.log(x instanceof Int32Array); // true
+}
diff --git a/examples/guide-supported-types-examples/src/boxed_number_slices.rs b/examples/guide-supported-types-examples/src/boxed_number_slices.rs
new file mode 100644
index 00000000..eb97c714
--- /dev/null
+++ b/examples/guide-supported-types-examples/src/boxed_number_slices.rs
@@ -0,0 +1,17 @@
+use wasm_bindgen::prelude::*;
+
+#[wasm_bindgen]
+pub fn take_boxed_number_slice_by_value(x: Box<[f64]>) {}
+
+#[wasm_bindgen]
+pub fn return_boxed_number_slice() -> Box<[u32]> {
+    (0..42).collect::<Vec<u32>>().into_boxed_slice()
+}
+
+#[wasm_bindgen]
+pub fn take_option_boxed_number_slice(x: Option<Box<[u8]>>) {}
+
+#[wasm_bindgen]
+pub fn return_option_boxed_number_slice() -> Option<Box<[i32]>> {
+    None
+}
diff --git a/examples/guide-supported-types-examples/src/lib.rs b/examples/guide-supported-types-examples/src/lib.rs
index a1db369c..d1aa1d13 100755
--- a/examples/guide-supported-types-examples/src/lib.rs
+++ b/examples/guide-supported-types-examples/src/lib.rs
@@ -13,3 +13,4 @@ pub mod js_value;
 pub mod boxed_js_value_slice;
 pub mod pointers;
 pub mod numbers;
+pub mod boxed_number_slices;
diff --git a/guide/src/reference/types.md b/guide/src/reference/types.md
index b7594883..79e85879 100644
--- a/guide/src/reference/types.md
+++ b/guide/src/reference/types.md
@@ -197,10 +197,23 @@ garbage-collected heap and the Wasm linear memory with `TextDecoder` and
 
 | `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` return value | JavaScript representation |
 |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| Yes | No | No | Yes | Yes | Yes | A JavaScript `TypedArray` view of the Wasm memory for the boxed slice of the appropriate type (`Int32Array`, `Uint8Array`, etc) |
+| Yes | No | No | Yes | Yes | Yes | A JavaScript `TypedArray` of the appropriate type (`Int32Array`, `Uint8Array`, etc...) |
 
-Note that this does ***not*** copy the whole slice of memory back and forth into
-the JavaScript heap from the Wasm linear memory.
+Note that the contents of the slice are copied into the JavaScript `TypedArray`
+from the Wasm linear memory when returning a boxed slice to JavaScript, and vice
+versa when receiving a JavaScript `TypedArray` as a boxed slice in Rust.
+
+### Example Rust Usage
+
+```rust
+{{#include ../../../examples/guide-supported-types-examples/src/boxed_number_slices.rs}}
+```
+
+### Example JavaScript Usage
+
+```js
+{{#include ../../../examples/guide-supported-types-examples/boxed_number_slices.js}}
+```
 
 ## `[u8]` `[i8]` `[u16]` `[i16]` `[u32]` `[i32]` `[u64]` `[i64]` `[f32]` `[f64]`