Add missing docs to primitive_conversions library in standard library (…

…#5627) ## Description ## Checklist - [ ] I have linked to any relevant issues. - [x] I have commented my code, particularly in hard-to-understand areas. - [x] I have updated the documentation where relevant (API docs, the reference, and the Sway book). - [ ] I have added tests that prove my fix is effective or that my feature works. - [ ] I have added (or requested a maintainer to add) the necessary `Breaking*` or `New Feature` labels where relevant. - [x] I have done my best to ensure that my PR adheres to [the Fuel Labs Code Review Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md). - [x] I have requested a review from the relevant team or maintainers. --------- Co-authored-by: Sophie Dankel <[email protected]> Co-authored-by: IGI-111 <[email protected]> Co-authored-by: Cameron Carstens <[email protected]>
FuelLabs · Sep 5, 2024 · 8959f11 · 8959f11
1 parent de242ad
commit 8959f11
Show file tree

Hide file tree

Showing 4 changed files with 146 additions and 0 deletions.
diff --git a/sway-lib-std/src/primitive_conversions/str.sw b/sway-lib-std/src/primitive_conversions/str.sw
@@ -3,6 +3,20 @@ library;
 use ::option::Option::{self, *};
 
 impl str {
+    /// Attempts to convert the string slice into a string array.
+    ///
+    /// # Returns
+    ///
+    /// * [Option<S>] - `Some(str_array)` if the lengths of the `S` str_array type and the string slice's lengths match. Else `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// fn foo() {
+    ///     let string_slice = "abcd";
+    ///     let string_array: str[4] = a.try_as_str_array().unwrap();
+    /// }
+    /// ```
     pub fn try_as_str_array<S>(self) -> Option<S> {
         __assert_is_str_array::<S>();
         let str_size = __size_of_str_array::<S>();

diff --git a/sway-lib-std/src/primitive_conversions/u16.sw b/sway-lib-std/src/primitive_conversions/u16.sw
@@ -5,6 +5,28 @@ use ::option::Option::{self, *};
 use ::u128::U128;
 
 impl u16 {
+    /// Attempts to convert the u16 value into a u8 value.
+    ///
+    /// # Additional Information
+    ///
+    /// The max value a u8 can represent is 255.
+    ///
+    /// # Returns
+    ///
+    /// [Option<u8>] - `Some(u8)` if the u16 is less than or equal to the max u8 value. Else `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// fn foo() {
+    ///     let val = 255_u16.try_as_u8();
+    ///     assert(val == Some(255_u8));
+    ///
+    ///     // Conversion fails as value is above the max a u8 can represent.
+    ///     let val2 = 256_u16.try_as_u8();
+    ///     assert(val == None);
+    /// }
+    /// ```
     pub fn try_as_u8(self) -> Option<u8> {
         if self <= u8::max().as_u16() {
             Some(asm(input: self) {

diff --git a/sway-lib-std/src/primitive_conversions/u32.sw b/sway-lib-std/src/primitive_conversions/u32.sw
@@ -5,6 +5,28 @@ use ::option::Option::{self, *};
 use ::u128::U128;
 
 impl u32 {
+    /// Attempts to convert the u32 value into a u8 value.
+    ///
+    /// # Additional Information
+    ///
+    /// The max value a u8 can represent is 255.
+    ///
+    /// # Returns
+    ///
+    /// [Option<u8>] - `Some(u8)` if the u32 is less than or equal to the max u8 value. Else `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// fn foo() {
+    ///     let val = 255_u32.try_as_u8();
+    ///     assert(val == Some(255_u8));
+    ///
+    ///     // Conversion fails as value is above the max a u8 can represent.
+    ///     let val2 = 256_u32.try_as_u8();
+    ///     assert(val == None);
+    /// }
+    /// ```
     pub fn try_as_u8(self) -> Option<u8> {
         if self <= u8::max().as_u32() {
             Some(asm(input: self) {
@@ -15,6 +37,28 @@ impl u32 {
         }
     }
 
+    /// Attempts to convert the u32 value into a u16 value.
+    ///
+    /// # Additional Information
+    ///
+    /// The max value a u16 can represent is 65_535.
+    ///
+    /// # Returns
+    ///
+    /// [Option<u16>] - `Some(u16)` if the u32 is less than or equal to the max u16 value. Else `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// fn foo() {
+    ///     let val = 65_535_u32.try_as_u16();
+    ///     assert(val == Some(65_535_u16));
+    ///
+    ///     // Conversion fails as value is above the max a u16 can represent.
+    ///     let val2 = 65_536_u32.try_as_u16();
+    ///     assert(val == None);
+    /// }
+    /// ```
     pub fn try_as_u16(self) -> Option<u16> {
         if self <= u16::max().as_u32() {
             Some(asm(input: self) {

diff --git a/sway-lib-std/src/primitive_conversions/u64.sw b/sway-lib-std/src/primitive_conversions/u64.sw
@@ -5,6 +5,28 @@ use ::option::Option::{self, *};
 use ::u128::U128;
 
 impl u64 {
+    /// Attempts to convert the u64 value into a u8 value.
+    ///
+    /// # Additional Information
+    ///
+    /// The max value a u8 can represent is 255.
+    ///
+    /// # Returns
+    ///
+    /// [Option<u8>] - `Some(u8)` if the u64 is less than or equal to the max u8 value. Else `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// fn foo() {
+    ///     let val = 255_u64.try_as_u8();
+    ///     assert(val == Some(255_u8));
+    ///
+    ///     // Conversion fails as value is above the max a u8 can represent.
+    ///     let val2 = 256_u64.try_as_u8();
+    ///     assert(val == None);
+    /// }
+    /// ```
     pub fn try_as_u8(self) -> Option<u8> {
         if self <= u8::max().as_u64() {
             Some(asm(input: self) {
@@ -15,6 +37,28 @@ impl u64 {
         }
     }
 
+    /// Attempts to convert the u64 value into a u16 value.
+    ///
+    /// # Additional Information
+    ///
+    /// The max value a u16 can represent is 65_535.
+    ///
+    /// # Returns
+    ///
+    /// [Option<u16>] - `Some(u16)` if the u64 is less than or equal to the max u16 value. Else `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// fn foo() {
+    ///     let val = 65_535_u64.try_as_u16();
+    ///     assert(val == Some(65_535_u16));
+    ///
+    ///     // Conversion fails as value is above the max a u16 can represent.
+    ///     let val2 = 65_536_u64.try_as_u16();
+    ///     assert(val == None);
+    /// }
+    /// ```
     pub fn try_as_u16(self) -> Option<u16> {
         if self <= u16::max().as_u64() {
             Some(asm(input: self) {
@@ -25,6 +69,28 @@ impl u64 {
         }
     }
 
+    /// Attempts to convert the u64 value into a u32 value.
+    ///
+    /// # Additional Information
+    ///
+    /// The max value a u32 can represent is 4_294_967_295.
+    ///
+    /// # Returns
+    ///
+    /// [Option<u32>] - `Some(u32)` if the u64 is less than or equal to the max u32 value. Else `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// fn foo() {
+    ///     let val = 4_294_967_295_u64.try_as_u32();
+    ///     assert(val == Some(4_294_967_295_u32));
+    ///
+    ///     // Conversion fails as value is above the max a u32 can represent.
+    ///     let val2 = 4_294_967_296_u64.try_as_u32();
+    ///     assert(val == None);
+    /// }
+    /// ```
     pub fn try_as_u32(self) -> Option<u32> {
         if self <= u32::max().as_u64() {
             Some(asm(input: self) {