diff --git a/gitlab-pages/docs/reference/bytes.md b/gitlab-pages/docs/reference/bytes.md new file mode 100644 index 000000000..3a3349550 --- /dev/null +++ b/gitlab-pages/docs/reference/bytes.md @@ -0,0 +1,128 @@ +--- +id: bytes-reference +title: Bytes +--- + +## Bytes.concat(b1: bytes, b2: bytes) : bytes + +Concatenate together two `bytes` arguments and return the result. + + + + + +```pascaligo +function concat_op (const s : bytes) : bytes is + begin skip end with bytes_concat(s , 0x7070) +``` + + + +```cameligo +let concat_op (s : bytes) : bytes = + Bytes.concat s 0x7070 +``` + + + +```reasonligo +let concat_op = (s: bytes): bytes => Bytes.concat(s, 0x7070); +``` + + + +## Bytes.slice(pos1: nat, pos2: nat, data: bytes) : bytes + +Extract the bytes between `pos1` and `pos2`. **Positions are zero indexed and +inclusive**. For example if you gave the input "ff7a7aff" to the following: + + + + + +```pascaligo +function slice_op (const s : bytes) : bytes is + begin skip end with bytes_slice(1n , 2n , s) +``` + + + +```cameligo +let slice_op (s : bytes) : bytes = + Bytes.slice 1n 2n s +``` + + + +``` +let slice_op = (s: bytes): bytes => Bytes.slice(1n, 2n, s); +``` + + + +It would return "7a7a" rather than "ff7a" or "ff" or "7a". + +## Bytes.pack(data: a') : bytes + +Converts Michelson data structures to a binary format for serialization. + +> ⚠️ `PACK` and `UNPACK` are features of Michelson that are intended to be used by people that really know what they're doing. There are several failure cases (such as `UNPACK`ing a lambda from an untrusted source), most of which are beyond the scope of this document. Don't use these functions without doing your homework first. + + + + +```pascaligo +function id_string (const p : string) : option(string) is block { + const packed : bytes = bytes_pack(p) ; +} with (bytes_unpack(packed): option(string)) +``` + + +```cameligo +let id_string (p: string) : string option = + let packed: bytes = Bytes.pack p in + ((Bytes.unpack packed): string option) +``` + + +```reasonligo +let id_string = (p: string) : option(string) => { + let packed : bytes = Bytes.pack(p); + ((Bytes.unpack(packed)): option(string)); +}; +``` + + + +## Bytes.unpack(packed: bytes) : a' + +Reverses the result of using `unpack` on data, going from Michelson's binary +serialization format to the `option` type annotated on the call. + +> ⚠️ `PACK` and `UNPACK` are features of Michelson that are intended to be used by people that really know what they're doing. There are several failure cases (such as `UNPACK`ing a lambda from an untrusted source), most of which are beyond the scope of this document. Don't use these functions without doing your homework first. + + + + +```pascaligo +function id_string (const p : string) : option(string) is block { + const packed : bytes = bytes_pack(p) ; +} with (bytes_unpack(packed): option(string)) +``` + + +```cameligo +let id_string (p: string) : string option = + let packed: bytes = Bytes.pack p in + ((Bytes.unpack packed): string option) +``` + + +```reasonligo +let id_string = (p: string) : option(string) => { + let packed : bytes = Bytes.pack(p); + ((Bytes.unpack(packed)): option(string)); +}; +``` + + diff --git a/src/test/integration_tests.ml b/src/test/integration_tests.ml index 58b492fc2..720f03b0f 100644 --- a/src/test/integration_tests.ml +++ b/src/test/integration_tests.ml @@ -414,7 +414,7 @@ let bytes_arithmetic () : unit result = let%bind foototo = e_bytes_hex "0f007070" in let%bind toto = e_bytes_hex "7070" in let%bind empty = e_bytes_hex "" in - let%bind tata = e_bytes_hex "7a7a7a7a" in + let%bind tata = e_bytes_hex "ff7a7aff" in let%bind at = e_bytes_hex "7a7a" in let%bind ba = e_bytes_hex "ba" in let%bind () = expect_eq program "concat_op" foo foototo in @@ -476,7 +476,7 @@ let bytes_arithmetic_mligo () : unit result = let%bind foototo = e_bytes_hex "0f007070" in let%bind toto = e_bytes_hex "7070" in let%bind empty = e_bytes_hex "" in - let%bind tata = e_bytes_hex "7a7a7a7a" in + let%bind tata = e_bytes_hex "ff7a7aff" in let%bind at = e_bytes_hex "7a7a" in let%bind ba = e_bytes_hex "ba" in let%bind () = expect_eq program "concat_op" foo foototo in @@ -496,7 +496,7 @@ let bytes_arithmetic_religo () : unit result = let%bind foototo = e_bytes_hex "0f007070" in let%bind toto = e_bytes_hex "7070" in let%bind empty = e_bytes_hex "" in - let%bind tata = e_bytes_hex "7a7a7a7a" in + let%bind tata = e_bytes_hex "ff7a7aff" in let%bind at = e_bytes_hex "7a7a" in let%bind ba = e_bytes_hex "ba" in let%bind () = expect_eq program "concat_op" foo foototo in