diff --git a/examples/guide-supported-types-examples/bool.js b/examples/guide-supported-types-examples/bool.js new file mode 100644 index 00000000..3276d1a7 --- /dev/null +++ b/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" diff --git a/examples/guide-supported-types-examples/boxed_js_value_slice.js b/examples/guide-supported-types-examples/boxed_js_value_slice.js new file mode 100644 index 00000000..ade87968 --- /dev/null +++ b/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 +} diff --git a/examples/guide-supported-types-examples/char.js b/examples/guide-supported-types-examples/char.js new file mode 100644 index 00000000..f404197a --- /dev/null +++ b/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" diff --git a/examples/guide-supported-types-examples/exported_types.js b/examples/guide-supported-types-examples/exported_types.js index 97dd4313..7c60aea8 100644 --- a/examples/guide-supported-types-examples/exported_types.js +++ b/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); diff --git a/examples/guide-supported-types-examples/imported_types.js b/examples/guide-supported-types-examples/imported_types.js index 41d1c682..b3473f79 100644 --- a/examples/guide-supported-types-examples/imported_types.js +++ b/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); -// true +console.log(x instanceof SomeJsType); // 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); - // true + console.log(y instanceof SomeJsType); // true } diff --git a/examples/guide-supported-types-examples/js_value.js b/examples/guide-supported-types-examples/js_value.js new file mode 100644 index 00000000..f5bb9a51 --- /dev/null +++ b/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(); diff --git a/examples/guide-supported-types-examples/src/bool.rs b/examples/guide-supported-types-examples/src/bool.rs new file mode 100644 index 00000000..43edb430 --- /dev/null +++ b/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 +} diff --git a/examples/guide-supported-types-examples/src/boxed_js_value_slice.rs b/examples/guide-supported-types-examples/src/boxed_js_value_slice.rs new file mode 100644 index 00000000..152482fc --- /dev/null +++ b/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>) {} + +#[wasm_bindgen] +pub fn return_option_boxed_js_value_slice() -> Option> { + None +} diff --git a/examples/guide-supported-types-examples/src/char.rs b/examples/guide-supported-types-examples/src/char.rs new file mode 100644 index 00000000..a9176f98 --- /dev/null +++ b/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 { + '🚀' +} diff --git a/examples/guide-supported-types-examples/src/exported_types.rs b/examples/guide-supported-types-examples/src/exported_types.rs index 018374cb..963cb520 100644 --- a/examples/guide-supported-types-examples/src/exported_types.rs +++ b/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!() +} diff --git a/examples/guide-supported-types-examples/src/js_value.rs b/examples/guide-supported-types-examples/src/js_value.rs new file mode 100644 index 00000000..5d03d2f3 --- /dev/null +++ b/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 +} diff --git a/examples/guide-supported-types-examples/src/lib.rs b/examples/guide-supported-types-examples/src/lib.rs index afe92e4b..1fef349a 100755 --- a/examples/guide-supported-types-examples/src/lib.rs +++ b/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; diff --git a/examples/guide-supported-types-examples/src/str.rs b/examples/guide-supported-types-examples/src/str.rs new file mode 100644 index 00000000..a7878733 --- /dev/null +++ b/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) {} diff --git a/examples/guide-supported-types-examples/src/string.rs b/examples/guide-supported-types-examples/src/string.rs new file mode 100644 index 00000000..f9f3e5c9 --- /dev/null +++ b/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) {} + +#[wasm_bindgen] +pub fn return_option_string() -> Option { + None +} diff --git a/examples/guide-supported-types-examples/str.js b/examples/guide-supported-types-examples/str.js new file mode 100644 index 00000000..4909b6f6 --- /dev/null +++ b/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'); diff --git a/examples/guide-supported-types-examples/string.js b/examples/guide-supported-types-examples/string.js new file mode 100644 index 00000000..4c9defcd --- /dev/null +++ b/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" +} diff --git a/guide/src/reference/types.md b/guide/src/reference/types.md index a29d61fd..c8f82339 100644 --- a/guide/src/reference/types.md +++ b/guide/src/reference/types.md @@ -26,7 +26,7 @@ JavaScript. | `T` parameter | `&T` parameter | `&mut T` parameter | `T` return value | `Option` parameter | `Option` 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` parameter | `Option` 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` parameter | `Option` 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` 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 | 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` parameter | `Option` 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` parameter | `Option` return value | JavaScript representation |