Hiro Docs

Function Signature

(map-insert map-name key-tuple value-tuple)

Input: MapName, tuple_A, tuple_B
Output: bool

Why it matters

The map-insert function is crucial for:

Adding new entries to a map.
Ensuring data integrity by preventing overwrites of existing entries.
Simplifying the process of managing data in smart contracts.
Enabling the creation of unique key-value pairs in maps.

When to use it

Use map-insert when you need to:

Add a new entry to a map.
Ensure that existing entries are not overwritten.
Manage data in your smart contract.
Create unique key-value pairs in maps.

Best Practices

Ensure the key-tuple and value-tuple are correctly formatted.
Use meaningful variable names for better readability.
Combine with other map functions for comprehensive map management.
Handle the case where the key already exists to avoid unexpected behavior.

Practical Example: Inserting User Data

Let's implement a function that inserts a user's data into a map:

(define-map UserData { userId: principal } { data: (buff 32) })

(define-public (insert-user-data (user principal) (data (buff 32)))
  (ok (map-insert UserData { userId: user } { data: data }))
)

;; Usage
(insert-user-data tx-sender 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef) ;; Returns (ok true) if the entry is inserted
(insert-user-data tx-sender 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef) ;; Returns (ok false) if the entry already exists

This example demonstrates:

Using map-insert to add a user's data to the UserData map.
Implementing a public function to insert the data.
Handling both the case where the entry is successfully inserted and where it already exists.

Common Pitfalls

Using map-insert with incorrectly formatted tuples, causing the insertion to fail.
Assuming the entry will always be inserted, leading to unhandled cases.
Not handling all possible conditions, resulting in incomplete data management.
Overlooking the need for proper error handling and validation.

map-set: Sets the value associated with a key in a map, overwriting any existing value.
map-delete: Removes an entry from a map.
map-get?: Retrieves an entry from a map.

The map-insert function is a fundamental tool for adding entries to maps in Clarity smart contracts. It allows developers to manage data, ensure data integrity, and create unique key-value pairs. When used effectively, map-insert enhances the reliability and maintainability of your smart contract code by providing a clear and concise way to manage data insertion.

map-insert