diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index 3f462613..720e4b84 100644 --- a/guide/src/SUMMARY.md +++ b/guide/src/SUMMARY.md @@ -16,6 +16,18 @@ - [Arbitrary Data with Serde](./reference/arbitrary-data-with-serde.md) - [Command Line Interface](./reference/cli.md) - [Supported Types](./reference/types.md) + - [Imported JavaScript Types](./reference/types/imported-js-types.md) + - [Exported Rust Types](./reference/types/exported-rust-types.md) + - [`JsValue`](./reference/types/jsvalue.md) + - [`Box<[JsValue]>`](./reference/types/boxed-jsvalue-slice.md) + - [`*const T` and `*mut T`](./reference/types/pointers.md) + - [Numbers](./reference/types/numbers.md) + - [`bool`](./reference/types/bool.md) + - [`char`](./reference/types/char.md) + - [`str`](./reference/types/str.md) + - [`String`](./reference/types/string.md) + - [Number Slices](./reference/types/number-slices.md) + - [Boxed Number Slices](./reference/types/boxed-number-slices.md) - [`#[wasm_bindgen]` Attributes](./reference/attributes/index.md) - [On JavaScript Imports](./reference/attributes/on-js-imports/index.md) - [`catch`](./reference/attributes/on-js-imports/catch.md) diff --git a/guide/src/reference/types.md b/guide/src/reference/types.md index f063e7ce..a1eaf6fb 100644 --- a/guide/src/reference/types.md +++ b/guide/src/reference/types.md @@ -3,232 +3,3 @@ This section provides an overview of all the types that `wasm-bindgen` can send and receive across the WebAssembly ABI boundary, and how they translate into JavaScript. - -## Imported `extern Whatever;` JavaScript Types - -| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | -|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| Yes | Yes | No | Yes | Yes | Yes | Instances of the extant `Whatever` JavaScript class / prototype constructor | - -### Example Rust Usage - -```rust -{{#include ../../../examples/guide-supported-types-examples/src/imported_types.rs}} -``` - -### Example JavaScript Usage - -```js -{{#include ../../../examples/guide-supported-types-examples/imported_types.js}} -``` - -## Exported `struct Whatever` Rust Types - -| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | -|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| Yes | Yes | Yes | Yes | No | No | Instances of a `wasm-bindgen`-generated JavaScript `class Whatever { ... }` | - -### Example Rust Usage - -```rust -{{#include ../../../examples/guide-supported-types-examples/src/exported_types.rs}} -``` - -### Example JavaScript Usage - -```js -{{#include ../../../examples/guide-supported-types-examples/exported_types.js}} -``` - -## `str` - -| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | -|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| 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` parameter | `Option` return value | JavaScript representation | -|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| Yes | No | No | Yes | Yes | Yes | 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` - -### 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` parameter | `Option` 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` parameter | `Option` return value | JavaScript representation | -|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| Yes | No | No | Yes | Yes | Yes | 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` parameter | `Option` return value | JavaScript representation | -|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| 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]>` - -| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | -|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| 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` parameter | `Option` return value | JavaScript representation | -|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| Yes | No | No | Yes | No | No | A JavaScript number value | - -### Example Rust Usage - -```rust -{{#include ../../../examples/guide-supported-types-examples/src/pointers.rs}} -``` - -### Example JavaScript Usage - -```js -{{#include ../../../examples/guide-supported-types-examples/pointers.js}} -``` - -## `u8` `i8` `u16` `i16` `u32` `i32` `u64` `i64` `isize` `usize` `f32` `f64` - -| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | -|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| Yes | No | No | Yes | Yes | Yes | A JavaScript number value | - -### Example Rust Usage - -```rust -{{#include ../../../examples/guide-supported-types-examples/src/numbers.rs}} -``` - -### Example JavaScript Usage - -```js -{{#include ../../../examples/guide-supported-types-examples/numbers.js}} -``` - -## `Box<[u8]>` `Box<[i8]>` `Box<[u16]>` `Box<[i16]>` `Box<[u32]>` `Box<[i32]>` `Box<[u64]>` `Box<[i64]>` `Box<[f32]>` `Box<[f64]>` - -| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | -|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| Yes | No | No | Yes | Yes | Yes | A JavaScript `TypedArray` of the appropriate type (`Int32Array`, `Uint8Array`, etc...) | - -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]` - -| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<&T>` parameter | `Option` return value | JavaScript representation | -|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| No | Yes | Yes | No | No | No | A JavaScript `TypedArray` view of the Wasm memory for the boxed slice of the appropriate type (`Int32Array`, `Uint8Array`, etc) | - -### Example Rust Usage - -```rust -{{#include ../../../examples/guide-supported-types-examples/src/number_slices.rs}} -``` - -### Example JavaScript Usage - -```js -{{#include ../../../examples/guide-supported-types-examples/number_slices.js}} -``` diff --git a/guide/src/reference/types/bool.md b/guide/src/reference/types/bool.md new file mode 100644 index 00000000..6859de8c --- /dev/null +++ b/guide/src/reference/types/bool.md @@ -0,0 +1,17 @@ +# `bool` + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | +|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| Yes | No | No | Yes | Yes | Yes | 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}} +``` diff --git a/guide/src/reference/types/boxed-jsvalue-slice.md b/guide/src/reference/types/boxed-jsvalue-slice.md new file mode 100644 index 00000000..c349ad15 --- /dev/null +++ b/guide/src/reference/types/boxed-jsvalue-slice.md @@ -0,0 +1,17 @@ +# `Box<[JsValue]>` + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | +|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| 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}} +``` diff --git a/guide/src/reference/types/boxed-number-slices.md b/guide/src/reference/types/boxed-number-slices.md new file mode 100644 index 00000000..73cbf0d1 --- /dev/null +++ b/guide/src/reference/types/boxed-number-slices.md @@ -0,0 +1,21 @@ +# Boxed Number Slices: `Box<[u8]>`, `Box<[i8]>`, `Box<[u16]>`, `Box<[i16]>`, `Box<[u32]>`, `Box<[i32]>`, `Box<[u64]>`, `Box<[i64]>`, `Box<[f32]>`, and `Box<[f64]>` + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | +|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| Yes | No | No | Yes | Yes | Yes | A JavaScript `TypedArray` of the appropriate type (`Int32Array`, `Uint8Array`, etc...) | + +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}} +``` diff --git a/guide/src/reference/types/char.md b/guide/src/reference/types/char.md new file mode 100644 index 00000000..168f9319 --- /dev/null +++ b/guide/src/reference/types/char.md @@ -0,0 +1,17 @@ +# `char` + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` 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}} +``` diff --git a/guide/src/reference/types/exported-rust-types.md b/guide/src/reference/types/exported-rust-types.md new file mode 100644 index 00000000..c75a4a2d --- /dev/null +++ b/guide/src/reference/types/exported-rust-types.md @@ -0,0 +1,17 @@ +# Exported `struct Whatever` Rust Types + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | +|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| Yes | Yes | Yes | Yes | No | No | Instances of a `wasm-bindgen`-generated JavaScript `class Whatever { ... }` | + +## Example Rust Usage + +```rust +{{#include ../../../../examples/guide-supported-types-examples/src/exported_types.rs}} +``` + +## Example JavaScript Usage + +```js +{{#include ../../../../examples/guide-supported-types-examples/exported_types.js}} +``` diff --git a/guide/src/reference/types/imported-js-types.md b/guide/src/reference/types/imported-js-types.md new file mode 100644 index 00000000..8d64fa33 --- /dev/null +++ b/guide/src/reference/types/imported-js-types.md @@ -0,0 +1,17 @@ +# Imported `extern Whatever;` JavaScript Types + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | +|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| Yes | Yes | No | Yes | Yes | Yes | Instances of the extant `Whatever` JavaScript class / prototype constructor | + +## Example Rust Usage + +```rust +{{#include ../../../../examples/guide-supported-types-examples/src/imported_types.rs}} +``` + +## Example JavaScript Usage + +```js +{{#include ../../../../examples/guide-supported-types-examples/imported_types.js}} +``` diff --git a/guide/src/reference/types/jsvalue.md b/guide/src/reference/types/jsvalue.md new file mode 100644 index 00000000..dcb78723 --- /dev/null +++ b/guide/src/reference/types/jsvalue.md @@ -0,0 +1,17 @@ +# `JsValue` + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | +|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| 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}} +``` diff --git a/guide/src/reference/types/number-slices.md b/guide/src/reference/types/number-slices.md new file mode 100644 index 00000000..191430a9 --- /dev/null +++ b/guide/src/reference/types/number-slices.md @@ -0,0 +1,17 @@ +# Number Slices: `[u8]`, `[i8]`, `[u16]`, `[i16]`, `[u32]`, `[i32]`, `[u64]`, `[i64]`, `[f32]`, and `[f64]` + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<&T>` parameter | `Option` return value | JavaScript representation | +|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| No | Yes | Yes | No | No | No | A JavaScript `TypedArray` view of the Wasm memory for the boxed slice of the appropriate type (`Int32Array`, `Uint8Array`, etc) | + +## Example Rust Usage + +```rust +{{#include ../../../../examples/guide-supported-types-examples/src/number_slices.rs}} +``` + +## Example JavaScript Usage + +```js +{{#include ../../../../examples/guide-supported-types-examples/number_slices.js}} +``` diff --git a/guide/src/reference/types/numbers.md b/guide/src/reference/types/numbers.md new file mode 100644 index 00000000..13742f53 --- /dev/null +++ b/guide/src/reference/types/numbers.md @@ -0,0 +1,17 @@ +# Numbers: `u8`, `i8`, `u16`, `i16`, `u32`, `i32`, `u64`, `i64`, `isize`, `usize`, `f32`, and `f64` + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | +|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| Yes | No | No | Yes | Yes | Yes | A JavaScript number value | + +## Example Rust Usage + +```rust +{{#include ../../../../examples/guide-supported-types-examples/src/numbers.rs}} +``` + +## Example JavaScript Usage + +```js +{{#include ../../../../examples/guide-supported-types-examples/numbers.js}} +``` diff --git a/guide/src/reference/types/pointers.md b/guide/src/reference/types/pointers.md new file mode 100644 index 00000000..15ca4eb5 --- /dev/null +++ b/guide/src/reference/types/pointers.md @@ -0,0 +1,17 @@ +# `*const T` and `*mut T` + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | +|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| Yes | No | No | Yes | No | No | A JavaScript number value | + +## Example Rust Usage + +```rust +{{#include ../../../../examples/guide-supported-types-examples/src/pointers.rs}} +``` + +## Example JavaScript Usage + +```js +{{#include ../../../../examples/guide-supported-types-examples/pointers.js}} +``` diff --git a/guide/src/reference/types/str.md b/guide/src/reference/types/str.md new file mode 100644 index 00000000..999bbc18 --- /dev/null +++ b/guide/src/reference/types/str.md @@ -0,0 +1,22 @@ +# `str` + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | +|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| 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}} +``` diff --git a/guide/src/reference/types/string.md b/guide/src/reference/types/string.md new file mode 100644 index 00000000..568e20b6 --- /dev/null +++ b/guide/src/reference/types/string.md @@ -0,0 +1,21 @@ +# `String` + +| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` return value | JavaScript representation | +|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| Yes | No | No | Yes | Yes | Yes | 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` + +## 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}} +```