On this page

Labeled and Optional Function Arguments

Published on August 8, 2026

Enrico Hochkoeppler Profile

By Enrico Hochkoeppler

Web Developer & TutoriaLibre Founder

Ordinary positional arguments identify themselves purely by where they sit in a function call, which works fine until a function takes several arguments of the same type and a reader has no way to tell, just by looking at a call site, which one means what. Labeled arguments solve this by attaching a name to an argument that travels with it regardless of position; optional arguments build on labels further, letting an argument be skipped entirely in favor of a default value.

The Problem Labels Solve​

Consider a function whose type alone gives no hint about what its arguments mean:


# String.sub;;

- : string -> int -> int -> string

Nothing in string -> int -> int -> string reveals whether the first int is a starting position or a length, or what the second one is — the type alone forces a reader to go check documentation just to make a correct call. A labeled version of the same idea makes the call site self-explanatory:


let substring ~pos ~len s = String.sub s pos len

# substring ~pos:2 ~len:3 "hello world";;

- : string = "llo"

Labeled Argument Syntax​

A labeled parameter is written with a leading ~ in a function's definition, and supplied at the call site the same way:


let f ~name1 ~name2 = name1 + name2

# f ~name2:3 ~name1:4;;

- : int = 7

Labeled arguments can be supplied in any order, since the label — not position — is what determines which parameter each one fills. When the argument's name at the call site already matches its label, the value can be written just as ~name instead of the more verbose ~name:name, a shorthand called punning:


let pos = 2 and len = 3 in

substring ~pos ~len "hello world"

A labeled parameter can also be given an explicit type annotation, or bound to a locally different name than its label, by writing the label followed by a colon and a parenthesized pattern:


let f ~name1:(arg1 : int) ~name2:(arg2 : int) = arg1 + arg2

Optional Arguments: Labels With a Default​

An optional argument uses ? instead of ~, paired with a default value supplied directly in the function's definition:


let bump ?(step = 1) x = x + step

# bump 5;;

- : int = 6

# bump ~step:10 5;;

- : int = 15

Calling bump without ~step uses the default of 1; supplying ~step:10 overrides it. The type of an optional argument reflects this directly, prefixing the label with ? rather than ~:


# bump;;

- : ?step:int -> int -> int = <fun>

Optional Arguments Without a Default: Exposed as option​

Leaving off the = default part turns the argument into a genuine option, directly inspectable inside the function body, which is useful whenever "was this argument supplied at all" needs to change behavior rather than just filling in a fallback number:


let greet ?greeting name =

  match greeting with

  | None -> "Hello, " ^ name

  | Some g -> g ^ ", " ^ name

# greet "Ada";;

- : string = "Hello, Ada"

# greet ~greeting:"Welcome" "Ada";;

- : string = "Welcome, Ada"

A Real Gotcha: Optional Arguments Need a Trailing Required Argument​

OCaml decides an optional argument was omitted by watching for the moment a non-labeled (or otherwise required) argument gets applied — that's the trigger that resolves every optional argument coming before it, filling in defaults for any that weren't supplied. This has a genuinely surprising consequence: a function whose optional arguments are the last ones in its parameter list may never actually resolve those defaults, because nothing ever comes after them to trigger the resolution.


let concat ?(sep = "") a b = a ^ sep ^ b

# concat "foo" "bar";;

- : string = "foobar"

This works fine, because b, a required argument, comes after the optional sep, triggering default resolution. Reordering the same idea so the optional argument comes last removes that trigger:


let concat_warn a b ?(sep = "") () = a ^ sep ^ b

Here, an extra unit parameter had to be added after sep specifically to give OCaml something required to trigger on — without it, applying concat_warn "foo" "bar" wouldn't produce a string at all, it would produce a still-waiting function of type ?sep:string -> string, since nothing forced the optional argument to resolve yet. This is precisely why library functions that take an optional argument as their last parameter conventionally end with a trailing () — it's not decorative, it's what makes the default value actually resolve at the point the function is meant to be considered fully applied.

Relaying an Optional Argument Without Unwrapping It​

A wrapper function that simply forwards an optional argument to another function underneath doesn't need to unwrap and rewrap it manually. Prefixing the argument with ? at the call site passes it through exactly as received — present or absent — without forcing a default to resolve along the way:


let open_window ?width ?height () = (* ... *) ()



let open_application ?width ?height () =

  open_window ~title:"My Application" ?width ?height ()

Here, ?width and ?height in the call to open_window forward whatever open_application itself received for those same arguments — None stays None, Some v stays Some v — without open_application needing to pattern-match on either one just to relay them onward.

Labeled Arguments Don't Mix With |>​

A specific, easy-to-hit syntax error: a labeled argument on its own cannot sit directly to the left of |>, since |> expects a plain expression, not a bare label-value pair.


# ~default:42 |> Option.value None;;

Error: Syntax error

The fix is to keep the labeled call as an ordinary function application and pipe the plain, unlabeled value into it instead:


# Some 10 |> Option.value ~default:42;;

- : int = 10

When Labels Genuinely Help, and When They're Unnecessary Ceremony​

Labels earn their place on functions with several parameters that share a type, or where a parameter's role isn't obvious from its type alone — exactly the situation String.sub illustrated at the start. They're far less useful on a short function with one or two arguments of clearly different, self-explanatory types, where adding labels mostly adds typing without adding clarity. Optional arguments are the right tool specifically for genuinely optional configuration — a function that behaves sensibly with a default in the common case, but occasionally needs to be overridden — rather than for arguments that are, in practice, always supplied deliberately at every call site; an argument that's always given a real value at every call is usually clearer left as an ordinary required parameter.

Key Takeaways​

Found this helpful? Share the knowledge...

... or support this project to keep it alive!

Buy Me a Coffee

Previous

Option/Result-Based Error Handling

Next

Custom Operators & Precedence Rules