guide: Split supported types section up into many sub sections

This commit is contained in:
Nick Fitzgerald 2018-08-14 18:01:17 -07:00
parent b1e3101fd4
commit a5a8fd747d
14 changed files with 229 additions and 229 deletions

View File

@ -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)

View File

@ -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<T>` parameter | `Option<T>` 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<T>` parameter | `Option<T>` 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<T>` parameter | `Option<T>` 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<T>` parameter | `Option<T>` 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<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 | 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<T>` parameter | `Option<T>` 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<T>` parameter | `Option<T>` 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<T>` parameter | `Option<T>` 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<T>` parameter | `Option<T>` 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<T>` parameter | `Option<T>` 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<T>` 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}}
```

View File

@ -0,0 +1,17 @@
# `bool`
| `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 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}}
```

View File

@ -0,0 +1,17 @@
# `Box<[JsValue]>`
| `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 `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}}
```

View File

@ -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<T>` parameter | `Option<T>` 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}}
```

View File

@ -0,0 +1,17 @@
# `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}}
```

View File

@ -0,0 +1,17 @@
# Exported `struct Whatever` Rust Types
| `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 | 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}}
```

View File

@ -0,0 +1,17 @@
# Imported `extern Whatever;` JavaScript Types
| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` 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}}
```

View File

@ -0,0 +1,17 @@
# `JsValue`
| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` 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}}
```

View File

@ -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<T>` 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}}
```

View File

@ -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<T>` parameter | `Option<T>` 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}}
```

View File

@ -0,0 +1,17 @@
# `*const T` and `*mut T`
| `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 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}}
```

View File

@ -0,0 +1,22 @@
# `str`
| `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` 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}}
```

View File

@ -0,0 +1,21 @@
# `String`
| `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 | 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}}
```