Slice/Array intrinsics: __slice and __elem_at

docs/book/src/reference/compiler_intrinsics.md

@@ -2,7 +2,7 @@
 
 The Sway compiler supports a list of intrinsics that perform various low level operations that are useful for building libraries. Compiler intrinsics should rarely be used but are preferred over `asm` blocks because they are type-checked and are safer overall. Below is a list of all available compiler intrinsics:
 
-___
+---
 
 ```sway
 __size_of_val<T>(val: T) -> u64
@@ -12,7 +12,7 @@ __size_of_val<T>(val: T) -> u64
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __size_of<T>() -> u64
@@ -22,7 +22,7 @@ __size_of<T>() -> u64
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __size_of_str_array<T>() -> u64
@@ -32,7 +32,7 @@ __size_of_str_array<T>() -> u64
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __assert_is_str_array<T>()
@@ -42,7 +42,7 @@ __assert_is_str_array<T>()
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __to_str_array(s: str) -> str[N]
@@ -52,7 +52,7 @@ __to_str_array(s: str) -> str[N]
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __is_reference_type<T>() -> bool
@@ -62,7 +62,7 @@ __is_reference_type<T>() -> bool
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __is_str_array<T>() -> bool
@@ -72,7 +72,7 @@ __is_str_array<T>() -> bool
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __eq<T>(lhs: T, rhs: T) -> bool
@@ -82,7 +82,7 @@ __eq<T>(lhs: T, rhs: T) -> bool
 
 **Constraints:** `T` is `bool`, `u8`, `u16`, `u32`, `u64`, `u256`, `b256` or `raw_ptr`.
 
-___
+---
 
 ```sway
 __gt<T>(lhs: T, rhs: T) -> bool
@@ -91,7 +91,8 @@ __gt<T>(lhs: T, rhs: T) -> bool
 **Description:** Returns whether `lhs` is greater than `rhs`.
 
 **Constraints:** `T` is `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
-___
+
+---
 
 ```sway
 __lt<T>(lhs: T, rhs: T) -> bool
@@ -100,7 +101,8 @@ __lt<T>(lhs: T, rhs: T) -> bool
 **Description:** Returns whether `lhs` is less than `rhs`.
 
 **Constraints:** `T` is `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
-___
+
+---
 
 ```sway
 __gtf<T>(index: u64, tx_field_id: u64) -> T
@@ -110,7 +112,7 @@ __gtf<T>(index: u64, tx_field_id: u64) -> T
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __addr_of<T>(val: T) -> raw_ptr
@@ -120,7 +122,7 @@ __addr_of<T>(val: T) -> raw_ptr
 
 **Constraints:** `T` is a reference type.
 
-___
+---
 
 ```sway
 __state_load_word(key: b256) -> u64
@@ -130,7 +132,7 @@ __state_load_word(key: b256) -> u64
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __state_load_quad(key: b256, ptr: raw_ptr, slots: u64) -> bool
@@ -140,7 +142,7 @@ __state_load_quad(key: b256, ptr: raw_ptr, slots: u64) -> bool
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __state_store_word(key: b256, val: u64) -> bool
@@ -150,7 +152,7 @@ __state_store_word(key: b256, val: u64) -> bool
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __state_store_quad(key: b256, ptr: raw_ptr, slots: u64) -> bool
@@ -160,7 +162,7 @@ __state_store_quad(key: b256, ptr: raw_ptr, slots: u64) -> bool
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __log<T>(val: T)
@@ -170,7 +172,7 @@ __log<T>(val: T)
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __add<T>(lhs: T, rhs: T) -> T
@@ -180,7 +182,7 @@ __add<T>(lhs: T, rhs: T) -> T
 
 **Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`.
 
-___
+---
 
 ```sway
 __sub<T>(lhs: T, rhs: T) -> T
@@ -190,7 +192,7 @@ __sub<T>(lhs: T, rhs: T) -> T
 
 **Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`.
 
-___
+---
 
 ```sway
 __mul<T>(lhs: T, rhs: T) -> T
@@ -200,7 +202,7 @@ __mul<T>(lhs: T, rhs: T) -> T
 
 **Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`.
 
-___
+---
 
 ```sway
 __div<T>(lhs: T, rhs: T) -> T
@@ -210,7 +212,7 @@ __div<T>(lhs: T, rhs: T) -> T
 
 **Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`.
 
-___
+---
 
 ```sway
 __and<T>(lhs: T, rhs: T) -> T
@@ -220,7 +222,7 @@ __and<T>(lhs: T, rhs: T) -> T
 
 **Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
 
-___
+---
 
 ```sway
 __or<T>(lhs: T, rhs: T) -> T
@@ -230,7 +232,7 @@ __or<T>(lhs: T, rhs: T) -> T
 
 **Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
 
-___
+---
 
 ```sway
 __xor<T>(lhs: T, rhs: T) -> T
@@ -239,7 +241,8 @@ __xor<T>(lhs: T, rhs: T) -> T
 **Description:** Bitwise XOR `lhs` and `rhs`.
 
 **Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
-___
+
+---
 
 ```sway
 __mod<T>(lhs: T, rhs: T) -> T
