From 566e3ded2e7004fd778dad5749224fcdc13b5064 Mon Sep 17 00:00:00 2001 From: Franco Bregante Date: Thu, 8 Feb 2024 15:36:07 -0300 Subject: [PATCH] fix function formatting part 2 --- clarity/functions.md | 457 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 371 insertions(+), 86 deletions(-) diff --git a/clarity/functions.md b/clarity/functions.md index b818bdde9a..7ccd962035 100644 --- a/clarity/functions.md +++ b/clarity/functions.md @@ -400,7 +400,10 @@ Returns the result of bitwise inclusive or'ing a variable number of integer inpu **example:** ``` -(bit-or 4 8) ;; Returns 12(bit-or 1 2 4) ;; Returns 7(bit-or 64 -32 -16) ;; Returns -16(bit-or u2 u4 u32) ;; Returns u38 +(bit-or 4 8) ;; Returns 12 +(bit-or 1 2 4) ;; Returns 7 +(bit-or 64 -32 -16) ;; Returns -16 +(bit-or u2 u4 u32) ;; Returns u38 ``` ## bit-shift-left​ @@ -422,7 +425,14 @@ Note that there is a deliberate choice made to ignore arithmetic overflow for th **example:** ``` -(bit-shift-left 2 u1) ;; Returns 4(bit-shift-left 16 u2) ;; Returns 64(bit-shift-left -64 u1) ;; Returns -128(bit-shift-left u4 u2) ;; Returns u16(bit-shift-left 123 u9999999999) ;; Returns -170141183460469231731687303715884105728(bit-shift-left u123 u9999999999) ;; Returns u170141183460469231731687303715884105728(bit-shift-left -1 u7) ;; Returns -128(bit-shift-left -1 u128) ;; Returns -1 +(bit-shift-left 2 u1) ;; Returns 4 +(bit-shift-left 16 u2) ;; Returns 64 +(bit-shift-left -64 u1) ;; Returns -128 +(bit-shift-left u4 u2) ;; Returns u16 +(bit-shift-left 123 u9999999999) ;; Returns -170141183460469231731687303715884105728 +(bit-shift-left u123 u9999999999) ;; Returns u170141183460469231731687303715884105728 +(bit-shift-left -1 u7) ;; Returns -128 +(bit-shift-left -1 u128) ;; Returns -1 ``` ## bit-shift-right​ @@ -444,7 +454,16 @@ Note that there is a deliberate choice made to ignore arithmetic overflow for th **example:** ``` -(bit-shift-right 2 u1) ;; Returns 1(bit-shift-right 128 u2) ;; Returns 32(bit-shift-right -64 u1) ;; Returns -32(bit-shift-right u128 u2) ;; Returns u32(bit-shift-right 123 u9999999999) ;; Returns 0(bit-shift-right u123 u9999999999) ;; Returns u0(bit-shift-right -128 u7) ;; Returns -1(bit-shift-right -256 u1) ;; Returns -128(bit-shift-right 5 u2) ;; Returns 1(bit-shift-right -5 u2) ;; Returns -2 +(bit-shift-right 2 u1) ;; Returns 1 +(bit-shift-right 128 u2) ;; Returns 32 +(bit-shift-right -64 u1) ;; Returns -32 +(bit-shift-right u128 u2) ;; Returns u32 +(bit-shift-right 123 u9999999999) ;; Returns 0 +(bit-shift-right u123 u9999999999) ;; Returns u0 +(bit-shift-right -128 u7) ;; Returns -1 +(bit-shift-right -256 u1) ;; Returns -128 +(bit-shift-right 5 u2) ;; Returns 1 +(bit-shift-right -5 u2) ;; Returns -2 ``` ## bit-xor​ @@ -464,7 +483,11 @@ Returns the result of bitwise exclusive or'ing a variable number of integer inpu **example:** ``` -(bit-xor 1 2) ;; Returns 3(bit-xor 120 280) ;; Returns 352(bit-xor -128 64) ;; Returns -64(bit-xor u24 u4) ;; Returns u28(bit-xor 1 2 4 -1) ;; Returns -8 +(bit-xor 1 2) ;; Returns 3 +(bit-xor 120 280) ;; Returns 352 +(bit-xor -128 64) ;; Returns -64 +(bit-xor u24 u4) ;; Returns u28 +(bit-xor 1 2 4 -1) ;; Returns -8 ``` ## buff-to-int-be​ @@ -486,7 +509,10 @@ Note: This function is only available starting with Stacks 2.1. **example:** ``` -(buff-to-int-be 0x01) ;; Returns 1(buff-to-int-be 0x00000000000000000000000000000001) ;; Returns 1(buff-to-int-be 0xffffffffffffffffffffffffffffffff) ;; Returns -1(buff-to-int-be 0x) ;; Returns 0 +(buff-to-int-be 0x01) ;; Returns 1 +(buff-to-int-be 0x00000000000000000000000000000001) ;; Returns 1 +(buff-to-int-be 0xffffffffffffffffffffffffffffffff) ;; Returns -1 +(buff-to-int-be 0x) ;; Returns 0 ``` ## buff-to-int-le​ @@ -508,7 +534,10 @@ Note: This function is only available starting with Stacks 2.1. **example:** ``` -(buff-to-int-le 0x01) ;; Returns 1(buff-to-int-le 0x01000000000000000000000000000000) ;; Returns 1(buff-to-int-le 0xffffffffffffffffffffffffffffffff) ;; Returns -1(buff-to-int-le 0x) ;; Returns 0 +(buff-to-int-le 0x01) ;; Returns 1 +(buff-to-int-le 0x01000000000000000000000000000000) ;; Returns 1 +(buff-to-int-le 0xffffffffffffffffffffffffffffffff) ;; Returns -1 +(buff-to-int-le 0x) ;; Returns 0 ``` ## buff-to-uint-be​ @@ -530,7 +559,10 @@ Note: This function is only available starting with Stacks 2.1. **example:** ``` -(buff-to-uint-be 0x01) ;; Returns u1(buff-to-uint-be 0x00000000000000000000000000000001) ;; Returns u1(buff-to-uint-be 0xffffffffffffffffffffffffffffffff) ;; Returns u340282366920938463463374607431768211455(buff-to-uint-be 0x) ;; Returns u0 +(buff-to-uint-be 0x01) ;; Returns u1 +(buff-to-uint-be 0x00000000000000000000000000000001) ;; Returns u1 +(buff-to-uint-be 0xffffffffffffffffffffffffffffffff) ;; Returns u340282366920938463463374607431768211455 +(buff-to-uint-be 0x) ;; Returns u0 ``` ## buff-to-uint-le​ @@ -552,7 +584,10 @@ Note: This function is only available starting with Stacks 2.1. **example:** ``` -(buff-to-uint-le 0x01) ;; Returns u1(buff-to-uint-le 0x01000000000000000000000000000000) ;; Returns u1(buff-to-uint-le 0xffffffffffffffffffffffffffffffff) ;; Returns u340282366920938463463374607431768211455(buff-to-uint-le 0x) ;; Returns u0 +(buff-to-uint-le 0x01) ;; Returns u1 +(buff-to-uint-le 0x01000000000000000000000000000000) ;; Returns u1 +(buff-to-uint-le 0xffffffffffffffffffffffffffffffff) ;; Returns u340282366920938463463374607431768211455 +(buff-to-uint-le 0x) ;; Returns u0 ``` ## concat​ @@ -572,7 +607,9 @@ The `concat` function takes two sequences of the same type, and returns a concat **example:** ``` -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4)(concat "hello " "world") ;; Returns "hello world"(concat 0x0102 0x0304) ;; Returns 0x01020304 +(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) +(concat "hello " "world") ;; Returns "hello world" +(concat 0x0102 0x0304) ;; Returns 0x01020304 ``` ## contract-call?​ @@ -592,7 +629,8 @@ The `contract-call?` function executes the given public function of the given co **example:** ``` -;; instantiate the sample-contracts/tokens.clar contract first!(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) +;; instantiate the sample-contracts/tokens.clar contract first! +(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) ``` ## contract-of​ @@ -612,7 +650,10 @@ The `contract-of` function returns the principal of the contract implementing th **example:** ``` -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait)(define-public (forward-get-balance (user principal) (contract )) (begin (ok (contract-of contract)))) ;; returns the principal of the contract implementing +(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) +(define-public (forward-get-balance (user principal) (contract )) + (begin + (ok (contract-of contract)))) ;; returns the principal of the contract implementing ``` ## default-to​ @@ -632,7 +673,10 @@ The `default-to` function attempts to 'unpack' the second argument: if the argum **example:** ``` -(define-map names-map { name: (string-ascii 12) } { id: int })(map-set names-map { name: "blockstack" } { id: 1337 })(default-to 0 (get id (map-get? names-map (tuple (name "blockstack"))))) ;; Returns 1337(default-to 0 (get id (map-get? names-map (tuple (name "non-existant"))))) ;; Returns 0 +(define-map names-map { name: (string-ascii 12) } { id: int }) +(map-set names-map { name: "blockstack" } { id: 1337 }) +(default-to 0 (get id (map-get? names-map (tuple (name "blockstack"))))) ;; Returns 1337 +(default-to 0 (get id (map-get? names-map (tuple (name "non-existant"))))) ;; Returns 0 ``` ## define-constant​ @@ -654,7 +698,8 @@ Like other kinds of definition statements, `define-constant` may only be used at **example:** ``` -(define-constant four (+ 2 2))(+ 4 four) ;; Returns 8 +(define-constant four (+ 2 2)) +(+ 4 four) ;; Returns 8 ``` ## define-data-var​ @@ -678,7 +723,11 @@ Like other kinds of definition statements, `define-data-var` may only be used at **example:** ``` -(define-data-var size int 0)(define-private (set-size (value int)) (var-set size value))(set-size 1)(set-size 2) +(define-data-var size int 0) +(define-private (set-size (value int)) + (var-set size value)) +(set-size 1) +(set-size 2) ``` ## define-fungible-token​ @@ -704,7 +753,8 @@ Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft- **example:** ``` -(define-fungible-token stacks)(define-fungible-token limited-supply-stacks u100) +(define-fungible-token stacks) +(define-fungible-token limited-supply-stacks u100) ``` ## define-map​ @@ -728,7 +778,14 @@ Like other kinds of definition statements, `define-map` may only be used at the **example:** ``` -(define-map squares { x: int } { square: int })(define-private (add-entry (x int)) (map-insert squares { x: 2 } { square: (* x x) }))(add-entry 1)(add-entry 2)(add-entry 3)(add-entry 4)(add-entry 5) +(define-map squares { x: int } { square: int }) +(define-private (add-entry (x int)) + (map-insert squares { x: 2 } { square: (* x x) })) +(add-entry 1) +(add-entry 2) +(add-entry 3) +(add-entry 4) +(add-entry 5) ``` ## define-non-fungible-token​ @@ -776,7 +833,11 @@ Private functions may return any type. **example:** ``` -(define-private (max-of (i1 int) (i2 int)) (if (> i1 i2) i1 i2))(max-of 4 6) ;; Returns 6 +(define-private (max-of (i1 int) (i2 int)) + (if (> i1 i2) + i1 + i2)) +(max-of 4 6) ;; Returns 6 ``` ## define-public​ @@ -800,7 +861,10 @@ Public functions _must_ return a ResponseType (using either `ok` or `err`). Any **example:** ``` -(define-public (hello-world (input int)) (begin (print (+ 2 input)) (ok input))) +(define-public (hello-world (input int)) + (begin + (print (+ 2 input)) + (ok input))) ``` ## define-read-only​ @@ -824,7 +888,8 @@ Read-only functions may return any type. However, read-only functions may not pe **example:** ``` -(define-read-only (just-return-one-hundred) (* 10 10)) +(define-read-only (just-return-one-hundred) + (* 10 10)) ``` ## define-trait​ @@ -852,7 +917,9 @@ Like other kinds of definition statements, `define-trait` may only be used at th **example:** ``` -(define-trait token-trait ((transfer? (principal principal uint) (response uint uint)) (get-balance (principal) (response uint uint)))) +(define-trait token-trait + ((transfer? (principal principal uint) (response uint uint)) + (get-balance (principal) (response uint uint)))) ``` ## element-at​ @@ -872,7 +939,11 @@ The `element-at?` function returns the element at `index` in the provided sequen **example:** ``` -(element-at? "blockstack" u5) ;; Returns (some "s")(element-at? (list 1 2 3 4 5) u5) ;; Returns none(element-at? (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4)(element-at? "abcd" u1) ;; Returns (some "b")(element-at? 0xfb01 u1) ;; Returns (some 0x01) +(element-at? "blockstack" u5) ;; Returns (some "s") +(element-at? (list 1 2 3 4 5) u5) ;; Returns none +(element-at? (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) +(element-at? "abcd" u1) ;; Returns (some "b") +(element-at? 0xfb01 u1) ;; Returns (some 0x01) ``` ## element-at?​ @@ -892,7 +963,11 @@ The `element-at?` function returns the element at `index` in the provided sequen **example:** ``` -(element-at? "blockstack" u5) ;; Returns (some "s")(element-at? (list 1 2 3 4 5) u5) ;; Returns none(element-at? (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4)(element-at? "abcd" u1) ;; Returns (some "b")(element-at? 0xfb01 u1) ;; Returns (some 0x01) +(element-at? "blockstack" u5) ;; Returns (some "s") +(element-at? (list 1 2 3 4 5) u5) ;; Returns none +(element-at? (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) +(element-at? "abcd" u1) ;; Returns (some "b") +(element-at? 0xfb01 u1) ;; Returns (some 0x01) ``` ## err​ @@ -932,7 +1007,13 @@ The `filter` function applies the input function `func` to each element of the i **example:** ``` -(filter not (list true false true false)) ;; Returns (false false)(define-private (is-a (char (string-utf8 1))) (is-eq char u"a"))(filter is-a u"acabd") ;; Returns u"aa"(define-private (is-zero (char (buff 1))) (is-eq char 0x00))(filter is-zero 0x00010002) ;; Returns 0x0000 +(filter not (list true false true false)) ;; Returns (false false) +(define-private (is-a (char (string-utf8 1))) + (is-eq char u"a")) +(filter is-a u"acabd") ;; Returns u"aa" +(define-private (is-zero (char (buff 1))) + (is-eq char 0x00)) +(filter is-zero 0x00010002) ;; Returns 0x0000 ``` ## fold​ @@ -956,7 +1037,17 @@ Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf **example:** ``` -(fold * (list 2 2 2) 1) ;; Returns 8(fold * (list 2 2 2) 0) ;; Returns 0;; calculates (- 11 (- 7 (- 3 2)))(fold - (list 3 7 11) 2) ;; Returns 5 (define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20)))(fold concat-string "cdef" "ab") ;; Returns "fedcab"(fold concat-string (list "cd" "ef") "ab") ;; Returns "efcdab"(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20)))(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 +(fold * (list 2 2 2) 1) ;; Returns 8 +(fold * (list 2 2 2) 0) ;; Returns 0 +;; calculates (- 11 (- 7 (- 3 2))) +(fold - (list 3 7 11) 2) ;; Returns 5 +(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) + (unwrap-panic (as-max-len? (concat a b) u20))) +(fold concat-string "cdef" "ab") ;; Returns "fedcab" +(fold concat-string (list "cd" "ef") "ab") ;; Returns "efcdab" +(define-private (concat-buff (a (buff 20)) (b (buff 20))) + (unwrap-panic (as-max-len? (concat a b) u20))) +(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 ``` ## from-consensus-buff?​ @@ -976,7 +1067,14 @@ Introduced in: **Clarity 2** **example:** ``` -(from-consensus-buff? int 0x0000000000000000000000000000000001) ;; Returns (some 1)(from-consensus-buff? uint 0x0000000000000000000000000000000001) ;; Returns none(from-consensus-buff? uint 0x0100000000000000000000000000000001) ;; Returns (some u1)(from-consensus-buff? bool 0x0000000000000000000000000000000001) ;; Returns none(from-consensus-buff? bool 0x03) ;; Returns (some true)(from-consensus-buff? bool 0x04) ;; Returns (some false)(from-consensus-buff? principal 0x051fa46ff88886c2ef9762d970b4d2c63678835bd39d) ;; Returns (some SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)(from-consensus-buff? { abc: int, def: int } 0x0c00000002036162630000000000000000000000000000000003036465660000000000000000000000000000000004) ;; Returns (some (tuple (abc 3) (def 4))) +(from-consensus-buff? int 0x0000000000000000000000000000000001) ;; Returns (some 1) +(from-consensus-buff? uint 0x0000000000000000000000000000000001) ;; Returns none +(from-consensus-buff? uint 0x0100000000000000000000000000000001) ;; Returns (some u1) +(from-consensus-buff? bool 0x0000000000000000000000000000000001) ;; Returns none +(from-consensus-buff? bool 0x03) ;; Returns (some true) +(from-consensus-buff? bool 0x04) ;; Returns (some false) +(from-consensus-buff? principal 0x051fa46ff88886c2ef9762d970b4d2c63678835bd39d) ;; Returns (some SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) +(from-consensus-buff? { abc: int, def: int } 0x0c00000002036162630000000000000000000000000000000003036465660000000000000000000000000000000004) ;; Returns (some (tuple (abc 3) (def 4))) ``` ## ft-burn?​ @@ -1000,7 +1098,9 @@ On a successful burn, it returns `(ok true)`. In the event of an unsuccessful bu **example:** ``` -(define-fungible-token stackaroo)(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) +(define-fungible-token stackaroo) +(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) +(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) ``` ## ft-get-balance​ @@ -1020,7 +1120,9 @@ Introduced in: **Clarity 1** **example:** ``` -(define-fungible-token stackaroo)(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 +(define-fungible-token stackaroo) +(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) +(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 ``` ## ft-get-supply​ @@ -1040,7 +1142,9 @@ Introduced in: **Clarity 1** **example:** ``` -(define-fungible-token stackaroo)(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)(ft-get-supply stackaroo) ;; Returns u100 +(define-fungible-token stackaroo) +(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) +(ft-get-supply stackaroo) ;; Returns u100 ``` ## ft-mint?​ @@ -1062,7 +1166,8 @@ If a non-positive amount is provided to mint, this function returns `(err 1)`. O **example:** ``` -(define-fungible-token stackaroo)(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) +(define-fungible-token stackaroo) +(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) ``` ## ft-transfer?​ @@ -1086,7 +1191,10 @@ This function returns (ok true) if the transfer is successful. In the event of a **example:** ``` -(define-fungible-token stackaroo)(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) +(define-fungible-token stackaroo) +(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) +(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) +(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) ``` ## get​ @@ -1106,7 +1214,11 @@ The `get` function fetches the value associated with a given key from the suppli **example:** ``` -(define-map names-map { name: (string-ascii 12) } { id: int })(map-insert names-map { name: "blockstack" } { id: 1337 }) ;; Returns true(get id (tuple (name "blockstack") (id 1337))) ;; Returns 1337(get id (map-get? names-map (tuple (name "blockstack")))) ;; Returns (some 1337)(get id (map-get? names-map (tuple (name "non-existent")))) ;; Returns none +(define-map names-map { name: (string-ascii 12) } { id: int }) +(map-insert names-map { name: "blockstack" } { id: 1337 }) ;; Returns true +(get id (tuple (name "blockstack") (id 1337))) ;; Returns 1337 +(get id (map-get? names-map (tuple (name "blockstack")))) ;; Returns (some 1337) +(get id (map-get? names-map (tuple (name "non-existent")))) ;; Returns none ``` ## get-block-info?​ @@ -1144,7 +1256,9 @@ New in Stacks 2.1: **example:** ``` -(get-block-info? time u0) ;; Returns (some u1557860301)(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb)(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) +(get-block-info? time u0) ;; Returns (some u1557860301) +(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) +(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) ``` ## get-burn-block-info?​ @@ -1181,7 +1295,8 @@ The `addrs` list contains the same PoX address values passed into the PoX smart **example:** ``` -(get-burn-block-info? header-hash u677050) ;; Returns (some 0xe67141016c88a7f1203eca0b4312f2ed141531f59303a1c267d7d83ab6b977d8)(get-burn-block-info? pox-addrs u677050) ;; Returns (some (tuple (addrs ((tuple (hashbytes 0x395f3643cea07ec4eec73b4d9a973dcce56b9bf1) (version 0x00)) (tuple (hashbytes 0x7c6775e20e3e938d2d7e9d79ac310108ba501ddb) (version 0x01)))) (payout u123))) +(get-burn-block-info? header-hash u677050) ;; Returns (some 0xe67141016c88a7f1203eca0b4312f2ed141531f59303a1c267d7d83ab6b977d8) +(get-burn-block-info? pox-addrs u677050) ;; Returns (some (tuple (addrs ( (tuple (hashbytes 0x395f3643cea07ec4eec73b4d9a973dcce56b9bf1) (version 0x00)) (tuple (hashbytes 0x7c6775e20e3e938d2d7e9d79ac310108ba501ddb) (version 0x01)))) (payout u123))) ``` ## hash160​ @@ -1221,7 +1336,8 @@ The `if` function admits a boolean argument and two expressions which must retur **example:** ``` -(if true 1 2) ;; Returns 1(if (> 1 2) 1 2) ;; Returns 2 +(if true 1 2) ;; Returns 1 +(if (> 1 2) 1 2) ;; Returns 2 ``` ## impl-trait​ @@ -1245,7 +1361,11 @@ Like other kinds of definition statements, `impl-trait` may only be used at the **example:** ``` -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait)(define-public (get-balance (account principal)) (ok u0))(define-public (transfer? (from principal) (to principal) (amount uint)) (ok u0)) +(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) +(define-public (get-balance (account principal)) + (ok u0)) +(define-public (transfer? (from principal) (to principal) (amount uint)) + (ok u0)) ``` ## index-of​ @@ -1265,7 +1385,11 @@ The `index-of?` function returns the first index at which `item` can be found, u **example:** ``` -(index-of? "blockstack" "b") ;; Returns (some u0)(index-of? "blockstack" "k") ;; Returns (some u4)(index-of? "blockstack" "") ;; Returns none(index-of? (list 1 2 3 4 5) 6) ;; Returns none(index-of? 0xfb01 0x01) ;; Returns (some u1) +(index-of? "blockstack" "b") ;; Returns (some u0) +(index-of? "blockstack" "k") ;; Returns (some u4) +(index-of? "blockstack" "") ;; Returns none +(index-of? (list 1 2 3 4 5) 6) ;; Returns none +(index-of? 0xfb01 0x01) ;; Returns (some u1) ``` ## index-of?​ @@ -1285,7 +1409,11 @@ The `index-of?` function returns the first index at which `item` can be found, u **example:** ``` -(index-of? "blockstack" "b") ;; Returns (some u0)(index-of? "blockstack" "k") ;; Returns (some u4)(index-of? "blockstack" "") ;; Returns none(index-of? (list 1 2 3 4 5) 6) ;; Returns none(index-of? 0xfb01 0x01) ;; Returns (some u1) +(index-of? "blockstack" "b") ;; Returns (some u0) +(index-of? "blockstack" "k") ;; Returns (some u4) +(index-of? "blockstack" "") ;; Returns none +(index-of? (list 1 2 3 4 5) 6) ;; Returns none +(index-of? 0xfb01 0x01) ;; Returns (some u1) ``` ## int-to-ascii​ @@ -1307,7 +1435,9 @@ Note: This function is only available starting with Stacks 2.1. **example:** ``` -(int-to-ascii 1) ;; Returns "1"(int-to-ascii u1) ;; Returns "1"(int-to-ascii -1) ;; Returns "-1" +(int-to-ascii 1) ;; Returns "1" +(int-to-ascii u1) ;; Returns "1" +(int-to-ascii -1) ;; Returns "-1" ``` ## int-to-utf8​ @@ -1329,7 +1459,9 @@ Note: This function is only available starting with Stacks 2.1. **example:** ``` -(int-to-utf8 1) ;; Returns u"1"(int-to-utf8 u1) ;; Returns u"1"(int-to-utf8 -1) ;; Returns u"-1" +(int-to-utf8 1) ;; Returns u"1" +(int-to-utf8 u1) ;; Returns u"1" +(int-to-utf8 -1) ;; Returns u"-1" ``` ## is-eq​ @@ -1349,7 +1481,11 @@ Compares the inputted values, returning `true` if they are all equal. Note that **example:** ``` -(is-eq 1 1) ;; Returns true(is-eq true false) ;; Returns false(is-eq "abc" 234 234) ;; Throws type error(is-eq "abc" "abc") ;; Returns true(is-eq 0x0102 0x0102) ;; Returns true +(is-eq 1 1) ;; Returns true +(is-eq true false) ;; Returns false +(is-eq "abc" 234 234) ;; Throws type error +(is-eq "abc" "abc") ;; Returns true +(is-eq 0x0102 0x0102) ;; Returns true ``` ## is-err​ @@ -1369,7 +1505,8 @@ Introduced in: **Clarity 1** **example:** ``` -(is-err (ok 1)) ;; Returns false(is-err (err 1)) ;; Returns true +(is-err (ok 1)) ;; Returns false +(is-err (err 1)) ;; Returns true ``` ## is-none​ @@ -1389,7 +1526,10 @@ Introduced in: **Clarity 1** **example:** ``` -(define-map names-map { name: (string-ascii 12) } { id: int })(map-set names-map { name: "blockstack" } { id: 1337 })(is-none (get id (map-get? names-map { name: "blockstack" }))) ;; Returns false(is-none (get id (map-get? names-map { name: "non-existant" }))) ;; Returns true +(define-map names-map { name: (string-ascii 12) } { id: int }) +(map-set names-map { name: "blockstack" } { id: 1337 }) +(is-none (get id (map-get? names-map { name: "blockstack" }))) ;; Returns false +(is-none (get id (map-get? names-map { name: "non-existant" }))) ;; Returns true ``` ## is-ok​ @@ -1409,7 +1549,8 @@ Introduced in: **Clarity 1** **example:** ``` -(is-ok (ok 1)) ;; Returns true(is-ok (err 1)) ;; Returns false +(is-ok (ok 1)) ;; Returns true +(is-ok (err 1)) ;; Returns false ``` ## is-some​ @@ -1429,7 +1570,10 @@ Introduced in: **Clarity 1** **example:** ``` -(define-map names-map { name: (string-ascii 12) } { id: int })(map-set names-map { name: "blockstack" } { id: 1337 })(is-some (get id (map-get? names-map { name: "blockstack" }))) ;; Returns true(is-some (get id (map-get? names-map { name: "non-existant" }))) ;; Returns false +(define-map names-map { name: (string-ascii 12) } { id: int }) +(map-set names-map { name: "blockstack" } { id: 1337 }) +(is-some (get id (map-get? names-map { name: "blockstack" }))) ;; Returns true +(is-some (get id (map-get? names-map { name: "non-existant" }))) ;; Returns false ``` ## is-standard​ @@ -1451,7 +1595,11 @@ Note: This function is only available starting with Stacks 2.1. **example:** ``` -(is-standard 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6) ;; returns true on testnet and false on mainnet(is-standard 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.foo) ;; returns true on testnet and false on mainnet(is-standard 'SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY) ;; returns true on mainnet and false on testnet(is-standard 'SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY.foo) ;; returns true on mainnet and false on testnet(is-standard 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; returns false on both mainnet and testnet +(is-standard 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6) ;; returns true on testnet and false on mainnet +(is-standard 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.foo) ;; returns true on testnet and false on mainnet +(is-standard 'SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY) ;; returns true on mainnet and false on testnet +(is-standard 'SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY.foo) ;; returns true on mainnet and false on testnet +(is-standard 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; returns false on both mainnet and testnet ``` ## keccak256​ @@ -1491,7 +1639,9 @@ The `len` function returns the length of a given sequence. Applicable sequence t **example:** ``` -(len "blockstack") ;; Returns u10(len (list 1 2 3 4 5)) ;; Returns u5(len 0x010203) ;; Returns u3 +(len "blockstack") ;; Returns u10 +(len (list 1 2 3 4 5)) ;; Returns u5 +(len 0x010203) ;; Returns u3 ``` ## let​ @@ -1511,7 +1661,16 @@ The `let` function accepts a list of `variable name` and `expression` pairs, eva **example:** ``` -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 +(let + ( (a 2) (b (+ 5 6 7))) + (print a) + (print b) + (+ a b)) ;; Returns 20 +(let + ( (a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) + (print a) + (print b) + (+ a b)) ;; Returns 23 ``` ## list​ @@ -1551,7 +1710,10 @@ Returns the power to which the number 2 must be raised to to obtain the value `n **example:** ``` -(log2 u8) ;; Returns u3(log2 8) ;; Returns 3(log2 u1) ;; Returns u0(log2 1000) ;; Returns 9 +(log2 u8) ;; Returns u3 +(log2 8) ;; Returns 3 +(log2 u1) ;; Returns u0 +(log2 1000) ;; Returns 9 ``` ## map​ @@ -1571,7 +1733,14 @@ The `map` function applies the function `func` to each corresponding element of **example:** ``` -(map not (list true false true false)) ;; Returns (false true false true)(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9)(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u"a") u"a" u"b"))(map a-or-b u"aca") ;; Returns (u"a" u"b" u"a")(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01))(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) +(map not (list true false true false)) ;; Returns (false true false true) +(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) +(define-private (a-or-b (char (string-utf8 1))) + (if (is-eq char u"a") u"a" u"b")) +(map a-or-b u"aca") ;; Returns (u"a" u"b" u"a") +(define-private (zero-or-one (char (buff 1))) + (if (is-eq char 0x00) 0x00 0x01)) +(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) ``` ## map-delete​ @@ -1591,7 +1760,11 @@ The `map-delete` function removes the value associated with the input key for th **example:** ``` -(define-map names-map { name: (string-ascii 10) } { id: int })(map-insert names-map { name: "blockstack" } { id: 1337 }) ;; Returns true(map-delete names-map { name: "blockstack" }) ;; Returns true(map-delete names-map { name: "blockstack" }) ;; Returns false(map-delete names-map (tuple (name "blockstack"))) ;; Same command, using a shorthand for constructing the tuple +(define-map names-map { name: (string-ascii 10) } { id: int }) +(map-insert names-map { name: "blockstack" } { id: 1337 }) ;; Returns true +(map-delete names-map { name: "blockstack" }) ;; Returns true +(map-delete names-map { name: "blockstack" }) ;; Returns false +(map-delete names-map (tuple (name "blockstack"))) ;; Same command, using a shorthand for constructing the tuple ``` ## map-get?​ @@ -1611,7 +1784,10 @@ The `map-get?` function looks up and returns an entry from a contract's data map **example:** ``` -(define-map names-map { name: (string-ascii 10) } { id: int })(map-set names-map { name: "blockstack" } { id: 1337 })(map-get? names-map (tuple (name "blockstack"))) ;; Returns (some (tuple (id 1337)))(map-get? names-map { name: "blockstack" }) ;; Same command, using a shorthand for constructing the tuple +(define-map names-map { name: (string-ascii 10) } { id: int }) +(map-set names-map { name: "blockstack" } { id: 1337 }) +(map-get? names-map (tuple (name "blockstack"))) ;; Returns (some (tuple (id 1337))) +(map-get? names-map { name: "blockstack" }) ;; Same command, using a shorthand for constructing the tuple ``` ## map-insert​ @@ -1633,7 +1809,10 @@ Note: the `value-tuple` requires 1 additional byte for storage in the materializ **example:** ``` -(define-map names-map { name: (string-ascii 10) } { id: int })(map-insert names-map { name: "blockstack" } { id: 1337 }) ;; Returns true(map-insert names-map { name: "blockstack" } { id: 1337 }) ;; Returns false(map-insert names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple +(define-map names-map { name: (string-ascii 10) } { id: int }) +(map-insert names-map { name: "blockstack" } { id: 1337 }) ;; Returns true +(map-insert names-map { name: "blockstack" } { id: 1337 }) ;; Returns false +(map-insert names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple ``` ## map-set​ @@ -1655,7 +1834,9 @@ Note: the `value-tuple` requires 1 additional byte for storage in the materializ **example:** ``` -(define-map names-map { name: (string-ascii 10) } { id: int })(map-set names-map { name: "blockstack" } { id: 1337 }) ;; Returns true(map-set names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple +(define-map names-map { name: (string-ascii 10) } { id: int }) +(map-set names-map { name: "blockstack" } { id: 1337 }) ;; Returns true +(map-set names-map (tuple (name "blockstack")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple ``` ## match​ @@ -1691,7 +1872,18 @@ Note: Type checking requires that the type of both the ok and err parts of the r **example:** ``` -(define-private (add-10 (x (optional int))) (match x value (+ 10 value) 10))(add-10 (some 5)) ;; Returns 15(add-10 none) ;; Returns 10(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) (match x value (ok (+ to-add value)) err-value (err err-value)))(add-or-pass-err (ok 5) 20) ;; Returns (ok 25)(add-or-pass-err (err "ERROR") 20) ;; Returns (err "ERROR") +(define-private (add-10 (x (optional int))) + (match x + value (+ 10 value) + 10)) +(add-10 (some 5)) ;; Returns 15 +(add-10 none) ;; Returns 10 +(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) + (match x + value (ok (+ to-add value)) + err-value (err err-value))) +(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) +(add-or-pass-err (err "ERROR") 20) ;; Returns (err "ERROR") ``` ## merge​ @@ -1711,7 +1903,11 @@ The `merge` function returns a new tuple with the combined fields, without mutat **example:** ``` -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) })(map-insert users { id: 1337 } { name: "john", address: none }) ;; Returns true(let ((user (unwrap-panic (map-get? users { id: 1337 })))) (merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name "john")) +(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) +(map-insert users { id: 1337 } { name: "john", address: none }) ;; Returns true +(let + ( (user (unwrap-panic (map-get? users { id: 1337 })))) + (merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name "john")) ``` ## mod​ @@ -1731,7 +1927,9 @@ Returns the integer remainder from integer dividing `i1` by `i2`. In the event o **example:** ``` -(mod 2 3) ;; Returns 2(mod 5 2) ;; Returns 1(mod 7 1) ;; Returns 0 +(mod 2 3) ;; Returns 2 +(mod 5 2) ;; Returns 1 +(mod 7 1) ;; Returns 0 ``` ## nft-burn?​ @@ -1755,7 +1953,9 @@ On a successful burn, it returns `(ok true)`. In the event of an unsuccessful bu **example:** ``` -(define-non-fungible-token stackaroo (string-ascii 40))(nft-mint? stackaroo "Roo" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)(nft-burn? stackaroo "Roo" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) +(define-non-fungible-token stackaroo (string-ascii 40)) +(nft-mint? stackaroo "Roo" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) +(nft-burn? stackaroo "Roo" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) ``` ## nft-get-owner?​ @@ -1775,7 +1975,10 @@ Introduced in: **Clarity 1** **example:** ``` -(define-non-fungible-token stackaroo (string-ascii 40))(nft-mint? stackaroo "Roo" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)(nft-get-owner? stackaroo "Roo") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)(nft-get-owner? stackaroo "Too") ;; Returns none +(define-non-fungible-token stackaroo (string-ascii 40)) +(nft-mint? stackaroo "Roo" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) +(nft-get-owner? stackaroo "Roo") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) +(nft-get-owner? stackaroo "Too") ;; Returns none ``` ## nft-mint?​ @@ -1801,7 +2004,8 @@ Otherwise, on successfuly mint, it returns `(ok true)`. **example:** ``` -(define-non-fungible-token stackaroo (string-ascii 40))(nft-mint? stackaroo "Roo" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) +(define-non-fungible-token stackaroo (string-ascii 40)) +(nft-mint? stackaroo "Roo" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) ``` ## nft-transfer?​ @@ -1825,7 +2029,11 @@ This function returns (ok true) if the transfer is successful. In the event of a **example:** ``` -(define-non-fungible-token stackaroo (string-ascii 40))(nft-mint? stackaroo "Roo" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)(nft-transfer? stackaroo "Roo" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)(nft-transfer? stackaroo "Roo" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1)(nft-transfer? stackaroo "Stacka" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) +(define-non-fungible-token stackaroo (string-ascii 40)) +(nft-mint? stackaroo "Roo" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) +(nft-transfer? stackaroo "Roo" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) +(nft-transfer? stackaroo "Roo" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) +(nft-transfer? stackaroo "Stacka" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) ``` ## not​ @@ -1845,7 +2053,8 @@ Returns the inverse of the boolean input. **example:** ``` -(not true) ;; Returns false(not (is-eq 1 2)) ;; Returns true +(not true) ;; Returns false +(not (is-eq 1 2)) ;; Returns true ``` ## ok​ @@ -1885,7 +2094,10 @@ Returns `true` if any boolean inputs are `true`. Importantly, the supplied argum **example:** ``` -(or true false) ;; Returns true(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true +(or true false) ;; Returns true +(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true +(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false +(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true ``` ## pow​ @@ -1911,7 +2123,9 @@ Returns the result of raising `i1` to the power of `i2`. In the event of an _ove **example:** ``` -(pow 2 3) ;; Returns 8(pow 2 2) ;; Returns 4(pow 7 1) ;; Returns 7 +(pow 2 3) ;; Returns 8 +(pow 2 2) ;; Returns 4 +(pow 7 1) ;; Returns 7 ``` ## principal-construct?​ @@ -1943,7 +2157,15 @@ Note: This function is only available starting with Stacks 2.1. **example:** ``` -(principal-construct? 0x1a 0xfa6bf38ed557fe417333710d6033e9419391a320) ;; Returns (ok ST3X6QWWETNBZWGBK6DRGTR1KX50S74D3425Q1TPK)(principal-construct? 0x1a 0xfa6bf38ed557fe417333710d6033e9419391a320 "foo") ;; Returns (ok ST3X6QWWETNBZWGBK6DRGTR1KX50S74D3425Q1TPK.foo)(principal-construct? 0x16 0xfa6bf38ed557fe417333710d6033e9419391a320) ;; Returns (err (tuple (error_code u0) (value (some SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY))))(principal-construct? 0x16 0xfa6bf38ed557fe417333710d6033e9419391a320 "foo") ;; Returns (err (tuple (error_code u0) (value (some SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY.foo))))(principal-construct? 0x 0xfa6bf38ed557fe417333710d6033e9419391a320) ;; Returns (err (tuple (error_code u1) (value none)))(principal-construct? 0x16 0xfa6bf38ed557fe417333710d6033e9419391a3) ;; Returns (err (tuple (error_code u1) (value none)))(principal-construct? 0x20 0xfa6bf38ed557fe417333710d6033e9419391a320) ;; Returns (err (tuple (error_code u1) (value none)))(principal-construct? 0x1a 0xfa6bf38ed557fe417333710d6033e9419391a320 "") ;; Returns (err (tuple (error_code u2) (value none)))(principal-construct? 0x1a 0xfa6bf38ed557fe417333710d6033e9419391a320 "foo[") ;; Returns (err (tuple (error_code u2) (value none))) +(principal-construct? 0x1a 0xfa6bf38ed557fe417333710d6033e9419391a320) ;; Returns (ok ST3X6QWWETNBZWGBK6DRGTR1KX50S74D3425Q1TPK) +(principal-construct? 0x1a 0xfa6bf38ed557fe417333710d6033e9419391a320 "foo") ;; Returns (ok ST3X6QWWETNBZWGBK6DRGTR1KX50S74D3425Q1TPK.foo) +(principal-construct? 0x16 0xfa6bf38ed557fe417333710d6033e9419391a320) ;; Returns (err (tuple (error_code u0) (value (some SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY)))) +(principal-construct? 0x16 0xfa6bf38ed557fe417333710d6033e9419391a320 "foo") ;; Returns (err (tuple (error_code u0) (value (some SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY.foo)))) +(principal-construct? 0x 0xfa6bf38ed557fe417333710d6033e9419391a320) ;; Returns (err (tuple (error_code u1) (value none))) +(principal-construct? 0x16 0xfa6bf38ed557fe417333710d6033e9419391a3) ;; Returns (err (tuple (error_code u1) (value none))) +(principal-construct? 0x20 0xfa6bf38ed557fe417333710d6033e9419391a320) ;; Returns (err (tuple (error_code u1) (value none))) +(principal-construct? 0x1a 0xfa6bf38ed557fe417333710d6033e9419391a320 "") ;; Returns (err (tuple (error_code u2) (value none))) +(principal-construct? 0x1a 0xfa6bf38ed557fe417333710d6033e9419391a320 "foo[") ;; Returns (err (tuple (error_code u2) (value none))) ``` ## principal-destruct?​ @@ -1975,7 +2197,10 @@ Note: This function is only available starting with Stacks 2.1. **example:** ``` -(principal-destruct? 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6) ;; Returns (ok (tuple (hash-bytes 0x164247d6f2b425ac5771423ae6c80c754f7172b0) (name none) (version 0x1a)))(principal-destruct? 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.foo) ;; Returns (ok (tuple (hash-bytes 0x164247d6f2b425ac5771423ae6c80c754f7172b0) (name (some "foo")) (version 0x1a)))(principal-destruct? 'SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY) ;; Returns (err (tuple (hash-bytes 0xfa6bf38ed557fe417333710d6033e9419391a320) (name none) (version 0x16)))(principal-destruct? 'SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY.foo) ;; Returns (err (tuple (hash-bytes 0xfa6bf38ed557fe417333710d6033e9419391a320) (name (some "foo")) (version 0x16))) +(principal-destruct? 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6) ;; Returns (ok (tuple (hash-bytes 0x164247d6f2b425ac5771423ae6c80c754f7172b0) (name none) (version 0x1a))) +(principal-destruct? 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.foo) ;; Returns (ok (tuple (hash-bytes 0x164247d6f2b425ac5771423ae6c80c754f7172b0) (name (some "foo")) (version 0x1a))) +(principal-destruct? 'SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY) ;; Returns (err (tuple (hash-bytes 0xfa6bf38ed557fe417333710d6033e9419391a320) (name none) (version 0x16))) +(principal-destruct? 'SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY.foo) ;; Returns (err (tuple (hash-bytes 0xfa6bf38ed557fe417333710d6033e9419391a320) (name (some "foo")) (version 0x16))) ``` ## principal-of?​ @@ -2039,7 +2264,12 @@ If the provided index is out of bounds, this functions returns `none`. **example:** ``` -(replace-at? u"ab" u1 u"c") ;; Returns (some u"ac")(replace-at? 0x00112233 u2 0x44) ;; Returns (some 0x00114433)(replace-at? "abcd" u3 "e") ;; Returns (some "abce")(replace-at? (list 1) u0 10) ;; Returns (some (10))(replace-at? (list (list 1) (list 2)) u0 (list 33)) ;; Returns (some ((33) (2)))(replace-at? (list 1 2) u3 4) ;; Returns none +(replace-at? u"ab" u1 u"c") ;; Returns (some u"ac") +(replace-at? 0x00112233 u2 0x44) ;; Returns (some 0x00114433) +(replace-at? "abcd" u3 "e") ;; Returns (some "abce") +(replace-at? (list 1) u0 10) ;; Returns (some (10)) +(replace-at? (list (list 1) (list 2)) u0 (list 33)) ;; Returns (some ( (33) (2))) +(replace-at? (list 1 2) u3 4) ;; Returns none ``` ## secp256k1-recover?​ @@ -2079,7 +2309,9 @@ The `secp256k1-verify` function verifies that the provided signature of the mess **example:** ``` -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false +(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true +(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true +(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false ``` ## sha256​ @@ -2159,7 +2391,12 @@ The `slice?` function attempts to return a sub-sequence of that starts at `left- **example:** ``` -(slice? "blockstack" u5 u10) ;; Returns (some "stack")(slice? (list 1 2 3 4 5) u5 u9) ;; Returns none(slice? (list 1 2 3 4 5) u3 u4) ;; Returns (some (4))(slice? "abcd" u1 u3) ;; Returns (some "bc")(slice? "abcd" u2 u2) ;; Returns (some "")(slice? "abcd" u3 u1) ;; Returns none +(slice? "blockstack" u5 u10) ;; Returns (some "stack") +(slice? (list 1 2 3 4 5) u5 u9) ;; Returns none +(slice? (list 1 2 3 4 5) u3 u4) ;; Returns (some (4)) +(slice? "abcd" u1 u3) ;; Returns (some "bc") +(slice? "abcd" u2 u2) ;; Returns (some "") +(slice? "abcd" u3 u1) ;; Returns none ``` ## some​ @@ -2179,7 +2416,8 @@ The `some` function constructs a `optional` type from the input value. **example:** ``` -(some 1) ;; Returns (some 1)(is-none (some 2)) ;; Returns false +(some 1) ;; Returns (some 1) +(is-none (some 2)) ;; Returns false ``` ## sqrti​ @@ -2200,7 +2438,10 @@ Fails on a negative numbers. **example:** ``` -(sqrti u11) ;; Returns u3(sqrti 1000000) ;; Returns 1000(sqrti u1) ;; Returns u1(sqrti 0) ;; Returns 0 +(sqrti u11) ;; Returns u3 +(sqrti 1000000) ;; Returns 1000 +(sqrti u1) ;; Returns u1 +(sqrti 0) ;; Returns 0 ``` ## string-to-int?​ @@ -2222,7 +2463,9 @@ Note: This function is only available starting with Stacks 2.1. **example:** ``` -(string-to-int? "1") ;; Returns (some 1)(string-to-int? u"-1") ;; Returns (some -1)(string-to-int? "a") ;; Returns none +(string-to-int? "1") ;; Returns (some 1) +(string-to-int? u"-1") ;; Returns (some -1) +(string-to-int? "a") ;; Returns none ``` ## string-to-uint?​ @@ -2244,7 +2487,9 @@ Note: This function is only available starting with Stacks 2.1. **example:** ``` -(string-to-uint? "1") ;; Returns (some u1)(string-to-uint? u"1") ;; Returns (some u1)(string-to-uint? "a") ;; Returns none +(string-to-uint? "1") ;; Returns (some u1) +(string-to-uint? u"1") ;; Returns (some u1) +(string-to-uint? "a") ;; Returns none ``` ## stx-account​ @@ -2266,7 +2511,8 @@ This function returns a tuple with the canonical account representation for an S **example:** ``` -(stx-account 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns (tuple (locked u0) (unlock-height u0) (unlocked u0))(stx-account (as-contract tx-sender)) ;; Returns (tuple (locked u0) (unlock-height u0) (unlocked u1000)) +(stx-account 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns (tuple (locked u0) (unlock-height u0) (unlocked u0)) +(stx-account (as-contract tx-sender)) ;; Returns (tuple (locked u0) (unlock-height u0) (unlocked u1000)) ``` ## stx-burn?​ @@ -2290,7 +2536,8 @@ This function returns (ok true) if the transfer is successful. In the event of a **example:** ``` -(as-contract (stx-burn? u60 tx-sender)) ;; Returns (ok true)(as-contract (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) +(as-contract (stx-burn? u60 tx-sender)) ;; Returns (ok true) +(as-contract (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) ``` ## stx-get-balance​ @@ -2312,7 +2559,8 @@ This function returns the STX balance, in microstacks (1 STX = 1,000,000 microst **example:** ``` -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 +(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 +(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 ``` ## stx-transfer-memo?​ @@ -2358,7 +2606,9 @@ This function returns (ok true) if the transfer is successful. In the event of a **example:** ``` -(as-contract (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true)(as-contract (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true)(as-contract (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) +(as-contract (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) +(as-contract (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) +(as-contract (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) ``` ## to-consensus-buff?​ @@ -2380,7 +2630,13 @@ If the value cannot fit as serialized into the maximum buffer size, this returns **example:** ``` -(to-consensus-buff? 1) ;; Returns (some 0x0000000000000000000000000000000001)(to-consensus-buff? u1) ;; Returns (some 0x0100000000000000000000000000000001)(to-consensus-buff? true) ;; Returns (some 0x03)(to-consensus-buff? false) ;; Returns (some 0x04)(to-consensus-buff? none) ;; Returns (some 0x09)(to-consensus-buff? 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns (some 0x051fa46ff88886c2ef9762d970b4d2c63678835bd39d)(to-consensus-buff? { abc: 3, def: 4 }) ;; Returns (some 0x0c00000002036162630000000000000000000000000000000003036465660000000000000000000000000000000004) +(to-consensus-buff? 1) ;; Returns (some 0x0000000000000000000000000000000001) +(to-consensus-buff? u1) ;; Returns (some 0x0100000000000000000000000000000001) +(to-consensus-buff? true) ;; Returns (some 0x03) +(to-consensus-buff? false) ;; Returns (some 0x04) +(to-consensus-buff? none) ;; Returns (some 0x09) +(to-consensus-buff? 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns (some 0x051fa46ff88886c2ef9762d970b4d2c63678835bd39d) +(to-consensus-buff? { abc: 3, def: 4 }) ;; Returns (some 0x0c00000002036162630000000000000000000000000000000003036465660000000000000000000000000000000004) ``` ## to-int​ @@ -2440,7 +2696,17 @@ The `try!` function attempts to 'unpack' the first argument: if the argument is **example:** ``` -(define-map names-map { name: (string-ascii 12) } { id: int })(map-set names-map { name: "blockstack" } { id: 1337 })(try! (map-get? names-map { name: "blockstack" })) ;; Returns (tuple (id 1337))(define-private (checked-even (x int)) (if (is-eq (mod x 2) 0) (ok x) (err false)))(define-private (double-if-even (x int)) (ok (* 2 (try! (checked-even x)))))(double-if-even 10) ;; Returns (ok 20)(double-if-even 3) ;; Returns (err false) +(define-map names-map { name: (string-ascii 12) } { id: int }) +(map-set names-map { name: "blockstack" } { id: 1337 }) +(try! (map-get? names-map { name: "blockstack" })) ;; Returns (tuple (id 1337)) +(define-private (checked-even (x int)) + (if (is-eq (mod x 2) 0) + (ok x) + (err false))) +(define-private (double-if-even (x int)) + (ok (* 2 (try! (checked-even x))))) +(double-if-even 10) ;; Returns (ok 20) +(double-if-even 3) ;; Returns (err false) ``` ## tuple​ @@ -2462,7 +2728,9 @@ There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, **example:** ``` -(tuple (name "blockstack") (id 1337)) ;; using tuple {name: "blockstack", id: 1337} ;; using curly brackets +(tuple (name "blockstack") +(id 1337)) ;; using tuple +{name: "blockstack", id: 1337} ;; using curly brackets ``` ## unwrap @@ -2482,7 +2750,13 @@ The `unwrap!` function attempts to 'unpack' the first argument: if the argument **example:** ``` -(define-map names-map { name: (string-ascii 12) } { id: int })(map-set names-map { name: "blockstack" } { id: 1337 })(define-private (get-name-or-err (name (string-ascii 12))) (let ((raw-name (unwrap! (map-get? names-map { name: name }) (err 1)))) (ok raw-name)))(get-name-or-err "blockstack") ;; Returns (ok (tuple (id 1337)))(get-name-or-err "non-existant") ;; Returns (err 1) +(define-map names-map { name: (string-ascii 12) } { id: int }) +(map-set names-map { name: "blockstack" } { id: 1337 }) +(define-private (get-name-or-err (name (string-ascii 12))) + (let ( (raw-name (unwrap! (map-get? names-map { name: name }) (err 1)))) + (ok raw-name))) +(get-name-or-err "blockstack") ;; Returns (ok (tuple (id 1337))) +(get-name-or-err "non-existant") ;; Returns (err 1) ``` ## unwrap-err @@ -2522,7 +2796,8 @@ The `unwrap-err` function attempts to 'unpack' the first argument: if the argume **example:** ``` -(unwrap-err-panic (err 1)) ;; Returns 1(unwrap-err-panic (ok 1)) ;; Throws a runtime exception +(unwrap-err-panic (err 1)) ;; Returns 1 +(unwrap-err-panic (ok 1)) ;; Throws a runtime exception ``` ## unwrap-panic​ @@ -2542,7 +2817,10 @@ The `unwrap` function attempts to 'unpack' its argument: if the argument is an o **example:** ``` -(define-map names-map { name: (string-ascii 12) } { id: int })(map-set names-map { name: "blockstack" } { id: 1337 })(unwrap-panic (map-get? names-map { name: "blockstack" })) ;; Returns (tuple (id 1337))(unwrap-panic (map-get? names-map { name: "non-existant" })) ;; Throws a runtime exception +(define-map names-map { name: (string-ascii 12) } { id: int }) +(map-set names-map { name: "blockstack" } { id: 1337 }) +(unwrap-panic (map-get? names-map { name: "blockstack" })) ;; Returns (tuple (id 1337)) +(unwrap-panic (map-get? names-map { name: "non-existant" })) ;; Throws a runtime exception ``` ## use-trait​ @@ -2566,7 +2844,9 @@ Like other kinds of definition statements, `use-trait` may only be used at the t **example:** ``` -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait)(define-public (forward-get-balance (user principal) (contract )) (begin (ok 1))) +(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) +(define-public (forward-get-balance (user principal) (contract )) + (begin (ok 1))) ``` ## var-get​ @@ -2586,7 +2866,8 @@ The `var-get` function looks up and returns an entry from a contract's data map. **example:** ``` -(define-data-var cursor int 6)(var-get cursor) ;; Returns 6 +(define-data-var cursor int 6) +(var-get cursor) ;; Returns 6 ``` ## var-set​ @@ -2606,7 +2887,10 @@ The `var-set` function sets the value associated with the input variable to the **example:** ``` -(define-data-var cursor int 6)(var-get cursor) ;; Returns 6(var-set cursor (+ (var-get cursor) 1)) ;; Returns true(var-get cursor) ;; Returns 7 +(define-data-var cursor int 6) +(var-get cursor) ;; Returns 6 +(var-set cursor (+ (var-get cursor) 1)) ;; Returns true +(var-get cursor) ;; Returns 7 ``` ## xor​ @@ -2626,5 +2910,6 @@ Returns the result of bitwise exclusive or'ing `i1` with `i2`. **example:** ``` -(xor 1 2) ;; Returns 3(xor 120 280) ;; Returns 352 +(xor 1 2) ;; Returns 3 +(xor 120 280) ;; Returns 352 ```