- Courses
- 💻Programming Languages
- 🐫OCaml (WIP)
- Functional Design Idioms
- Labeled & Optional Parameters
On this page
Labeled and Optional Function Arguments
Published on August 8, 2026
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
- Labeled arguments (
~name) attach a name to a parameter that travels with it regardless of position, and can be supplied in any order at the call site;~namealone is shorthand when the local variable name matches the label. - Optional arguments (
?namewith a default via?(name = default)) can be omitted entirely, falling back to their default value; leaving off the default exposes the argument as a genuineoptioninstead. - An optional argument needs a required argument after it in the parameter list to trigger default resolution — a trailing
()is the conventional fix when an optional argument would otherwise be last. - Prefixing an argument with
?at a call site relays it exactly as received, without needing to manually unwrap and rewrap it just to forward it to another function. - A labeled argument cannot sit directly to the left of
|>; the labeled call needs to remain an ordinary function application instead. - Labels are most valuable for functions with several same-typed or non-obvious parameters; optional arguments are best reserved for genuinely optional configuration rather than values that are always supplied anyway.
Found this helpful? Share the knowledge...
... or support this project to keep it alive!
Previous
Option/Result-Based Error Handling
Next
Custom Operators & Precedence Rules
- The Problem Labels Solve
- Labeled Argument Syntax
- Optional Arguments: Labels With a Default
- Optional Arguments Without a Default: Exposed as option
- A Real Gotcha: Optional Arguments Need a Trailing Required Argument
- Relaying an Optional Argument Without Unwrapping It
- Labeled Arguments Don't Mix With |>
- When Labels Genuinely Help, and When They're Unnecessary Ceremony
- Key Takeaways
