Implicit parameters

Overview

Implicit parameters allow you to omit frequently-used function arguments at call sites when the compiler can infer them from context. This feature is particularly useful when working with ordered collections like Map and Set from the core library, which require comparison functions but where the comparison logic is usually obvious from the key type. Other examples are equal and toText functions.

Basic usage

Declaring implicit parameters

When declaring a function, any function parameter can be declared implicit using the implicit type constructor:

For example, the core Map library declares a function:

public func add<K, V>(self: Map<K, V>, compare : (implicit : (K, K) -> Order), key : K, value : V) {
  // ...
}

The implicit marker on the type of parameter compare indicates the call-site can omit the compare argument, provided it can be inferred at the call site.

A function can declare more than one implicit parameter, even of the same name.

func show<T, U>(
    self: (T, U),
    toTextT : (implicit : (toText : T -> Text)),
    toTextU : (implicit : (toText : U -> Text))) : Text {
  "(" # toTextT(self.0) # "," # toTextU(self.1) # ")"
}

In these cases, you can add an inner name to indicate the external names of the implicit parameters (both toText) and distinguish them from the names used with the function body, toTextT and toTextU: these need to be distinct so that the body can call them. The inner name (under implicit) overrides the local name of the parameter in the body.

Calling functions with implicit arguments

When calling a function with implicit parameters, you can omit the implicit arguments if the compiler can infer them:

import Map "mo:core/Map";
import Nat "mo:core/Nat";

let map = Map.empty<Nat, Text>();

// Without implicits - must provide compare function explicitly
Map.add(map, Nat.compare, 5, "five");

// With implicits - compare function inferred from key type
Map.add(map, 5, "five");

The compiler automatically finds an appropriate comparison function based on the type of the key argument.

The available candidates are:

• Any value named compare whose type matches the parameter type.

If there is no such value,

• Any field named M.compare declared in some module available M.
• If there is more than one such field, none of which is more specific than all the others, the call is ambiguous.

An ambiguous call can always be disambiguated by supplying the explicit arguments for all implicit parameters.

Contextual dot notation

Implicit parameters dovetail nicely with contextual dot notation. The dot notation and implicit arguments can be used in conjunction to shorten code.

For example, since the first parameter of Map.add is called self, we can both use map as the receiver of add “method” calls and omit the tedious compare argument:

import Map "mo:core/Map";
import Nat "mo:core/Nat";

let map = Map.empty<Nat, Text>();

// Using contextual dot notation, without implicits - must provide compare function explicitly
map.add(Nat.compare, 5, "five");

// Using contextual dot notation together with implicits - compare function inferred from key type
map.add(5, "five");

Working with ordered collections

The primary use case for implicit arguments is simplifying code that uses maps and sets from the core library.

Map Example

import Map "mo:core/Map";
import Nat "mo:core/Nat";

let inventory = Map.empty<Nat, Text>();

// Old style: explicitly pass Nat.compare
Map.add(inventory, Nat.compare, 101, "Widget");
Map.add(inventory, Nat.compare, 102, "Gadget");
Map.add(inventory, Nat.compare, 103, "Doohickey");

let item1 = Map.get(inventory, Nat.compare, 102);

// With contextual dots and implicits: compare function inferred
inventory.add(101, "Widget");
inventory.add(102, "Gadget");
inventory.add(103, "Doohickey");

let item2 = inventory.get(102);

Set example

The core Set type also takes advantage of implicit compare parameters.

import Set "mo:core/Set";
import Text "mo:core/Text";

let tags = Set.empty<Text>();

// Old style
Set.add(tags, Text.compare, "urgent");
Set.add(tags, Text.compare, "reviewed");
let hasTag1 = Set.contains(tags, Text.compare, "urgent");

// With implicits
tags.add("urgent");
tags.add("reviewed");
let hasTag2 = tags.contains("urgent");

Building collections incrementally

Implicit arguments make imperative collection operations much cleaner:

import Map "mo:core/Map";
import Text "mo:core/Text";

let scores = Map.empty<Text, Nat>();

// Add player scores
scores.add("Alice", 100);
scores.add("Bob", 85);
scores.add("Charlie", 92);

// Update a score
scores.add("Bob", 95);

// Check and remove
if (scores.containsKey("Alice")) {
  scores.remove("Alice");
};

// Get size
let playerCount = scores.size();

How inference works

The compiler infers an implicit argument by:

1. Examining the types of the explicit arguments provided.
2. Looking for all candidate values for the implicit argument in the current scope that match the required type and name.
3. From these, selecting the best unique candidate based on type specificity.

