From 9f0f4979bb5b02c85bb874835f795df54427e069 Mon Sep 17 00:00:00 2001 From: Call Delegation <106365423+calldelegation@users.noreply.github.com> Date: Wed, 26 Jun 2024 18:50:22 -0400 Subject: [PATCH 01/10] first pass --- docs/book/src/introduction/core_library.md | 82 ++++++++++++++++++++++ docs/book/src/introduction/index.md | 1 + 2 files changed, 83 insertions(+) create mode 100644 docs/book/src/introduction/core_library.md diff --git a/docs/book/src/introduction/core_library.md b/docs/book/src/introduction/core_library.md new file mode 100644 index 00000000000..01382075ad6 --- /dev/null +++ b/docs/book/src/introduction/core_library.md @@ -0,0 +1,82 @@ +# Core Library + +The Sway Core Library, like the name suggests contains core operators and logic for the primitive types of the Sway programming language. These traits and methods are an extension of the [primitive types](https://docs.fuel.network/docs/sway/basics/built_in_types/#primitive-types) `u8`, `u16`, `u32`, `u64`, `u256`, `str[]`, `str`, `bool` and , `b256` and can be used where appropriate. +> Please note that Sway Core Library at the time of writing (v0.61.0) does not support operators for unsigned integers of size 128 (`u128`). Although the necessary OP codes exists for operators `u128` in the [FuelVM instruction set](https://docs.fuel.network/docs/specs/fuel-vm/instruction-set/) the team has limited bandwidth preparing for mainnet launch, so please consider [contributing](https://docs.fuel.network/docs/sway/reference/contributing_to_sway/) if this is of interest to you. + +The latest core library documentation can be found in the [Core Library Book](https://fuellabs.github.io/sway/master/core/). If the latest version is not compatible please refer to the appropriate tagged release. + +## Using the Core Library +Unlike their standard library counterparts, core library functionalities do not need to be explicitly imported and will work out of the box after creating any new Sway project with `forc new`. The `use` keyword is simply not required. + +Consider this example of using the modulo function for two like value types in a `struct`: +```sway +let struct1 = MyStruct { val: 10 }; +let struct2 = MyStruct { val: 2 }; +let result_struct = struct1 % struct2; +``` + +A bonus of developing with Sway is that developers do not have to worry about underflows and overflows, as these are handled by the FuelVM by design. + +## Core Library Prelude + +Sway core operations and logic are limited to their respective types. In other words, intuitively, the add `+` operation will be available for all unsigned integers in Sway but not for booleans. + +The prelude contains a list of operations essential to all Sway programs. The latest version of the prelude can be found [here](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/prelude.sw). + +> In addition to the notice above `Strings` are currently being reworked and do not have essential operations like concatenation etc. Workarounds will be required. + +### Primitives +`max()` The largest value that can be represented by this integer type i.e. `u256::max()` +`min()` The smallest value that can be represented by this integer type i.e. `u256::min()` +`bits()` The size of this integer type in bits i.e. `u256::bits()` +`zero()` the zero value for this integer type i.e. `u256::zero()` + +### Primitive Conversions +`as_u256` Converts any unsigned integer smaller than `u256` including `b256` to a `u256` i.e. `val.as_u256()` +`as_u64` Converts any unsigned integer smaller than `u64` to a `u64` i.e. `val.as_u64()` +`as_u32` Converts any unsigned integer smaller than `u32` to a `u32` i.e. `val.as_u32()` +`as_b256` Converts a `u256` to a `b256` i.e. `val.as_b256()` + +### Operations +`add` Add two values of the same type i.e. `let res = val1 + val2` +`subtract` Subtract two values of the same type i.e. `let res = val1 - val2` +`multiply` Multiply two values of the same type i.e. `let res = val1 * val2` +`divide` Divide two values of the same type i.e. `let res = val1 * val2` +`modulo` Modulo two values of the same type i.e. `let res = val1 % val2` +`not` Inverts the value of the type i.e. `let res = !val` +`equal` Evaluates if two values of the same type are equal i.e. `let res = val1 == val2` or `let res = val1 != val2` +`order` Evaluates if one value of the same type is greater than another i.e. `let res = val1 > val2` or `let res = val1 >= val2` +`shift` Bit shift left by an amount i.e. `let res = val1 >> 1` or `let res = val1 << 1` + +### String +`len` Return the length of the string slice in bytes i.e. `let res = val.len()` +`as_ptr` Return a `raw_ptr` to the beginning of the string slice on the heap i.e. `let res = val.as_ptr` +`from_str_array` Convert a string array to string i.e. `let res: str = from_str_array(val)` + +### Storage +`slot` The assigned location in storage i.e. `let res = val.slot()` +`offset` The assigned offset based on the data structure `T` i.e. `let res = val.offset()` +`field_id` A unique identifier i.e. `let res = val.field_id()` + +### Raw Slice +`slice` Converts self into a `raw_slice` i.e. `let slice = my_type.as_raw_slice()` + +### Codec +`abi_encode` Encodes a value based on the buffer i.e. `let res = val.abi_encode(buffer)` +`abi_decode` Decodes a type based on the buffer i.e. `let res = my_type::abi_decode(buffer)` + +For the full list of traits and methods available for each primitive type, please refer to the chart below or the [Core Library Book](https://fuellabs.github.io/sway/master/core/index.html). + +| Primitive Type | Description | +|--------------------|----------------------------------| +| [b256](https://fuellabs.github.io/sway/master/core/primitive.b256.html) | 256 bits (32 bytes), i.e. a hash | +| [bool](https://fuellabs.github.io/sway/master/core/primitive.bool.html) | Boolean true or false | +| [str](https://fuellabs.github.io/sway/master/core/primitive.str.html) | String Slice | +| [str[0-63]](https://fuellabs.github.io/sway/master/core/primitive.str[0].html) | Fixed-length string | +| [u265](https://fuellabs.github.io/sway/master/core/primitive.u256.html) | 256-bit unsigned integer | +| [u64](https://fuellabs.github.io/sway/master/core/primitive.u64.html) | 64-bit unsigned integer | +| [u32](https://fuellabs.github.io/sway/master/core/primitive.u32.html) | 32-bit unsigned integer | +| [u16](https://fuellabs.github.io/sway/master/core/primitive.u16.html) | 16-bit unsigned integer | +| [u8](https://fuellabs.github.io/sway/master/core/primitive.u8.html) | 8-bit unsigned integer | + + \ No newline at end of file diff --git a/docs/book/src/introduction/index.md b/docs/book/src/introduction/index.md index 8328fdaf1ba..33694f3f541 100644 --- a/docs/book/src/introduction/index.md +++ b/docs/book/src/introduction/index.md @@ -6,4 +6,5 @@ To get started with Forc and Sway smart contract development, install the Fuel t - [The Fuel Toolchain](./fuel_toolchain.md) - [A Forc Project](./forc_project.md) - [Standard Library](./standard_library.md) +- [Core Library](./core_library.md) - [Sway Language Standards](./sway_standards.md) From 14c0d885539a1dc15471537639726ea535a6f32a Mon Sep 17 00:00:00 2001 From: Call Delegation <106365423+calldelegation@users.noreply.github.com> Date: Wed, 26 Jun 2024 19:04:17 -0400 Subject: [PATCH 02/10] ci --- docs/book/spell-check-custom-words.txt | 7 ++++++- docs/book/src/SUMMARY.md | 1 + docs/book/src/introduction/core_library.md | 14 +++++++++++--- 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/book/spell-check-custom-words.txt b/docs/book/spell-check-custom-words.txt index 818c9a71b02..0d66d348464 100644 --- a/docs/book/spell-check-custom-words.txt +++ b/docs/book/spell-check-custom-words.txt @@ -210,4 +210,9 @@ namespacing unsafety prioritizations polymorphism -ContractId \ No newline at end of file +ContractId +booleans +underflows +Codec +bool +str \ No newline at end of file diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 78f0164d676..a1c7f9edd51 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -7,6 +7,7 @@ - [The Fuel Toolchain](./introduction/fuel_toolchain.md) - [A Forc Project](./introduction/forc_project.md) - [Standard Library](./introduction/standard_library.md) + - [Core Library](./introduction/core_library.md) - [Sway Language Standards](./introduction/sway_standards.md) - [Examples](./examples/index.md) - [Counter](./examples/counter.md) diff --git a/docs/book/src/introduction/core_library.md b/docs/book/src/introduction/core_library.md index 01382075ad6..9b5385baeed 100644 --- a/docs/book/src/introduction/core_library.md +++ b/docs/book/src/introduction/core_library.md @@ -1,14 +1,17 @@ # Core Library -The Sway Core Library, like the name suggests contains core operators and logic for the primitive types of the Sway programming language. These traits and methods are an extension of the [primitive types](https://docs.fuel.network/docs/sway/basics/built_in_types/#primitive-types) `u8`, `u16`, `u32`, `u64`, `u256`, `str[]`, `str`, `bool` and , `b256` and can be used where appropriate. +The Sway Core Library, like the name suggests contains core operators and logic for the primitive types of the Sway programming language. These traits and methods are an extension of the [primitive types](https://docs.fuel.network/docs/sway/basics/built_in_types/#primitive-types) `u8`, `u16`, `u32`, `u64`, `u256`, `str[]`, `str`, `bool` and , `b256` and can be used where appropriate. + > Please note that Sway Core Library at the time of writing (v0.61.0) does not support operators for unsigned integers of size 128 (`u128`). Although the necessary OP codes exists for operators `u128` in the [FuelVM instruction set](https://docs.fuel.network/docs/specs/fuel-vm/instruction-set/) the team has limited bandwidth preparing for mainnet launch, so please consider [contributing](https://docs.fuel.network/docs/sway/reference/contributing_to_sway/) if this is of interest to you. The latest core library documentation can be found in the [Core Library Book](https://fuellabs.github.io/sway/master/core/). If the latest version is not compatible please refer to the appropriate tagged release. ## Using the Core Library + Unlike their standard library counterparts, core library functionalities do not need to be explicitly imported and will work out of the box after creating any new Sway project with `forc new`. The `use` keyword is simply not required. Consider this example of using the modulo function for two like value types in a `struct`: + ```sway let struct1 = MyStruct { val: 10 }; let struct2 = MyStruct { val: 2 }; @@ -26,18 +29,21 @@ The prelude contains a list of operations essential to all Sway programs. The la > In addition to the notice above `Strings` are currently being reworked and do not have essential operations like concatenation etc. Workarounds will be required. ### Primitives + `max()` The largest value that can be represented by this integer type i.e. `u256::max()` `min()` The smallest value that can be represented by this integer type i.e. `u256::min()` `bits()` The size of this integer type in bits i.e. `u256::bits()` `zero()` the zero value for this integer type i.e. `u256::zero()` ### Primitive Conversions + `as_u256` Converts any unsigned integer smaller than `u256` including `b256` to a `u256` i.e. `val.as_u256()` `as_u64` Converts any unsigned integer smaller than `u64` to a `u64` i.e. `val.as_u64()` `as_u32` Converts any unsigned integer smaller than `u32` to a `u32` i.e. `val.as_u32()` `as_b256` Converts a `u256` to a `b256` i.e. `val.as_b256()` ### Operations + `add` Add two values of the same type i.e. `let res = val1 + val2` `subtract` Subtract two values of the same type i.e. `let res = val1 - val2` `multiply` Multiply two values of the same type i.e. `let res = val1 * val2` @@ -49,19 +55,23 @@ The prelude contains a list of operations essential to all Sway programs. The la `shift` Bit shift left by an amount i.e. `let res = val1 >> 1` or `let res = val1 << 1` ### String + `len` Return the length of the string slice in bytes i.e. `let res = val.len()` `as_ptr` Return a `raw_ptr` to the beginning of the string slice on the heap i.e. `let res = val.as_ptr` `from_str_array` Convert a string array to string i.e. `let res: str = from_str_array(val)` ### Storage + `slot` The assigned location in storage i.e. `let res = val.slot()` `offset` The assigned offset based on the data structure `T` i.e. `let res = val.offset()` `field_id` A unique identifier i.e. `let res = val.field_id()` ### Raw Slice + `slice` Converts self into a `raw_slice` i.e. `let slice = my_type.as_raw_slice()` ### Codec + `abi_encode` Encodes a value based on the buffer i.e. `let res = val.abi_encode(buffer)` `abi_decode` Decodes a type based on the buffer i.e. `let res = my_type::abi_decode(buffer)` @@ -78,5 +88,3 @@ For the full list of traits and methods available for each primitive type, pleas | [u32](https://fuellabs.github.io/sway/master/core/primitive.u32.html) | 32-bit unsigned integer | | [u16](https://fuellabs.github.io/sway/master/core/primitive.u16.html) | 16-bit unsigned integer | | [u8](https://fuellabs.github.io/sway/master/core/primitive.u8.html) | 8-bit unsigned integer | - - \ No newline at end of file From 622d994e8b672fec3d2aa062eb39f527133f325a Mon Sep 17 00:00:00 2001 From: Call Delegation <106365423+calldelegation@users.noreply.github.com> Date: Wed, 26 Jun 2024 19:07:04 -0400 Subject: [PATCH 03/10] Standard Library Book link is more clear --- docs/book/src/introduction/standard_library.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book/src/introduction/standard_library.md b/docs/book/src/introduction/standard_library.md index 01c98a0cc37..317c743bd1c 100644 --- a/docs/book/src/introduction/standard_library.md +++ b/docs/book/src/introduction/standard_library.md @@ -7,7 +7,7 @@ Similar to Rust, Sway comes with its own standard library. The Sway Standard Library is the foundation of portable Sway software, a set of minimal shared abstractions for the broader Sway ecosystem. It offers core types, like `Result` and `Option`, library-defined operations on language primitives, native asset management, blockchain contextual operations, access control, storage management, and support for types from other VMs, among many other things. -The entire Sway standard library is a Forc project called `std`, and is available directly [here](https://github.com/FuelLabs/sway/tree/master/sway-lib-std). Navigate to the appropriate tagged release if the latest `master` is not compatible. You can find the latest `std` documentation [here](https://fuellabs.github.io/sway/master/std/). +The entire Sway standard library is a Forc project called `std`, and is available directly [here](https://github.com/FuelLabs/sway/tree/master/sway-lib-std). Navigate to the appropriate tagged release if the latest `master` is not compatible. You can find the latest `std` documentation in the [Standard Library Book](https://fuellabs.github.io/sway/master/std/). ## Using the Standard Library From 31cf2bfe325cb0cb007d96fa15a7b094cb0e4656 Mon Sep 17 00:00:00 2001 From: Call Delegation <106365423+calldelegation@users.noreply.github.com> Date: Wed, 26 Jun 2024 19:16:21 -0400 Subject: [PATCH 04/10] review --- docs/book/src/introduction/core_library.md | 146 +++++++++++++++------ 1 file changed, 109 insertions(+), 37 deletions(-) diff --git a/docs/book/src/introduction/core_library.md b/docs/book/src/introduction/core_library.md index 9b5385baeed..b72170a332f 100644 --- a/docs/book/src/introduction/core_library.md +++ b/docs/book/src/introduction/core_library.md @@ -30,61 +30,133 @@ The prelude contains a list of operations essential to all Sway programs. The la ### Primitives -`max()` The largest value that can be represented by this integer type i.e. `u256::max()` -`min()` The smallest value that can be represented by this integer type i.e. `u256::min()` -`bits()` The size of this integer type in bits i.e. `u256::bits()` -`zero()` the zero value for this integer type i.e. `u256::zero()` +`max()` The largest value that can be represented by this integer type + +- `let val = u256::max()` + +`min()` The smallest value that can be represented by this integer type + +- `let res = u256::min()` + +`bits()` The size of this integer type in bits + +- `let res = u256::bits()` + +`zero()` the zero value for this integer type i + +- `let res = u256::zero()` ### Primitive Conversions -`as_u256` Converts any unsigned integer smaller than `u256` including `b256` to a `u256` i.e. `val.as_u256()` -`as_u64` Converts any unsigned integer smaller than `u64` to a `u64` i.e. `val.as_u64()` -`as_u32` Converts any unsigned integer smaller than `u32` to a `u32` i.e. `val.as_u32()` -`as_b256` Converts a `u256` to a `b256` i.e. `val.as_b256()` +`as_u256` Converts any unsigned integer smaller than `u256` including `b256` to a `u256` + +- `let res = val.as_u256()` + +`as_u64` Converts any unsigned integer smaller than `u64` to a `u64` + +- `let res = val.as_u64()` + +`as_u32` Converts any unsigned integer smaller than `u32` to a `u32` + +- `let res = val.as_u32()` + +`as_b256` Converts a `u256` to a `b256` + +- `let res = val.as_b256()` ### Operations -`add` Add two values of the same type i.e. `let res = val1 + val2` -`subtract` Subtract two values of the same type i.e. `let res = val1 - val2` -`multiply` Multiply two values of the same type i.e. `let res = val1 * val2` -`divide` Divide two values of the same type i.e. `let res = val1 * val2` -`modulo` Modulo two values of the same type i.e. `let res = val1 % val2` -`not` Inverts the value of the type i.e. `let res = !val` -`equal` Evaluates if two values of the same type are equal i.e. `let res = val1 == val2` or `let res = val1 != val2` -`order` Evaluates if one value of the same type is greater than another i.e. `let res = val1 > val2` or `let res = val1 >= val2` -`shift` Bit shift left by an amount i.e. `let res = val1 >> 1` or `let res = val1 << 1` +`add` Add two values of the same type + +- `let res = val1 + val2` + +`subtract` Subtract two values of the same type + +- `let res = val1 - val2` + +`multiply` Multiply two values of the same type + +- `let res = val1 * val2` + +`divide` Divide two values of the same type + +- `let res = val1 * val2` + +`modulo` Modulo two values of the same type + +- `let res = val1 % val2` + +`not` Inverts the value of the type + +- `let res = !val` + +`equal` Evaluates if two values of the same type are equal i.e. + +- `let res = val1 == val2` +- `let res = val1 != val2` + +`order` Evaluates if one value of the same type is greater than another + +- `let res = val1 > val2` +- `let res = val1 >= val2` + +`shift` Bit shift left by an amount + +- `let res = val1 >> 1` +- `let res = val1 << 1` ### String -`len` Return the length of the string slice in bytes i.e. `let res = val.len()` -`as_ptr` Return a `raw_ptr` to the beginning of the string slice on the heap i.e. `let res = val.as_ptr` -`from_str_array` Convert a string array to string i.e. `let res: str = from_str_array(val)` +`len` Return the length of the string slice in bytes + +- `let res = val.len()` + +`as_ptr` Return a `raw_ptr` to the beginning of the string slice on the heap + +- `let res = val.as_ptr` + +`from_str_array` Convert a string array to string + +- `let res: str = from_str_array(val)` ### Storage -`slot` The assigned location in storage i.e. `let res = val.slot()` -`offset` The assigned offset based on the data structure `T` i.e. `let res = val.offset()` -`field_id` A unique identifier i.e. `let res = val.field_id()` +`slot` The assigned location in storage + +- `let res = val.slot()` + +`offset` The assigned offset based on the data structure `T` + +- `let res = val.offset()` + `field_id` A unique identifier +- `let res = val.field_id()` ### Raw Slice -`slice` Converts self into a `raw_slice` i.e. `let slice = my_type.as_raw_slice()` +`slice` Converts self into a `raw_slice` + +- `let slice = my_type.as_raw_slice()` ### Codec -`abi_encode` Encodes a value based on the buffer i.e. `let res = val.abi_encode(buffer)` -`abi_decode` Decodes a type based on the buffer i.e. `let res = my_type::abi_decode(buffer)` +`abi_encode` Encodes a value based on the buffer + +- `let res = val.abi_encode(buffer)` + +`abi_decode` Decodes a type based on the buffer + +- `let res = my_type::abi_decode(buffer)` For the full list of traits and methods available for each primitive type, please refer to the chart below or the [Core Library Book](https://fuellabs.github.io/sway/master/core/index.html). -| Primitive Type | Description | -|--------------------|----------------------------------| -| [b256](https://fuellabs.github.io/sway/master/core/primitive.b256.html) | 256 bits (32 bytes), i.e. a hash | -| [bool](https://fuellabs.github.io/sway/master/core/primitive.bool.html) | Boolean true or false | -| [str](https://fuellabs.github.io/sway/master/core/primitive.str.html) | String Slice | -| [str[0-63]](https://fuellabs.github.io/sway/master/core/primitive.str[0].html) | Fixed-length string | -| [u265](https://fuellabs.github.io/sway/master/core/primitive.u256.html) | 256-bit unsigned integer | -| [u64](https://fuellabs.github.io/sway/master/core/primitive.u64.html) | 64-bit unsigned integer | -| [u32](https://fuellabs.github.io/sway/master/core/primitive.u32.html) | 32-bit unsigned integer | -| [u16](https://fuellabs.github.io/sway/master/core/primitive.u16.html) | 16-bit unsigned integer | -| [u8](https://fuellabs.github.io/sway/master/core/primitive.u8.html) | 8-bit unsigned integer | +| Primitive Type | Description | +| ------------------------------------------------------------------------------ | -------------------------------- | +| [b256](https://fuellabs.github.io/sway/master/core/primitive.b256.html) | 256 bits (32 bytes), i.e. a hash | +| [bool](https://fuellabs.github.io/sway/master/core/primitive.bool.html) | Boolean true or false | +| [str](https://fuellabs.github.io/sway/master/core/primitive.str.html) | String Slice | +| [str[0-63]](https://fuellabs.github.io/sway/master/core/primitive.str[0].html) | Fixed-length string | +| [u265](https://fuellabs.github.io/sway/master/core/primitive.u256.html) | 256-bit unsigned integer | +| [u64](https://fuellabs.github.io/sway/master/core/primitive.u64.html) | 64-bit unsigned integer | +| [u32](https://fuellabs.github.io/sway/master/core/primitive.u32.html) | 32-bit unsigned integer | +| [u16](https://fuellabs.github.io/sway/master/core/primitive.u16.html) | 16-bit unsigned integer | +| [u8](https://fuellabs.github.io/sway/master/core/primitive.u8.html) | 8-bit unsigned integer | From 306b0d0d0446163e9749abfff0b34b27926c1486 Mon Sep 17 00:00:00 2001 From: Call Delegation <106365423+calldelegation@users.noreply.github.com> Date: Wed, 3 Jul 2024 02:21:24 -0400 Subject: [PATCH 05/10] Update docs/book/src/introduction/standard_library.md Co-authored-by: IGI-111 --- docs/book/src/introduction/standard_library.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book/src/introduction/standard_library.md b/docs/book/src/introduction/standard_library.md index 317c743bd1c..01c98a0cc37 100644 --- a/docs/book/src/introduction/standard_library.md +++ b/docs/book/src/introduction/standard_library.md @@ -7,7 +7,7 @@ Similar to Rust, Sway comes with its own standard library. The Sway Standard Library is the foundation of portable Sway software, a set of minimal shared abstractions for the broader Sway ecosystem. It offers core types, like `Result` and `Option`, library-defined operations on language primitives, native asset management, blockchain contextual operations, access control, storage management, and support for types from other VMs, among many other things. -The entire Sway standard library is a Forc project called `std`, and is available directly [here](https://github.com/FuelLabs/sway/tree/master/sway-lib-std). Navigate to the appropriate tagged release if the latest `master` is not compatible. You can find the latest `std` documentation in the [Standard Library Book](https://fuellabs.github.io/sway/master/std/). +The entire Sway standard library is a Forc project called `std`, and is available directly [here](https://github.com/FuelLabs/sway/tree/master/sway-lib-std). Navigate to the appropriate tagged release if the latest `master` is not compatible. You can find the latest `std` documentation [here](https://fuellabs.github.io/sway/master/std/). ## Using the Standard Library From dfc9711e829348390f2ed7627cf83c4bc87753f2 Mon Sep 17 00:00:00 2001 From: Call Delegation <106365423+calldelegation@users.noreply.github.com> Date: Tue, 2 Jul 2024 23:21:44 -0700 Subject: [PATCH 06/10] changes --- docs/book/src/introduction/core_library.md | 138 ++---------------- .../book/src/introduction/standard_library.md | 2 +- 2 files changed, 15 insertions(+), 125 deletions(-) diff --git a/docs/book/src/introduction/core_library.md b/docs/book/src/introduction/core_library.md index b72170a332f..f1f39ea8d7b 100644 --- a/docs/book/src/introduction/core_library.md +++ b/docs/book/src/introduction/core_library.md @@ -8,17 +8,17 @@ The latest core library documentation can be found in the [Core Library Book](ht ## Using the Core Library -Unlike their standard library counterparts, core library functionalities do not need to be explicitly imported and will work out of the box after creating any new Sway project with `forc new`. The `use` keyword is simply not required. +Core library functionalities do not need to be explicitly imported and will work out of the box after creating any new Sway project with [`forc new`](../forc/commands/forc_new.md). The `use` keyword is simply not required. -Consider this example of using the modulo function for two like value types in a `struct`: +Consider this example of using the modulo function for two like value types: ```sway -let struct1 = MyStruct { val: 10 }; -let struct2 = MyStruct { val: 2 }; -let result_struct = struct1 % struct2; +let val_1 = 10; +let val_2 = 2; +let result = val_1 % val_2; ``` -A bonus of developing with Sway is that developers do not have to worry about underflows and overflows, as these are handled by the FuelVM by design. +Developers don't need to concern themselves with underflows and overflows because the Sway compiler automatically manages these issues during execution. ## Core Library Prelude @@ -28,124 +28,14 @@ The prelude contains a list of operations essential to all Sway programs. The la > In addition to the notice above `Strings` are currently being reworked and do not have essential operations like concatenation etc. Workarounds will be required. -### Primitives - -`max()` The largest value that can be represented by this integer type - -- `let val = u256::max()` - -`min()` The smallest value that can be represented by this integer type - -- `let res = u256::min()` - -`bits()` The size of this integer type in bits - -- `let res = u256::bits()` - -`zero()` the zero value for this integer type i - -- `let res = u256::zero()` - -### Primitive Conversions - -`as_u256` Converts any unsigned integer smaller than `u256` including `b256` to a `u256` - -- `let res = val.as_u256()` - -`as_u64` Converts any unsigned integer smaller than `u64` to a `u64` - -- `let res = val.as_u64()` - -`as_u32` Converts any unsigned integer smaller than `u32` to a `u32` - -- `let res = val.as_u32()` - -`as_b256` Converts a `u256` to a `b256` - -- `let res = val.as_b256()` - -### Operations - -`add` Add two values of the same type - -- `let res = val1 + val2` - -`subtract` Subtract two values of the same type - -- `let res = val1 - val2` - -`multiply` Multiply two values of the same type - -- `let res = val1 * val2` - -`divide` Divide two values of the same type - -- `let res = val1 * val2` - -`modulo` Modulo two values of the same type - -- `let res = val1 % val2` - -`not` Inverts the value of the type - -- `let res = !val` - -`equal` Evaluates if two values of the same type are equal i.e. - -- `let res = val1 == val2` -- `let res = val1 != val2` - -`order` Evaluates if one value of the same type is greater than another - -- `let res = val1 > val2` -- `let res = val1 >= val2` - -`shift` Bit shift left by an amount - -- `let res = val1 >> 1` -- `let res = val1 << 1` - -### String - -`len` Return the length of the string slice in bytes - -- `let res = val.len()` - -`as_ptr` Return a `raw_ptr` to the beginning of the string slice on the heap - -- `let res = val.as_ptr` - -`from_str_array` Convert a string array to string - -- `let res: str = from_str_array(val)` - -### Storage - -`slot` The assigned location in storage - -- `let res = val.slot()` - -`offset` The assigned offset based on the data structure `T` - -- `let res = val.offset()` - `field_id` A unique identifier -- `let res = val.field_id()` - -### Raw Slice - -`slice` Converts self into a `raw_slice` - -- `let slice = my_type.as_raw_slice()` - -### Codec - -`abi_encode` Encodes a value based on the buffer - -- `let res = val.abi_encode(buffer)` - -`abi_decode` Decodes a type based on the buffer - -- `let res = my_type::abi_decode(buffer)` +- [`core::primitives::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/primitives.sw) a module for getting `max`, `min`, `bits` and `zero`th for integers. +- [`core::primitive_conversions::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/primitive_conversions.sw) a module for converting between unsigned integers sizes. +- [`core::raw_ptr::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/raw_ptr.sw) a module for dealing with pointers. +- [`core::raw_slice::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/raw_slice.sw) a module for converting types to raw slice +- [`core::ops::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/ops.sw) a module for operations like `add` or `subtract` and comparisons `equal` and `order`. +- [`core::storage::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/storage.sw) a module dealing with storage. +- [`core::str::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/str.sw) a module dealing with `str` slices like `len` or converstions like `from_str_array`. +- [`core::codec::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/codec.sw) a module to encode and decode data structures. For the full list of traits and methods available for each primitive type, please refer to the chart below or the [Core Library Book](https://fuellabs.github.io/sway/master/core/index.html). diff --git a/docs/book/src/introduction/standard_library.md b/docs/book/src/introduction/standard_library.md index 317c743bd1c..811cb1b504f 100644 --- a/docs/book/src/introduction/standard_library.md +++ b/docs/book/src/introduction/standard_library.md @@ -7,7 +7,7 @@ Similar to Rust, Sway comes with its own standard library. The Sway Standard Library is the foundation of portable Sway software, a set of minimal shared abstractions for the broader Sway ecosystem. It offers core types, like `Result` and `Option`, library-defined operations on language primitives, native asset management, blockchain contextual operations, access control, storage management, and support for types from other VMs, among many other things. -The entire Sway standard library is a Forc project called `std`, and is available directly [here](https://github.com/FuelLabs/sway/tree/master/sway-lib-std). Navigate to the appropriate tagged release if the latest `master` is not compatible. You can find the latest `std` documentation in the [Standard Library Book](https://fuellabs.github.io/sway/master/std/). +The entire Sway standard library is a Forc project called `std`, and is available directly [here](https://github.com/FuelLabs/sway/tree/master/sway-lib-std). Navigate to the appropriate tagged release if the latest `master` is not compatible. You can find the latest `std` documentation in [here](https://fuellabs.github.io/sway/master/std/). ## Using the Standard Library From 1f38cb9e83e95be22ac228c0ee8a0954ef96e7be Mon Sep 17 00:00:00 2001 From: Call Delegation <106365423+calldelegation@users.noreply.github.com> Date: Tue, 2 Jul 2024 23:23:37 -0700 Subject: [PATCH 07/10] fix --- docs/book/src/introduction/core_library.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/book/src/introduction/core_library.md b/docs/book/src/introduction/core_library.md index f1f39ea8d7b..b8fad550bb4 100644 --- a/docs/book/src/introduction/core_library.md +++ b/docs/book/src/introduction/core_library.md @@ -2,8 +2,6 @@ The Sway Core Library, like the name suggests contains core operators and logic for the primitive types of the Sway programming language. These traits and methods are an extension of the [primitive types](https://docs.fuel.network/docs/sway/basics/built_in_types/#primitive-types) `u8`, `u16`, `u32`, `u64`, `u256`, `str[]`, `str`, `bool` and , `b256` and can be used where appropriate. -> Please note that Sway Core Library at the time of writing (v0.61.0) does not support operators for unsigned integers of size 128 (`u128`). Although the necessary OP codes exists for operators `u128` in the [FuelVM instruction set](https://docs.fuel.network/docs/specs/fuel-vm/instruction-set/) the team has limited bandwidth preparing for mainnet launch, so please consider [contributing](https://docs.fuel.network/docs/sway/reference/contributing_to_sway/) if this is of interest to you. - The latest core library documentation can be found in the [Core Library Book](https://fuellabs.github.io/sway/master/core/). If the latest version is not compatible please refer to the appropriate tagged release. ## Using the Core Library @@ -26,8 +24,6 @@ Sway core operations and logic are limited to their respective types. In other w The prelude contains a list of operations essential to all Sway programs. The latest version of the prelude can be found [here](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/prelude.sw). -> In addition to the notice above `Strings` are currently being reworked and do not have essential operations like concatenation etc. Workarounds will be required. - - [`core::primitives::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/primitives.sw) a module for getting `max`, `min`, `bits` and `zero`th for integers. - [`core::primitive_conversions::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/primitive_conversions.sw) a module for converting between unsigned integers sizes. - [`core::raw_ptr::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/raw_ptr.sw) a module for dealing with pointers. From 9eb7aacb361236ddc421ce8e0abe6226cb20d5d3 Mon Sep 17 00:00:00 2001 From: Call Delegation <106365423+calldelegation@users.noreply.github.com> Date: Tue, 2 Jul 2024 23:26:30 -0700 Subject: [PATCH 08/10] ci --- docs/book/src/introduction/core_library.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/book/src/introduction/core_library.md b/docs/book/src/introduction/core_library.md index b8fad550bb4..d90edd8f049 100644 --- a/docs/book/src/introduction/core_library.md +++ b/docs/book/src/introduction/core_library.md @@ -24,13 +24,13 @@ Sway core operations and logic are limited to their respective types. In other w The prelude contains a list of operations essential to all Sway programs. The latest version of the prelude can be found [here](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/prelude.sw). -- [`core::primitives::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/primitives.sw) a module for getting `max`, `min`, `bits` and `zero`th for integers. +- [`core::primitives::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/primitives.sw) a module for getting `max`, `min`, `bits` and `zero` for integers. - [`core::primitive_conversions::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/primitive_conversions.sw) a module for converting between unsigned integers sizes. - [`core::raw_ptr::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/raw_ptr.sw) a module for dealing with pointers. - [`core::raw_slice::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/raw_slice.sw) a module for converting types to raw slice - [`core::ops::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/ops.sw) a module for operations like `add` or `subtract` and comparisons `equal` and `order`. - [`core::storage::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/storage.sw) a module dealing with storage. -- [`core::str::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/str.sw) a module dealing with `str` slices like `len` or converstions like `from_str_array`. +- [`core::str::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/str.sw) a module dealing with `str` slices like `len` or conversions like `from_str_array`. - [`core::codec::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/codec.sw) a module to encode and decode data structures. For the full list of traits and methods available for each primitive type, please refer to the chart below or the [Core Library Book](https://fuellabs.github.io/sway/master/core/index.html). From 6d0931a7b7d9d87c1d69d4fd15a09fe3f292723c Mon Sep 17 00:00:00 2001 From: Call Delegation <106365423+calldelegation@users.noreply.github.com> Date: Fri, 12 Jul 2024 08:21:07 +0200 Subject: [PATCH 09/10] revisions --- docs/book/src/introduction/core_library.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/book/src/introduction/core_library.md b/docs/book/src/introduction/core_library.md index d90edd8f049..0970a50da68 100644 --- a/docs/book/src/introduction/core_library.md +++ b/docs/book/src/introduction/core_library.md @@ -2,7 +2,7 @@ The Sway Core Library, like the name suggests contains core operators and logic for the primitive types of the Sway programming language. These traits and methods are an extension of the [primitive types](https://docs.fuel.network/docs/sway/basics/built_in_types/#primitive-types) `u8`, `u16`, `u32`, `u64`, `u256`, `str[]`, `str`, `bool` and , `b256` and can be used where appropriate. -The latest core library documentation can be found in the [Core Library Book](https://fuellabs.github.io/sway/master/core/). If the latest version is not compatible please refer to the appropriate tagged release. +The latest core library documentation can be found [here](https://fuellabs.github.io/sway/master/core/). If the latest version is not compatible please refer to the appropriate tagged release. ## Using the Core Library @@ -16,12 +16,8 @@ let val_2 = 2; let result = val_1 % val_2; ``` -Developers don't need to concern themselves with underflows and overflows because the Sway compiler automatically manages these issues during execution. - ## Core Library Prelude -Sway core operations and logic are limited to their respective types. In other words, intuitively, the add `+` operation will be available for all unsigned integers in Sway but not for booleans. - The prelude contains a list of operations essential to all Sway programs. The latest version of the prelude can be found [here](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/prelude.sw). - [`core::primitives::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/primitives.sw) a module for getting `max`, `min`, `bits` and `zero` for integers. @@ -33,7 +29,7 @@ The prelude contains a list of operations essential to all Sway programs. The la - [`core::str::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/str.sw) a module dealing with `str` slices like `len` or conversions like `from_str_array`. - [`core::codec::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/codec.sw) a module to encode and decode data structures. -For the full list of traits and methods available for each primitive type, please refer to the chart below or the [Core Library Book](https://fuellabs.github.io/sway/master/core/index.html). +For the full list of traits and methods available for each primitive type, please refer to the chart below or the core library documentation [here](https://fuellabs.github.io/sway/master/core/index.html). | Primitive Type | Description | | ------------------------------------------------------------------------------ | -------------------------------- | From b48fb86a153910c31eb7e28bd252e581f2c7ce2d Mon Sep 17 00:00:00 2001 From: Call Delegation <106365423+calldelegation@users.noreply.github.com> Date: Sun, 14 Jul 2024 14:09:12 -0400 Subject: [PATCH 10/10] fix --- docs/book/src/introduction/core_library.md | 30 ++++++---------------- 1 file changed, 8 insertions(+), 22 deletions(-) diff --git a/docs/book/src/introduction/core_library.md b/docs/book/src/introduction/core_library.md index 0970a50da68..314db3e5c02 100644 --- a/docs/book/src/introduction/core_library.md +++ b/docs/book/src/introduction/core_library.md @@ -20,25 +20,11 @@ let result = val_1 % val_2; The prelude contains a list of operations essential to all Sway programs. The latest version of the prelude can be found [here](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/prelude.sw). -- [`core::primitives::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/primitives.sw) a module for getting `max`, `min`, `bits` and `zero` for integers. -- [`core::primitive_conversions::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/primitive_conversions.sw) a module for converting between unsigned integers sizes. -- [`core::raw_ptr::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/raw_ptr.sw) a module for dealing with pointers. -- [`core::raw_slice::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/raw_slice.sw) a module for converting types to raw slice -- [`core::ops::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/ops.sw) a module for operations like `add` or `subtract` and comparisons `equal` and `order`. -- [`core::storage::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/storage.sw) a module dealing with storage. -- [`core::str::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/str.sw) a module dealing with `str` slices like `len` or conversions like `from_str_array`. -- [`core::codec::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/codec.sw) a module to encode and decode data structures. - -For the full list of traits and methods available for each primitive type, please refer to the chart below or the core library documentation [here](https://fuellabs.github.io/sway/master/core/index.html). - -| Primitive Type | Description | -| ------------------------------------------------------------------------------ | -------------------------------- | -| [b256](https://fuellabs.github.io/sway/master/core/primitive.b256.html) | 256 bits (32 bytes), i.e. a hash | -| [bool](https://fuellabs.github.io/sway/master/core/primitive.bool.html) | Boolean true or false | -| [str](https://fuellabs.github.io/sway/master/core/primitive.str.html) | String Slice | -| [str[0-63]](https://fuellabs.github.io/sway/master/core/primitive.str[0].html) | Fixed-length string | -| [u265](https://fuellabs.github.io/sway/master/core/primitive.u256.html) | 256-bit unsigned integer | -| [u64](https://fuellabs.github.io/sway/master/core/primitive.u64.html) | 64-bit unsigned integer | -| [u32](https://fuellabs.github.io/sway/master/core/primitive.u32.html) | 32-bit unsigned integer | -| [u16](https://fuellabs.github.io/sway/master/core/primitive.u16.html) | 16-bit unsigned integer | -| [u8](https://fuellabs.github.io/sway/master/core/primitive.u8.html) | 8-bit unsigned integer | +- [`core::primitives::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/primitives.sw) +- [`core::primitive_conversions::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/primitive_conversions.sw) +- [`core::raw_ptr::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/raw_ptr.sw) +- [`core::raw_slice::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/raw_slice.sw) +- [`core::ops::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/ops.sw) +- [`core::storage::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/storage.sw) +- [`core::str::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/str.sw) +- [`core::codec::*`](https://github.com/FuelLabs/sway/blob/master/sway-lib-core/src/codec.sw)