Add comparison functions by turbolent · Pull Request #4430 · onflow/cadence

turbolent · 2026-02-06T00:39:07Z

Description

Implement FLIP 357: Add minOf and maxOf Functions to Cadence.

Add new functions minOf<T>(T, T) and maxOf<T>(T, T), where T must be comparable (we can't express this with a type bound yet).

The tests are currently only run with the interpreter, just like the rest of the stdlib tests. I left a TODO in #3804 to refactor all tests to be also run with the compiler/VM.

The names are not min/max, as existing contracts commonly use these names e.g. in variable declarations, and would break, as we do not allow shadowing of built-in functions. The names are taken from Kotlin: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.comparisons/min-of.html

Targeted PR against master branch
Linked to Github issue with discussion and accepted design OR link to spec that describes this work
Code follows the standards mentioned here
Updated relevant documentation
Re-reviewed Files changed in the Github PR explorer
Added appropriate labels

github-actions · 2026-02-06T00:39:18Z

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA 3d2aac8.

Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

Scanned Files

None

github-actions · 2026-02-06T00:43:04Z

Benchstat comparison

Base branch: onflow:master
Base commit: b585d8d

Results

	old.txt	new.txt
	time/op		delta
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ByteArrayTransfer-4	1.28µs ± 0%	1.31µs ± 0%	~	(p=1.000 n=1+1)
ByteArrayValueToByteSlice-4	78.4ns ± 0%	83.0ns ± 0%	~	(p=1.000 n=1+1)
ByteSliceToByteArrayValue-4	937ns ± 0%	1039ns ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
ContractFunctionInvocation-4	380µs ± 0%	389µs ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
EMVAddressTransfer-4	3.44µs ± 0%	3.52µs ± 0%	~	(p=1.000 n=1+1)
Emit-4	4.63ms ± 0%	4.54ms ± 0%	~	(p=1.000 n=1+1)
EnumTransfer-4	1.28µs ± 0%	1.40µs ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
ExportType/composite_type-4	270ns ± 0%	286ns ± 0%	~	(p=1.000 n=1+1)
ExportType/simple_type-4	77.7ns ± 0%	78.4ns ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/sema goos:linux goarch:amd64
FlowTokenContract-4	618µs ± 0%	610µs ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ImperativeFib-4	23.0µs ± 0%	23.8µs ± 0%	~	(p=1.000 n=1+1)
InterpretRecursionFib-4	2.33ms ± 0%	2.42ms ± 0%	~	(p=1.000 n=1+1)
NewInterpreter/new_interpreter-4	860ns ± 0%	903ns ± 0%	~	(p=1.000 n=1+1)
NewInterpreter/new_sub-interpreter-4	324ns ± 0%	338ns ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/sema goos:linux goarch:amd64
QualifiedIdentifierCreation/One_level-4	2.18ns ± 0%	2.19ns ± 0%	~	(p=1.000 n=1+1)
QualifiedIdentifierCreation/Three_levels-4	81.9ns ± 0%	82.8ns ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
RuntimeFungibleTokenTransferInterpreter-4	627µs ± 0%	616µs ± 0%	~	(p=1.000 n=1+1)
RuntimeFungibleTokenTransferVM-4	722µs ± 0%	715µs ± 0%	~	(p=1.000 n=1+1)
RuntimeResourceDictionaryValues-4	2.83ms ± 0%	2.69ms ± 0%	~	(p=1.000 n=1+1)
RuntimeResourceTracking-4	10.3ms ± 0%	9.6ms ± 0%	~	(p=1.000 n=1+1)
RuntimeScriptNoop-4	14.8µs ± 0%	14.7µs ± 0%	~	(p=1.000 n=1+1)
RuntimeVMInvokeContractImperativeFib-4	41.9µs ± 0%	41.2µs ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/sema goos:linux goarch:amd64
SuperTypeInference/arrays-4	236ns ± 0%	226ns ± 0%	~	(p=1.000 n=1+1)
SuperTypeInference/composites-4	94.5ns ± 0%	94.4ns ± 0%	~	(p=1.000 n=1+1)
SuperTypeInference/integers-4	317ns ± 0%	319ns ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ValueIsSubtypeOfSemaType-4	61.0ns ± 0%	62.8ns ± 0%	~	(p=1.000 n=1+1)

	alloc/op		delta
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ByteArrayTransfer-4	1.07kB ± 0%	1.04kB ± 0%	~	(p=1.000 n=1+1)
ByteArrayValueToByteSlice-4	32.0B ± 0%	32.0B ± 0%	~	(all equal)
ByteSliceToByteArrayValue-4	850B ± 0%	844B ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
ContractFunctionInvocation-4	144kB ± 0%	144kB ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
EMVAddressTransfer-4	2.46kB ± 0%	2.46kB ± 0%	~	(p=1.000 n=1+1)
Emit-4	1.50MB ± 0%	1.50MB ± 0%	~	(p=1.000 n=1+1)
EnumTransfer-4	870B ± 0%	828B ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
ExportType/composite_type-4	120B ± 0%	120B ± 0%	~	(all equal)
ExportType/simple_type-4	0.00B	0.00B	~	(all equal)
pkg:github.com/onflow/cadence/sema goos:linux goarch:amd64
FlowTokenContract-4	226kB ± 0%	226kB ± 0%	~	(p=1.000 n=1+1)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ImperativeFib-4	8.30kB ± 0%	8.30kB ± 0%	~	(all equal)
InterpretRecursionFib-4	1.19MB ± 0%	1.19MB ± 0%	~	(p=1.000 n=1+1)
NewInterpreter/new_interpreter-4	976B ± 0%	976B ± 0%	~	(all equal)
NewInterpreter/new_sub-interpreter-4	232B ± 0%	232B ± 0%	~	(all equal)
pkg:github.com/onflow/cadence/sema goos:linux goarch:amd64
QualifiedIdentifierCreation/One_level-4	0.00B	0.00B	~	(all equal)
QualifiedIdentifierCreation/Three_levels-4	64.0B ± 0%	64.0B ± 0%	~	(all equal)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
RuntimeFungibleTokenTransferInterpreter-4	165kB ± 0%	165kB ± 0%	~	(p=1.000 n=1+1)
RuntimeFungibleTokenTransferVM-4	188kB ± 0%	189kB ± 0%	~	(p=1.000 n=1+1)
RuntimeResourceDictionaryValues-4	1.76MB ± 0%	1.76MB ± 0%	~	(p=1.000 n=1+1)
RuntimeResourceTracking-4	6.98MB ± 0%	6.98MB ± 0%	~	(p=1.000 n=1+1)
RuntimeScriptNoop-4	8.09kB ± 0%	8.08kB ± 0%	~	(p=1.000 n=1+1)
RuntimeVMInvokeContractImperativeFib-4	13.4kB ± 0%	13.4kB ± 0%	~	(all equal)
pkg:github.com/onflow/cadence/sema goos:linux goarch:amd64
SuperTypeInference/arrays-4	72.0B ± 0%	72.0B ± 0%	~	(all equal)
SuperTypeInference/composites-4	0.00B	0.00B	~	(all equal)
SuperTypeInference/integers-4	0.00B	0.00B	~	(all equal)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ValueIsSubtypeOfSemaType-4	32.0B ± 0%	32.0B ± 0%	~	(all equal)

	allocs/op		delta
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ByteArrayTransfer-4	7.00 ± 0%	7.00 ± 0%	~	(all equal)
ByteArrayValueToByteSlice-4	1.00 ± 0%	1.00 ± 0%	~	(all equal)
ByteSliceToByteArrayValue-4	5.00 ± 0%	5.00 ± 0%	~	(all equal)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
ContractFunctionInvocation-4	2.25k ± 0%	2.25k ± 0%	~	(all equal)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
EMVAddressTransfer-4	29.0 ± 0%	29.0 ± 0%	~	(all equal)
Emit-4	40.0k ± 0%	40.0k ± 0%	~	(all equal)
EnumTransfer-4	13.0 ± 0%	13.0 ± 0%	~	(all equal)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
ExportType/composite_type-4	3.00 ± 0%	3.00 ± 0%	~	(all equal)
ExportType/simple_type-4	0.00	0.00	~	(all equal)
pkg:github.com/onflow/cadence/sema goos:linux goarch:amd64
FlowTokenContract-4	3.58k ± 0%	3.58k ± 0%	~	(all equal)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ImperativeFib-4	176 ± 0%	176 ± 0%	~	(all equal)
InterpretRecursionFib-4	17.7k ± 0%	17.7k ± 0%	~	(all equal)
NewInterpreter/new_interpreter-4	15.0 ± 0%	15.0 ± 0%	~	(all equal)
NewInterpreter/new_sub-interpreter-4	4.00 ± 0%	4.00 ± 0%	~	(all equal)
pkg:github.com/onflow/cadence/sema goos:linux goarch:amd64
QualifiedIdentifierCreation/One_level-4	0.00	0.00	~	(all equal)
QualifiedIdentifierCreation/Three_levels-4	2.00 ± 0%	2.00 ± 0%	~	(all equal)
pkg:github.com/onflow/cadence/runtime goos:linux goarch:amd64
RuntimeFungibleTokenTransferInterpreter-4	3.08k ± 0%	3.08k ± 0%	~	(all equal)
RuntimeFungibleTokenTransferVM-4	3.61k ± 0%	3.61k ± 0%	~	(all equal)
RuntimeResourceDictionaryValues-4	36.7k ± 0%	36.7k ± 0%	~	(all equal)
RuntimeResourceTracking-4	129k ± 0%	129k ± 0%	~	(p=1.000 n=1+1)
RuntimeScriptNoop-4	114 ± 0%	114 ± 0%	~	(all equal)
RuntimeVMInvokeContractImperativeFib-4	426 ± 0%	426 ± 0%	~	(all equal)
pkg:github.com/onflow/cadence/sema goos:linux goarch:amd64
SuperTypeInference/arrays-4	3.00 ± 0%	3.00 ± 0%	~	(all equal)
SuperTypeInference/composites-4	0.00	0.00	~	(all equal)
SuperTypeInference/integers-4	0.00	0.00	~	(all equal)
pkg:github.com/onflow/cadence/interpreter goos:linux goarch:amd64
ValueIsSubtypeOfSemaType-4	1.00 ± 0%	1.00 ± 0%	~	(all equal)

SupunS

Nice!

stdlib/comparison_test.go

turbolent · 2026-02-06T16:23:39Z

Unfortunately, adding new built-ins causes checking errors for several deployed contracts, as we do not allow shadowing of built-ins, and min and max are frequently used variable names.

I guess we could introduce a Math contract and have Math.min and Math.max?

SupunS · 2026-02-06T19:06:17Z

ah I see!

I guess we could introduce a Math contract and have Math.min and Math.max?

This sounds like a good idea. I guess we would have to limit it for Number types only (rather than all comparable types - mainly because the of the naming).

turbolent · 2026-02-06T19:18:02Z

We already ran into this problem in #3055, and had started discussing a solution there: #3055 (comment)

From @dete:

I’ve never seen it before, but you could implement max, min, (and maybe clamp) as a member variable on the numeric types.
let x: Fix64 = ...
x = x.max(10.0)
x = x.clamp(0.0, 1.0)
Math.min and Math.max would be more typical, but now that I’m thinking about it, the max, min, clamp functions seem really quite clean. Could be clampMax, clampMin and clamp since the semantics are different.

Swift does that for some functions, like sqrt: https://developer.apple.com/documentation/swift/double/squareroot(), and uses static functions for e.g min/max: https://developer.apple.com/documentation/swift/double/maximum(_:_:). We have static functions for built-in types, so that would also be an option for us

turbolent · 2026-02-09T18:10:44Z

Regarding min and max specifically, we already have min and max fields on the types which return the minimum and maximum value representable by the type (e.g. UInt8.max == 255), so we would have to name the functions differently, e.g. minimum and maximum.

These functions are also not tied to numeric types, but useful for any comparable type. In that sense defining them in a Math module is not really appropriate.

turbolent · 2026-02-09T22:28:24Z

I kept it simple and took inspiration from Kotlin, where the functions have an Of suffix, e.g. https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.comparisons/min-of.html. This does not break any currently deployed contracts.

SupunS

kept it simple and took inspiration from Kotlin, where the functions have a Of suffix

That's a great idea!

stdlib/comparison.go

codecov · 2026-02-17T23:01:25Z

Codecov Report

❌ Patch coverage is 89.18919% with 16 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
stdlib/comparison.go	89.18%	10 Missing and 6 partials ⚠️

📢 Thoughts on this report? Let us know!

stdlib/comparison.go

Co-authored-by: Raymond Zhang <zhangraymond05@gmail.com>

SupunS · 2026-04-08T22:44:18Z

stdlib/comparison_test.go

+		_, err := parseAndCheck(t, `
+            import Comparison
+
+            let result: Int = min(5, 10)


Doesn't the function name need to be import-qualified? e.g: Comparison.min(...)?

No, in the FLIP the proposal was to define a new built-in location Comparison, but it exports the functions directly, not nested in a contract.

I still think that makes sense for such ubiquitous functions. Requiring the functions to be qualified would make the expressions where they are used very verbose, to the point where developers likely will just opt to not use them.

add min and max functions

4bedb5a

turbolent self-assigned this Feb 6, 2026

turbolent requested review from RZhang05 and SupunS as code owners February 6, 2026 00:39

turbolent added the Feature label Feb 6, 2026

SupunS approved these changes Feb 6, 2026

View reviewed changes

stdlib/comparison_test.go Outdated Show resolved Hide resolved

turbolent changed the title ~~Add min and max functions~~ Add minOf and maxOf functions Feb 9, 2026

turbolent force-pushed the bastian/min-max-functions branch from fc97a02 to 32abb30 Compare February 9, 2026 22:27

rename min/max to minOf/maxOf

5e12934

turbolent force-pushed the bastian/min-max-functions branch from 32abb30 to 5e12934 Compare February 9, 2026 22:48

turbolent mentioned this pull request Feb 9, 2026

FLIP 357: Add Comparison Functions to Cadence onflow/flips#357

Open

SupunS approved these changes Feb 9, 2026

View reviewed changes

SupunS reviewed Feb 9, 2026

View reviewed changes

stdlib/comparison.go Show resolved Hide resolved

turbolent added 3 commits February 9, 2026 16:00

assert return types

4b87ffe

Merge branch 'master' into bastian/min-max-functions

f7475c7

rename to min/max, define in Comparison location

f1a5561

turbolent changed the title ~~Add minOf and maxOf functions~~ Add Comparison functions Feb 17, 2026

turbolent changed the title ~~Add Comparison functions~~ Add comparison functions Feb 17, 2026

add clamp function

e9ae4a8

RZhang05 reviewed Feb 18, 2026

View reviewed changes

stdlib/comparison.go Outdated Show resolved Hide resolved

turbolent and others added 2 commits February 20, 2026 10:59

remove unnecessary cast

3089b79

Co-authored-by: Raymond Zhang <zhangraymond05@gmail.com>

Merge branch 'master' into bastian/min-max-functions

b78b250

add docstrings

15fe578

turbolent requested review from RZhang05 and SupunS March 10, 2026 20:53

Merge branch 'master' into bastian/min-max-functions

3d2aac8

SupunS approved these changes Apr 8, 2026

View reviewed changes

turbolent requested a review from SupunS April 8, 2026 23:50

Conversation

turbolent commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

github-actions bot commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Review

Snapshot Warnings

Scanned Files

Uh oh!

github-actions bot commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchstat comparison

Uh oh!

SupunS left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

turbolent commented Feb 6, 2026

Uh oh!

SupunS commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

turbolent commented Feb 6, 2026

Uh oh!

turbolent commented Feb 9, 2026

Uh oh!

turbolent commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SupunS left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codecov bot commented Feb 17, 2026

Codecov Report

Uh oh!

Uh oh!

SupunS Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

turbolent Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

turbolent commented Feb 6, 2026 •

edited

Loading

github-actions bot commented Feb 6, 2026 •

edited

Loading

github-actions bot commented Feb 6, 2026 •

edited

Loading

SupunS commented Feb 6, 2026 •

edited

Loading

turbolent commented Feb 9, 2026 •

edited

Loading