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:

Handling different branches or cases for optional and response types.
Simplifying complex conditional logic.
Enhancing code readability and maintainability.
Ensuring 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:

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

Common Pitfalls

Using match without covering all possible branches, leading to unhandled cases.
Assuming the value will always match a certain branch, causing runtime errors.
Not handling all possible conditions, resulting in incomplete logic.
Overlooking 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