Hiro Docs

Using the addition function for arithmetic operations in Clarity smart contracts.

The addition function (+) in Clarity performs addition on a variable number of integer inputs. It's a fundamental arithmetic operation used in many smart contract calculations.

Function Signature

(+ i1 i2...)

Input: Two or more integers (int or uint)
Output: A single integer (int or uint)

Why it matters

The addition function is crucial for:

Performing basic arithmetic calculations within smart contracts.
Incrementing counters or values.
Combining multiple quantities or balances.
Implementing mathematical formulas that involve addition.

When to use it

Use the addition function when you need to:

Perform basic addition in your contract logic.
Increment values or counters.
Sum up multiple values.
Implement mathematical formulas that involve addition.

Best Practices

Always consider the possibility of overflow when adding large numbers.
Use appropriate types (int or uint) based on your needs and expected value ranges.
Be aware that adding negative numbers to positive numbers can result in subtraction.
Consider using checked arithmetic functions if overflow detection is critical.

Practical Example: Simple Counter

Let's implement a simple counter that uses the addition function to increment its value:

(define-data-var counter int 0)

(define-public (increment-counter (amount int))
  (begin
    (var-set counter (+ (var-get counter) amount))
    (ok (var-get counter))
  )
)

;; Usage
(increment-counter 1) ;; Increments the counter by 1
(increment-counter 5) ;; Increments the counter by 5

This example demonstrates:

Using addition to increment the value of a counter.
Implementing a public function to handle the increment operation.
Returning the updated counter value.

Common Pitfalls

Overlooking potential overflow when adding large numbers.
Not considering the effect of adding negative numbers (for int types).
Forgetting to update related variables or state when incrementing values.

-: Used for subtraction operations.
*: Used for multiplication operations.
/: Used for division operations.

The addition function is a fundamental tool for performing arithmetic operations in Clarity smart contracts. By understanding its behavior with different types of inputs and potential edge cases, developers can use it effectively to implement various mathematical operations in their contracts, from simple increments to more complex calculations.

add