If there is no unique best candidate the compiler rejects the call as ambiguous.

If a callee takes several implicit parameters, either all implicit arguments must be omitted, or all explicit and implicit arguments must be provided at the call site, in their declared order.

Resolution order

The compiler searches for implicit arguments in the following order, stopping at the first tier that produces a unique match:

1. Direct: values whose type directly matches:
   1. Local values in the current scope.
   2. Module fields of modules in scope (e.g., Nat.compare).
   3. Fields of unimported modules (requires --implicit-package).
2. Derived: functions with implicit parameters that, after stripping their own implicits and instantiating type parameters, match the required type (see Implicit derivation below):
   1. Local values in the current scope.
   2. Module fields (e.g., Array.compare<T>).
   3. Fields of unimported modules (requires --implicit-package).
3. Structural: structural combiners (__record, __tuple convention) applied to record or tuple types (see Structural derivation below):
   1. Local values in the current scope.
   2. Module fields.
   3. Fields of unimported modules (requires --implicit-package).

Within each tier, if multiple candidates match, the compiler picks the most specific one (by subtyping). If no unique best candidate exists, the call is rejected as ambiguous.

This ordering guarantees that direct matches are always preferred over derived ones, and local definitions take precedence over imported or unimported module definitions.

Implicit derivation

When no direct match exists, the compiler can derive an implicit argument from a function that itself has implicit parameters. This eliminates the need for boilerplate wrapper functions. The candidate function can be polymorphic (the compiler infers the type instantiation) or monomorphic.

For example, suppose Array.compare is declared as:

public func compare<T>(a : [T], b : [T], compare : (implicit : (T, T) -> Order)) : Order

and a function requires an implicit compare : ([Nat], [Nat]) -> Order. Without derivation, you would need to write a wrapper:

module MyArray {
  public func compare(a : [Nat], b : [Nat]) : Order {
    Array.compare(a, b) // resolves inner `compare` to Nat.compare
  };
};

With derivation, the compiler handles this automatically. It recognizes that Array.compare<Nat>, after removing its implicit compare parameter and instantiating T := Nat, has the right type. It then recursively resolves the inner implicit (Nat.compare) and synthesizes the wrapper for you.

This works transitively: a compare for [[Nat]] is derived via Array.compare<[Nat]>, which needs [Nat] compare, which is derived via Array.compare<Nat>, which needs Nat.compare, all resolved automatically.

The resolution depth is bounded to guarantee termination. If you encounter a depth limit, you can increase it with --implicit-derivation-depth or provide the argument explicitly.

When derivation is attempted but fails (for example, because an inner implicit can’t be resolved), the compiler reports which inner implicits were missing and, when applicable, a hint about which module to import.

Structural derivation

When an implicit is needed for a record or tuple type, the compiler can synthesize it automatically using a structural combiner: a function whose single parameter name begins with __ and encodes the structural decomposition kind. Structural combiners must not have implicit parameters.

Two structural kinds are supported, distinguished by the combiner’s parameter name:

Parameter name	Combiner type	Implicit argument type	Description
__record	[(Text, () -> E)] -> R	Rec -> R or (Rec, Rec) -> R	Record: one or two records, arity from implicit
__tuple	[() -> E] -> R	(A, B, ...) -> R or ((A,B,...), (A,B,...)) -> R (≥ 2 elements)	Tuple: one implicit per element
__variant	:	:	Reserved for future extension

Each per-field/element result is wrapped in a thunk (() -> E), giving the combiner full control over evaluation order. Combiners that need all values (like serialization) simply call every thunk. Combiners that can short-circuit (like comparison) can stop early: remaining thunks are never evaluated.

The search label used to resolve per-element implicits is the same as the implicit parameter name at the call site.

Caution

Motoko has no type abstraction (no newtypes or private types), so a named type that expands to a record: including stdlib containers like Map, Set, or Buffer: is structurally indistinguishable from a plain data record and may be decomposed into its internal fields by structural derivation; provide a dedicated instance (e.g. MapJson) to take precedence over structural synthesis for such types.

Unary record derivation (__record)

When the compiler is looking for an implicit of type SomeRecord -> R and finds a unique structural combiner for R (parameter named __record, type [(Text, () -> E)] -> R), it:

1. Decomposes SomeRecord into its fields (in lexicographic order).
2. For each field name : FieldType, resolves a per-field implicit of type FieldType -> E using the same search label.
3. Synthesises a wrapper: func($r) { combiner([("f1", func() { inst1($r.f1) }), ...]) }.

