Hiro Docs

Function Signature

(match opt-input some-binding-name some-branch none-branch)
(match-resp input ok-binding-name ok-branch err-binding-name err-branch)

Input: (optional A) name expression expression | (response A B) name expression name expression
Output: C

Why it matters

The match function is crucial for:

1Handling different branches or cases for optional and response types.
2Simplifying complex conditional logic.
3Enhancing code readability and maintainability.
4Ensuring comprehensive handling of all possible cases.

When to use it

Use match when you need to:

Handle different branches or cases for optional and response types.
Simplify complex conditional logic.
Enhance the readability and maintainability of your code.
Ensure comprehensive handling of all possible cases.

Best Practices

Ensure all possible branches are covered to avoid unhandled cases.
Use meaningful variable names for better readability.
Combine with other control flow functions for more complex logic.
Be aware of the performance implications of extensive branching.

Practical Example: Handling Optional and Response Values

Let's implement functions that handle optional and response values using match:

(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")

This example demonstrates:

1Using match to handle the result of an optional value.
2Using match to handle the result of a response value.
3Implementing functions to return the appropriate result based on the input type.

Common Pitfalls

1Using match without covering all possible branches, leading to unhandled cases.
2Assuming the value will always match a certain branch, causing runtime errors.
3Not handling all possible conditions, resulting in incomplete logic.
4Overlooking the need for proper error handling and validation.

if: Implements conditional logic based on boolean expressions.
let: Binds variables to expressions within a local scope.
default-to: Provides default values for optional types.

The match function is a fundamental tool for handling different branches or cases in Clarity smart contracts. It allows developers to manage optional and response types, simplify complex conditional logic, and ensure comprehensive handling of all possible cases. When used effectively, match enhances the reliability and maintainability of your smart contract code by providing a clear and concise way to manage branching logic.

match