@@ -248,7 +251,8 @@ __mod<T>(lhs: T, rhs: T) -> T
 **Description:** Modulo of `lhs` by `rhs`.
 
 **Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`.
-___
+
+---
 
 ```sway
 __rsh<T>(lhs: T, rhs: u64) -> T
@@ -257,7 +261,8 @@ __rsh<T>(lhs: T, rhs: u64) -> T
 **Description:** Logical right shift of `lhs` by `rhs`.
 
 **Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
-___
+
+---
 
 ```sway
 __lsh<T>(lhs: T, rhs: u64) -> T
@@ -266,7 +271,8 @@ __lsh<T>(lhs: T, rhs: u64) -> T
 **Description:** Logical left shift of `lhs` by `rhs`.
 
 **Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
-___
+
+---
 
 ```sway
 __revert(code: u64)
@@ -276,7 +282,7 @@ __revert(code: u64)
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __ptr_add(ptr: raw_ptr, offset: u64)
@@ -286,7 +292,7 @@ __ptr_add(ptr: raw_ptr, offset: u64)
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __ptr_sub(ptr: raw_ptr, offset: u64)
@@ -296,7 +302,7 @@ __ptr_sub(ptr: raw_ptr, offset: u64)
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __smo<T>(recipient: b256, data: T, coins: u64)
@@ -306,7 +312,7 @@ __smo<T>(recipient: b256, data: T, coins: u64)
 
 **Constraints:** None.
 
-___
+---
 
 ```sway
 __not(op: T) -> T
@@ -316,7 +322,7 @@ __not(op: T) -> T
 
 **Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
 
-___
+---
 
 ```sway
 __jmp_mem()
@@ -325,3 +331,44 @@ __jmp_mem()
 **Description:** Jumps to `MEM[$hp]`.
 
 **Constraints:** None.
+
+---
+
+```sway
+__slice(item: &[T; N], start: u64, end: u64) -> &[T]
+__slice(item: &[T], start: u64, end: u64) -> &[T]
+__slice(item: &mut [T; N], start: u64, end: u64) -> &mut [T]
+__slice(item: &mut [T], start: u64, end: u64) -> &mut [T]
+```
+
+**Description:** Slices an array or another slice.
+
+This intrinsic returns a reference to a slice containing the range of elements inside `item`.
+The mutability of reference is defined by the first parameter mutability.
+
+Runtime bound checks are not generated, and must be done manually when and where appropriated. Compile time bound checks are done when possible.
+
+**Constraints:**
+
+- `item` is an array or a slice;
+- when `start` is a literal, it must be smaller than `item` length;
+- when `end` is a literal, it must be smaller than or equal to `item` length;
+- `end` must be greater than or equal to `start`
+
+---
+
+```sway
+__elem_at(item: &[T; N], index: u64) -> &T
+__elem_at(item: &[T], index: u64) -> &T
+__elem_at(item: &mut [T; N], index: u64) -> &mut T
+__elem_at(item: &mut [T], index: u64) -> &mut T
+```
+
+**Description:** Returns a reference to the indexed element. The mutability of reference is defined by the first parameter mutability.
+
+Runtime bound checks are not generated, and must be done manually when and where appropriated. Compile time bound checks are done when possible.
+
+**Constraints:**
+
+- `item` is a reference to an array or a reference to a slice;
+- when `index` is a literal, it must be smaller than `item` length;

docs/reference/src/code/language/built-ins/slices/.gitignore

@@ -0,0 +1,2 @@
+out
+target

docs/reference/src/code/language/built-ins/slices/Forc.lock

@@ -0,0 +1,14 @@
+[[package]]
+name = 'arrays'
+source = 'root'
+dependencies = ['std']
+
+[[package]]
+name = 'core'
+source = 'path+from-root-54F92B42A645EA2B'
+dependencies = []
+
+[[package]]
+name = 'std'
+source = 'git+https://github.com/fuellabs/sway?tag=v0.24.5#e695606d8884a18664f6231681333a784e623bc9'
+dependencies = ['core']

docs/reference/src/code/language/built-ins/slices/Forc.toml

@@ -0,0 +1,8 @@
+[project]
+authors = ["Fuel Labs <contact@fuel.sh>"]
+entry = "lib.sw"
+license = "Apache-2.0"
+name = "slices"
+
+[dependencies]
+std = { path = "../../../../../../../sway-lib-std" }

docs/reference/src/code/language/built-ins/slices/src/lib.sw

@@ -0,0 +1,7 @@
+library;
+
+// ANCHOR: syntax
+fn syntax(s: &[u64]) -> u64 {
+    s.len()
+}
+// ANCHOR_END: syntax

docs/reference/src/documentation/language/built-ins/index.md

@@ -22,8 +22,10 @@ Sway has the following primitive types:
    1. `str[n]` (fixed-length string of size n)
 4. [Bytes](b256.md)
    1. `b256` (256 bits / 32 bytes, i.e. a hash)
+5. [Slices](slices.md)
 
 <!-- TODO: The following sentence does not belong here. We need to convey the default size, including word size, somewhere however not on this page -->
+
 The default numeric type is `u64`. The FuelVM's word size is 64 bits, and the cases where using a smaller numeric type to save space are minimal.
 
 All other types in Sway are built up of these primitive types, or references to these primitive types.