Unchecked Counter

Solidity counter type that bypasses checked arithmetic, designed to be used in for loops.

Background

User-defined value types (UDVTs) provide a means to create aliases for elementary Solidity types, resulting in a zero-cost abstraction that enhances type safety and improves code readability. Solidity v0.8.19 onwards allows for the binding of operators such as + to UDVTs, making the syntax even more concise and expressive.

Further recommended reading on this topic:

• Solidity v0.8.8: User-Defined Value Types
• Solidity v0.8.19: User-Defined Operators

Install

forge install PaulRBerg/unchecked-counter@v1

Your .gitmodules file should now contain the following entry:

[submodule "lib/unchecked-counter"]
  branch = "v1"
  path = "lib/unchecked-counter"
  url = "https://github.com/PaulRBerg/unchecked-counter"

Usage

With Casting Function

// SPDX-License-Identifier: UNLICENSED
pragma solidity >=0.8.19;

import { UC, uc } from "unchecked-counter/UC.sol";

// Example that uses the `uc` casting function
function iterate(uint256[] memory arr) pure {
  for (UC i = uc(0); i < uc(100); i = i + uc(1)) {
      uint256 element = arr[i.into()]; // or `i.unwrap()`
  }
}

With Constants

// SPDX-License-Identifier: UNLICENSED
pragma solidity >=0.8.19;

import { ONE, UC, ZERO } from "unchecked-counter/UC.sol";

// Example that uses the constants `ONE` and `ZERO`
function iterate(uint256[] memory arr) pure {
  uint256 counter;
  for (UC i = uc(0); i < uc(100); i = i + uc(1)) {
      uint256 element = arr[i.into()]; // or `i.unwrap()`
  }
}

Contributing

Feel free to dive in! Open an issue, start a discussion or submit a PR.

Pre Requisites

You will need the following software on your machine:

• Git
• Foundry
• Node.Js
• Yarn

In addition, familiarity with Solidity is requisite.

Set Up

Clone this repository including submodules:

$ git clone --recurse-submodules -j8 [email protected]:PaulRBerg/unchecked-counter.git

Then, inside the project's directory, run this to install the Node.js dependencies:

$ yarn install

Now you can start making changes.

License

MIT © Paul Razvan Berg