Strings Library

README.md

@@ -32,6 +32,7 @@ These libraries contain helper functions, generalized standards, and other tools
 ### Libraries
 
 - [Binary Merkle Proof](./sway_libs/src/merkle_proof/) is used to verify Binary Merkle Trees computed off-chain.
+- [String](./sway_libs/src/string/) is an interface to implement dynamic length strings that are UTF-8 encoded.
 
 ## Using a library
 

sway_libs/src/lib.sw

@@ -1,3 +1,4 @@
 library sway_libs;
 
 dep merkle_proof/binary_merkle_proof;
+dep string/string;

sway_libs/src/string/README.md

@@ -0,0 +1,60 @@
+# Overview
+
+The String library provides an interface to use UTF-8 encoded strings of dynamic length in Sway. The `String` is heap allocated, growable, and not null terminated.
+
+The `String` is stored as vector of bytes. This differs from Sway's built in `str` because the size cannot be known at compile time and the length is dynamic. 
+
+For more information please see the [specification](./SPECIFICATION.md).
+
+> **Note** There is no way to convert a `str` to a `String`.
+
+## Known Issues
+
+It is important to note that unlike Rust's `String`, this `String` library does **not** guarantee a valid UTF-8 string. The `String` currently behaves only as a `vec` and does not perform any validation. This intended to be supported in the future with the introduction of [`char`](https://github.com/FuelLabs/sway/issues/2937) to the Sway language.
+
+# Using the Library
+
+## Getting Started
+
+In order to use the `String` library it must be added to the Forc.toml file and then imported into your Sway project. To add Sway-libs as a dependency to the Forc.toml in your project, please see the [README.md](../../../README.md).
+
+```rust
+use sway_libs::string::String;
+```
+
+Once imported, a `String` can be instantiated defining a new variable and calling the `new` function.
+
+```rust
+let mut string = ~String::new();
+```
+
+## Basic Functionality
+
+Appending or adding bytes to the `String` can be done by calling the `push` and `insert` functions.
+
+```rust
+// Append to the end
+string.push(0u8);
+
+// Insert at index 0
+string.insert(0u8, 0);
+```
+
+Removing bytes from the `String` can be done with either the `pop` or `remove` functions.
+
+```rust
+// Remove the last byte from the string, return the option that wraps the value and unwrap the byte
+let last_byte = string.pop().unwrap();
+
+// Remove and return the byte at index 0
+let nth_byte = string.remove(0);
+```
+
+To retrieve a byte in the `String`, use the `nth` function.
+
+```rust
+// Retrieve the byte at index 0
+let nth_byte = string.nth(0);
+```
+
+For more information please see the [specification](./SPECIFICATION.md).

sway_libs/src/string/SPECIFICATION.md

@@ -0,0 +1,63 @@
+# Overview
+
+This document provides an overview of the String library.
+
+It outlines the use cases, i.e. specification, and describes how to implement the library.
+
+## Use Cases
+
+The String library can be used anytime a string's length is unknown at compile time. Further methods can then be implemented to provide additional features building off of the `String` struct.
+
+> **Note** There is no guarantee in the validity of the UTF-8 encoded `String` and should be used with caution. For more information, please see the [known issues](./README.md#known-issues).
+
+## Public Functions
+
+### `as_bytes()`
+
+Convert the `String` struct to a `Vec` of `u8` bytes. 
+
+### `capacity()`
+
+Returns the total amount of memory on the heap allocated to the `String` which can be filled with bytes. 
+
+> **Note** Capacity and length are not the same. A `String` may have a length of 0 but any positive capacity.
+
+### `clear()`
+
+Truncates the `String` to a length of 0 and will appear empty. This does not clear the capacity of the `String`.
+
+### `from_utf8()`
+
+A new instance of a `String` will be created from a vector of `u8`'s
+
+### `insert()`
+
+Inserts a new byte at the specified index in the `String`. 
+
+### `is_empty()`
+
+Returns a boolean indicating whether the length of the `String` is zero.
+
+### `len()`
+
+Returns the total number of bytes in the `String`. 
+
+### `new()`
+
+Creates a new instance of the `String` struct.
+
+### `nth()`
+
+Returns the byte at the specified index in the `String`. If the index is out of bounds, `None` is returned.
+
+### `pop()`
+
+Removes the last byte in the `String` and returns it. If the `String` does not have any bytes, `None` is returned. 
+
+### `remove()`
+
+Remove and return the specified byte in the `String`. 
+
+### `with_capacity()`
+
+Creates a new instance of the `String` struct with a specified amount of memory allocated on the heap.

sway_libs/src/string/string.sw

@@ -0,0 +1,104 @@
+library string;
+
+use std::{option::Option, vec::Vec};
+
+pub struct String {
+    bytes: Vec<u8>,
+}
+
+impl String {
+    /// Returns the bytes stored for the `String`.
+    pub fn as_bytes(self) -> Vec<u8> {
+        self.bytes
+    }
+
+    /// Gets the amount of memory on the heap allocated to the `String`.
+    pub fn capacity(self) -> u64 {
+        self.bytes.capacity()
+    }
+
+    /// Truncates this `String` to a length of zero, removing all contents.
+    pub fn clear(self) {
+        self.bytes.clear()
+    }
+
+    /// Converts a vector of bytes to a `String`.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `bytes` - The vector of `u8` bytes which will be converted into a `String`.
+    pub fn from_utf8(bytes: Vec<u8>) -> String {
+        String { bytes }
+    }
+
+    /// Inserts a byte at the index within the `String`.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `byte` - The element which will be added to the `String`.
+    /// * `index` - The position in the `String` where the byte will be inserted.
+    pub fn insert(self, byte: u8, index: u64) {
+        self.bytes.insert(index, byte);
+    }
+
+    /// Returns `true` if the vector contains no bytes.
+    pub fn is_empty(self) -> bool {
+        self.bytes.is_empty()
+    }
+
+    /// Returns the number of bytes in the `String`, also referred to
+    /// as its 'length'.
+    pub fn len(self) -> u64 {
+        self.bytes.len()
+    }
+
+    /// Constructs a new instance of the `String` type.
+    pub fn new() -> Self {
+        Self {
+            bytes: ~Vec::new(),
+        }
+    }
+
+    /// Returns the byte at the specified index.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `index` - The position of the byte that will be returned.
+    pub fn nth(self, index: u64) -> Option<u8> {
+        self.bytes.get(index)
+    }
+
+    /// Removes the last byte from the `String` buffer and returns it.
+    pub fn pop(self) -> Option<u8> {
+        self.bytes.pop()
+    }
+
+    /// Appends a byte to the end of the `String`.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `byte` - The element to be appended to the end of the `String`.
+    pub fn push(self, byte: u8) {
+        self.bytes.push(byte);
+    }
+
+    /// Removes and returns the byte at the specified index.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `index` - The position of the byte that will be removed.
+    pub fn remove(self, index: u64) -> u8 {
+        self.bytes.remove(index)
+    }
+
+    /// Constructs a new instance of the `String` type with the specified capacity.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `capacity` - The specified amount of memory on the heap to be allocated for the `String`.
+    pub fn with_capacity(capacity: u64) -> Self {
+        Self {
+            bytes: ~Vec::with_capacity(capacity),
+        }
+    }
+}

tests/src/test_projects/harness.rs

@@ -1,3 +1,4 @@
 // Add test modules here:
 
 mod merkle_proof;
+mod string;

tests/src/test_projects/string/.gitignore

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

tests/src/test_projects/string/Forc.toml

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

tests/src/test_projects/string/mod.rs

@@ -0,0 +1 @@
+mod tests;