This makes it possible for a library to provide generic serialization for any record type as long as instances exist for all field types.

Example: JSON serialization

Suppose a Json package defines a type, a structural combiner, and an entry point:

public type Json = { #number : Int; #text : Text; #obj : [(Text, Json)]; /* ... */ };

// Structural combiner — __record parameter name triggers record-level synthesis.
// Each field is a thunk; serialization evaluates all of them.
public func encode(__record : [(Text, () -> Json)]) : Json =
  #obj(__record.map(func((k, v)) = (k, v())));

// Entry point using contextual dot notation
public func toJson<R>(self : R, encode : (implicit : R -> Json)) : Json = encode(self);

And per-type instances in companion modules:

IntJson.mo

public func encode(self : Int) : Json = #number self;

Any record whose fields all have an encode instance can now be serialised with no boilerplate:

import Json "mo:json/Json";
import IntJson "mo:json/IntJson";
import TextJson "mo:json/TextJson";

type Person = { name : Text; age : Int };

let p : Person = { name = "Alice"; age = 30 };
let json = p.toJson();
// Result: #obj([("name", #text "Alice"), ("age", #number 30)])

The compiler finds Json.encode(__record) as the unique structural combiner for Json, resolves per-field encode instances from TextJson and IntJson, and synthesizes the wrapper automatically.

Binary record derivation

When the compiler is looking for an implicit of type (Rec, Rec) -> R where Rec is a record type and both arguments have the same type, it searches for a __record combiner for R: the same combiner that handles the unary case. The arity is determined entirely by the implicit argument’s type; the combiner itself is unaware of it.

The compiler synthesizes a binary wrapper:

func($r1, $r2) { combiner([("f1", func() { inst1($r1.f1, $r2.f1) }), ...]) }

Each per-field implicit has type (FieldType, FieldType) -> E, resolved recursively with the same search label. This allows binary operations like comparison or equality to be derived field-by-field from a single __record combiner.

Example: lexicographic comparison

import Array "mo:core/Array";
import Nat "mo:core/Nat";
import Text "mo:core/Text";
import Order "mo:core/Order";

// __record combiner: fold field-wise Order values, short-circuiting at first non-equal.
// Thunks enable genuine short-circuiting — remaining fields are never evaluated.
func compare(__record : [(Text, () -> Order.Order)]) : Order.Order {
  for ((_, ordThunk) in __record.vals()) {
    let ord = ordThunk();
    if (ord != #equal) return ord
  };
  #equal
};

type Person = { name : Text; age : Nat };

// Array.sort uses (implicit : (T, T) -> Order.Order) — derived from __record (binary path).
// Fields resolved: age → Nat.compare, name → Text.compare (lexicographic order).
let people : [Person] = [{ name = "Carol"; age = 30 }, { name = "Bob"; age = 25 }];
let sorted = people.sort();
// sorted[0] = { name = "Bob"; age = 25 }  (age 25 < 30)

Nested record types are handled automatically: a Team with a Person field will derive compare for Team by first deriving compare for Person at depth+1.

Tuple derivation (__tuple)

When the compiler is looking for an implicit of type (A, B, ...) -> R (a tuple domain with at least two elements), it searches for a structural combiner whose parameter is named __tuple and has type [() -> E] -> R.

When found, the compiler synthesizes a wrapper:

func($t) { combiner([func() { inst0($t.0) }, func() { inst1($t.1) }, ...]) }

Each per-element implicit has type ElemType_i -> E, resolved positionally using the same search label.

Binary tuple derivation

Like __record, the __tuple combiner also supports binary implicit arguments. When the implicit argument has type ((A, B, ...), (A, B, ...)) -> R (two arguments of the same tuple type with ≥ 2 elements), the compiler synthesizes a binary wrapper:

func($t1, $t2) { combiner([func() { inst0($t1.0, $t2.0) }, func() { inst1($t1.1, $t2.1) }, ...]) }

Each per-element implicit has type (ElemType_i, ElemType_i) -> E. This enables element-wise binary operations like comparison or equality over tuples.

Example: tuple description

// __tuple combiner: join per-element descriptions (evaluates all thunks)
func describe(__tuple : [() -> Text]) : Text {
  var s = "("; var first = true;
  for (t in __tuple.vals()) {
    if (not first) { s #= ", " };
    s #= t(); first := false
  };
  s #= ")"; s
};

module TextDesc { public func describe(self : Text) : Text = self };
module NatDesc  { public func describe(self : Nat)  : Text = debug_show self };

func inspect<T>(x : T, describe : (implicit : T -> Text)) : Text = describe(x);

assert inspect(("hello", 42 : Nat)) == "(hello, 42)";

Disambiguation: binary vs unary when both __record and __tuple are in scope

Having __record and __tuple combiners in scope simultaneously is safe: the compiler picks the right path by inspecting the number of arguments in the implicit argument’s function type. The dispatch depends on where the tuple appears in the source, not on what the type expands to:

• implicit : (X, X) -> T: the inline tuple (X, X) is flattened into two separate args. The compiler sees a two-argument function, checks that both args are the same type, and uses the binary path: __record if X is a record type, __tuple if X is a tuple type (≥ 2 elements).
• implicit : P -> T where P is a type alias for (A, B, ...): P is not a tuple in the source, so it stays as a single arg. The compiler sees a one-argument function, promotes P to a tuple, and uses the __tuple combiner (unary path).

In practice: write (X, X) -> T directly as two args to trigger the binary path. Going through a type alias type Pair = (R, R) and writing Pair -> T will route to __tuple (unary) instead.

Supported types

The core library provides comparison functions for common types:

• Nat.compare for Nat
• Int.compare for Int
• Text.compare for Text
• Char.compare for Char
• Bool.compare for Bool
• Principal.compare for Principal
• etc.

Other implicit parameters declared by the core library are equals : (implicit : (T, T) -> Bool) and toText: (implicit : T -> Text).

Explicitly providing implicit arguments

You can always provide implicit arguments explicitly when needed:

import Map "mo:core/Map";
import Nat "mo:core/Nat";
import {type Order} "mo:core/Order";

// Custom comparison function for reverse ordering
func reverseCompare(a : Nat, b : Nat) : Order {
  Nat.compare(b, a)
};

let reversedMap = Map.empty<Nat, Text>();
// Explicitly provide the comparison function
reversedMap.add(reverseCompare, 5, "five");
reversedMap.add(reverseCompare, 3, "three");

This is useful when:

• Using custom comparison logic
• Working with custom types that have multiple possible orderings
• Improving code clarity in complex scenarios

Custom types

To use implicit arguments with your own custom types, define a comparison function:

import Map "mo:core/Map";
import Text "mo:core/Text";
import {type Order} "mo:core/Order";

type Person = {
  name : Text;
  age : Nat;
};

module Person {
  public func compare(a : Person, b : Person) : Order {
    Text.compare(a.name, b.name)
  };
};

// Now works with implicits
let directory = Map.empty<Person, Text>();
directory.add({ name = "Alice"; age = 30 }, "alice@example.com");
directory.add({ name = "Bob"; age = 25 }, "bob@example.com");

let email = directory.get({ name = "Alice"; age = 30 });

Best practices

1. Use implicits for standard types: When working with Nat, Text, Int, Principal, and other primitive types, let the compiler infer the comparison function.

2. Be explicit with custom logic: When using non-standard comparison logic, explicitly provide the comparison function for clarity.

3. Name comparison functions consistently: Follow the convention of ModuleName.compare to ensure proper inference.

4. Consider readability: While implicits reduce boilerplate, explicit arguments may be clearer in some contexts, especially when teaching or documenting code.

5. Collections benefit most: The repeated operations on Map and Set from core particularly benefit from implicit arguments since you call these functions frequently.

6. Don’t go wild with implicit parameters. Use them sparingly.

Migration from explicit arguments

Existing code with explicit comparison functions will continue to work. You can adopt implicit arguments gradually:

import Map "mo:core/Map";
import Nat "mo:core/Nat";

let data = Map.empty<Nat, Text>();

// Both styles work simultaneously
Map.add(data, Nat.compare, 1, "one");  // Explicit
Map.add(data, 2, "two");                // Implicit
Map.add(data, 3, "three");              // Implicit

There is no need to update existing code unless you want to take advantage of the cleaner syntax.

Performance considerations

Implicit arguments are resolved at compile time.

• For direct matches, the resulting code is identical to explicitly passing the argument.
• For derived implicits, the compiler synthesizes a wrapper function at each call site. This creates a small overhead per call site, which could be mitigated by caching in the future. For now, if this becomes a performance issue, consider defining the function explicitly so all call sites share a single definition.
• For __record structural derivation, the synthesized wrapper invokes one implicit per record field (two invocations per field for the binary path), so runtime cost scales linearly with record width. For __tuple, cost scales with tuple arity. For hot paths with wide types, consider writing the combiner explicitly.

See also

• Language reference