Hiro Docs

Function Signature

(index-of list element)

Input:
- list: A list of elements
- element: The element to find in the list
Output: (optional uint)

Why it matters

The index-of function is crucial for:

Locating the position of an element within a list.
Implementing search functionality in smart contracts.
Enabling conditional logic based on the presence and position of elements.
Simplifying list operations by providing a built-in search mechanism.

When to use it

Use index-of when you need to:

Determine the position of an element in a list.
Check if an element exists in a list and retrieve its index.
Implement logic that depends on the order or position of elements.
Simplify list search operations without writing custom loops.

Best Practices

Ensure the list and element types are compatible.
Handle the none case when the element is not found in the list.
Use meaningful variable names for better readability.
Consider the performance implications when searching large lists.

Practical Example: Finding an Element in a List

Let's implement a function that finds the index of a given element in a list of integers:

(define-read-only (find-index (element int) (numbers (list 10 int)))
  (index-of numbers element))

;; Usage
(find-index 3 (list 1 2 3 4 5)) ;; Returns (some u2)
(find-index 6 (list 1 2 3 4 5)) ;; Returns none

This example demonstrates:

Using index-of to find the position of an element in a list.
Handling both the case where the element is found and where it is not found.

Common Pitfalls

Assuming the element will always be found, leading to unhandled none cases.
Using index-of on lists with incompatible element types.
Overlooking the performance impact of searching very large lists.
Not considering that index-of returns a 0-based index.

filter: Used to create a new list containing only elements that match a condition.
map: Applies a function to each element in a list, transforming the elements.
len: Returns the length of a list.

The index-of function is a powerful tool for locating elements within lists in Clarity smart contracts. It provides a straightforward way to search for elements and retrieve their positions, enabling more complex list operations and conditional logic. When used effectively, index-of simplifies list search operations and enhances the readability and maintainability of your smart contract code.

index-of