fluencelabs/wasm-bindgen
1
0
Fork 0
mirror of https://github.com/fluencelabs/wasm-bindgen synced 2025-04-25 06:02:13 +00:00
Code Issues Projects Releases Wiki Activity

guide: Start adding example usage to "supported types" section

Browse Source
This commit is contained in:
Nick Fitzgerald 2018-08-10 16:56:40 -07:00
parent 2a3d01c380
commit e87498e939
16 changed files with 307 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Cargo.toml
View File

@ -55,6 +55,7 @@ members = [
"examples/comments", "examples/comments",
"examples/console_log", "examples/console_log",
"examples/dom", "examples/dom",
"examples/guide-supported-types-examples",
"examples/hello_world", "examples/hello_world",
"examples/import_js", "examples/import_js",
"examples/julia_set", "examples/julia_set",

3
examples/guide-supported-types-examples/.gitignore vendored Normal file
View File

@ -0,0 +1,3 @@
package-lock.json
guide_supported_types_examples.js
guide_supported_types_examples_bg.wasm

10
examples/guide-supported-types-examples/Cargo.toml Normal file
View File

@ -0,0 +1,10 @@
[package]
name = "guide-supported-types-examples"
version = "0.1.0"
authors = ["Nick Fitzgerald <fitzgen@gmail.com>"]
[lib]
crate-type = ["cdylib"]
[dependencies]
wasm-bindgen = { path = "../.." }

61
examples/guide-supported-types-examples/README.md Normal file
View File

@ -0,0 +1,61 @@
# Adding Numbers
[View this example online](https://webassembly.studio/?f=612vwsrmwft)
This directory is an example of using the `#[wasm_bindgen]` macro to simply add
two numbers. The neat part about this is that it's an example of how to generate
the smallest wasm-bindgen binary.
You can build the example with:
```
$ ./build.sh
```
(or running the commands on Windows manually)
Currently this generates a 651 byte wasm binary:
```
$ ls -alh add_bg.wasm
-rw-rw-r-- 1 alex alex 651 Apr 20 22:16 add_bg.wasm
```
If you run [wasm-opt], a C++ tool for optimize WebAssembly, you can make it even
smaller too!
```
$ wasm-opt -Os add_bg.wasm -o add.wasm
$ ls -alh add.wasm
-rw-rw-r-- 1 alex alex 100 Apr 20 22:19 add.wasm
```
And sure enough, using the [wasm2wat] tool it's quite small!
```
$ wasm2wat add.wasm
(module
(type (;0;) (func (param i32 i32) (result i32)))
(func (;0;) (type 0) (param i32 i32) (result i32)
get_local 1
get_local 0
i32.add)
(memory (;0;) 2)
(export "memory" (memory 0))
(export "add" (func 0))
(data (i32.const 1545) "invalid malloc request"))
```
Note that it's important to point out that the size reductions here are because
the wasm is compiled in release mode by the build script and this crate's
workspace has the following configuration
```toml
[profile.release]
lto = true
opt-level = 's'
panic = 'abort'
```
[wasm2wat]: https://github.com/webassembly/wabt
[wasm-opt]: https://github.com/webassembly/binaryen

2
examples/guide-supported-types-examples/bootstrap.js vendored Normal file
View File

@ -0,0 +1,2 @@
import * as imported_types from './imported_types.js';
import * as exported_types from './exported_types.js';

12
examples/guide-supported-types-examples/build.sh Executable file
View File

@ -0,0 +1,12 @@
#!/bin/sh
# For more coments about what's going on here, see the `hello_world` example
set -ex
cargo +nightly build --target wasm32-unknown-unknown --release
cargo +nightly run --manifest-path ../../crates/cli/Cargo.toml \
--bin wasm-bindgen -- \
../../target/wasm32-unknown-unknown/release/guide_supported_types_examples.wasm --out-dir .
npm install
npm run serve

1
examples/guide-supported-types-examples/exported_types.js Normal file
View File

@ -0,0 +1 @@
console.log("todo")

26
examples/guide-supported-types-examples/imported_types.js Normal file
View File

@ -0,0 +1,26 @@
import {
imported_type_by_value,
imported_type_by_shared_ref,
return_imported_type,
take_option_imported_type,
return_option_imported_type,
} from './guide_supported_types_examples';
imported_type_by_value(new SomeJsType());
imported_type_by_shared_ref(new SomeJsType());
let x = return_imported_type();
console.log(x instanceof SomeJsType);
// true
take_option_imported_type(null);
take_option_imported_type(undefined);
take_option_imported_type(new SomeJsType());
let y = return_option_imported_type();
if (y == null) {
// ...
} else {
console.log(y instanceof SomeJsType);
// true
}

8
examples/guide-supported-types-examples/index.html Normal file
View File

@ -0,0 +1,8 @@
<html>
<head>
<meta content="text/html;charset=utf-8" http-equiv="Content-Type"/>
</head>
<body>
<script src='./index.js'></script>
</body>
</html>

5
examples/guide-supported-types-examples/index.js Normal file
View File

@ -0,0 +1,5 @@
// For more comments about what's going on here, check out the `hello_world`
// example
import('./bootstrap').then(() => {
console.log("done");
});

10
examples/guide-supported-types-examples/package.json Normal file
View File

@ -0,0 +1,10 @@
{
"scripts": {
"serve": "webpack-dev-server"
},
"devDependencies": {
"webpack": "^4.11.1",
"webpack-cli": "^2.0.10",
"webpack-dev-server": "^3.1.0"
}
}

6
examples/guide-supported-types-examples/src/exported_types.rs Normal file
View File

@ -0,0 +1,6 @@
use wasm_bindgen::prelude::*;
#[wasm_bindgen]
pub struct RustType {
inner: u32,
}

25
examples/guide-supported-types-examples/src/imported_types.rs Normal file
View File

@ -0,0 +1,25 @@
use wasm_bindgen::prelude::*;
#[wasm_bindgen]
extern {
pub type SomeJsType;
}
#[wasm_bindgen]
pub fn imported_type_by_value(x: SomeJsType) { /* ... */ }
#[wasm_bindgen]
pub fn imported_type_by_shared_ref(x: &SomeJsType) { /* ... */ }
#[wasm_bindgen]
pub fn return_imported_type() -> SomeJsType {
unimplemented!()
}
#[wasm_bindgen]
pub fn take_option_imported_type(x: Option<SomeJsType>) { /* ... */ }
#[wasm_bindgen]
pub fn return_option_imported_type() -> Option<SomeJsType> {
unimplemented!()
}

7
examples/guide-supported-types-examples/src/lib.rs Executable file
View File

@ -0,0 +1,7 @@
#![feature(use_extern_macros)]
#![allow(unused_variables, dead_code)]
extern crate wasm_bindgen;
pub mod imported_types;
pub mod exported_types;

10
examples/guide-supported-types-examples/webpack.config.js Normal file
View File

@ -0,0 +1,10 @@
const path = require('path');
module.exports = {
entry: './index.js',
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'index.js',
},
mode: 'development'
};

139
guide/src/reference/types.md
View File

@ -1,21 +1,122 @@
# Supported Types # Supported Rust Types and their JavaScript Representations
The table below provides an overview of all the types that `wasm-bindgen` can This section provides an overview of all the types that `wasm-bindgen` can send
send and receive across the WebAssembly ABI boundary. and receive across the WebAssembly ABI boundary, and how they translate into
JavaScript.
| Type | `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` return value | ## Imported `extern Whatever;` JavaScript Types
|:---:|:---:|:---:|:---:|:---:|:---:|
| Imported `extern Whatever;` JavaScript Types | Yes | Yes | Yes | Yes | Yes | Yes | | `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option<T>` parameter | `Option<T>` return value | JavaScript representation |
| Exported `struct Whatever` Rust Types | Yes | Yes | Yes | Yes | Yes | Yes | |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| `str` | No | Yes | No | Yes | Yes | No | | Yes | Yes | No | Yes | Yes | Yes | Instances of the extant `Whatever` JavaScript class / prototype constructor |
| `String` | Yes | No | No | Yes | Yes | Yes |
| `char` | Yes | No | No | Yes | No | No | ### Example Rust Usage
| `bool` | Yes | No | No | Yes | No | No |
| `JsValue` | Yes | Yes | Yes | Yes | No | No | ```rust
| `Box<[JsValue]>` | Yes | No | No | Yes | Yes | yes | {{#include ../../../examples/guide-supported-types-examples/src/imported_types.rs}}
| `*const T` | Yes | No | No | Yes | No | No | ```
| `*mut T` | Yes | No | No | Yes | No | No |
| `u8` `i8` `u16` `i16` `u64` `i64` `isize` `size` | Yes | No | No | Yes | No | No | ### Example JavaScript Usage
| `u32` `i32` `f32` `f64` | Yes | Yes | Yes | Yes | No | No |
| `Box<[u8]>` `Box<[i8]>` `Box<[u16]>` `Box<[i16]>` `Box<[u32]>` `Box<[i32]>` `Box<[u64]>` `Box<[i64]>` `Box<[f32]>` `Box<[f64]`> | Yes | No | No | Yes | Yes | Yes | ```js
| `[u8]` `[i8]` `[u16]` `[i16]` `[u32]` `[i32]` `[u64]` `[i64]` `[f32]` `[f64]` | No | Yes | Yes | No | Yes | No | {{#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 | Yes | Yes | 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 | Yes | Yes | 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.
## `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`
## `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 |
## `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 |
## `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 |
## `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 |
## `*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 |
## `u8` `i8` `u16` `i16` `u64` `i64` `isize` `size`
| `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 |
## `u32` `i32` `f32` `f64`
| `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 | A JavaScript number value |
## `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` view of the Wasm memory for the boxed slice 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.
## `[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 | Yes | No | A JavaScript `TypedArray` view of the Wasm memory for the boxed slice 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.