What comes in the box
Every OCaml installation includes the standard library, Stdlib, whose modules (List, String, Printf, Hashtbl, Map and several dozen more) are available in every program without any setup. You have used much of it already. This lesson fills in the parts you will need for everyday programs: working with text, formatting output, lazy sequences and files.
The OCaml standard library has a particular character. It is deliberately conservative: small, stable, and careful about compatibility, so code written years ago still compiles. It has grown steadily through the 4.x and 5.x releases (Seq arrived in OCaml 4.07, String.starts_with in 4.13, In_channel and Out_channel in 4.14, Domain and Effect in 5.0), but it is still smaller than Python's or Java's. Many teams therefore add a richer library on top, and the end of this lesson says which and why.
A few tools to know by name
Definition— Quoted string literal
{|...|} is a string literal in which nothing is escaped: backslashes, double quotes and newlines are taken literally. {id|...|id} allows |} inside by choosing a delimiter. It is ideal for test data, regular expressions and embedded text.
Definition— Printf directives
In a format string, %d formats an int, %f a float, %s a string, %S a string as an OCaml literal (with quotes and escapes), %b a bool and %c a char. A number between % and the letter sets a minimum width (%5d), a minus sign aligns left (%-10s), and .n sets the precision (%.2f). The compiler checks every directive against its argument.
Definition— Seq
A value of type 'a Seq.t is a lazy sequence: a function that, when called, produces the next element and the rest of the sequence, or says the sequence has ended. Elements are computed only when consumed, so a sequence can be infinite.
Definition— Channels
An in_channel or out_channel is an open file (or standard input/output) for reading or writing. The modules In_channel and Out_channel (OCaml 4.14) provide functions such as with_open_text, which opens a file, passes the channel to your function and closes it afterwards, even if an exception is raised.
Text, sequences, formatting and files
Parsing and reporting text
let data = {|item,qty,price
rice,3,2.50
beans,10,1.20
mangoes,6,0.75
tea,one,4.00
salt,2,0.40|}
type row = { name : string; qty : int; price : float }
let parse_row line =
match String.split_on_char ',' line with
| [ name; qty; price ] -> (
match (int_of_string_opt qty, float_of_string_opt price) with
| Some qty, Some price -> Ok { name; qty; price }
| _ -> Error (Printf.sprintf "bad numbers in %S" line))
| _ -> Error (Printf.sprintf "expected 3 fields in %S" line)
let () =
let lines = String.split_on_char '\n' data |> List.map String.trim |> List.filter (( <> ) "") in
let rows = match lines with [] -> [] | _header :: rest -> List.map parse_row rest in
let good = List.filter_map Result.to_option rows in
List.iter (function Error e -> print_endline ("skipped: " ^ e) | Ok _ -> ()) rows;
Printf.printf "%-10s %4s %8s\n" "item" "qty" "total";
List.iter (fun r -> Printf.printf "%-10s %4d %8.2f\n" r.name r.qty (float_of_int r.qty *. r.price)) good;
let total = List.fold_left (fun acc r -> acc +. (float_of_int r.qty *. r.price)) 0. good in
Printf.printf "%-10s %4s %8.2f\n" "TOTAL" "" total;
(* A few more String functions *)
let s = " Zanzibar spice market " in
let t = String.trim s in
Printf.printf "%b %b %s\n" (String.starts_with ~prefix:"Zan" t) (String.ends_with ~suffix:"x" t)
(String.concat "|" (String.split_on_char ' ' t));
Printf.printf "%s %s %d\n" (String.sub t 0 8) (String.capitalize_ascii "dar es salaam")
(Option.value ~default:(-1) (String.index_opt t 's'))skipped: bad numbers in "tea,one,4.00"
item qty total
rice 3 7.50
beans 10 12.00
mangoes 6 4.50
salt 2 0.80
TOTAL 24.80
true false Zanzibar|spice|market
Zanzibar Dar es salaam 9This little report is the shape of a great deal of real code: split text into lines, skip blanks and the header, parse each row into a record or an error, report the errors, and print the rest as an aligned table.
{|...|}holds the data with its newlines, without any escaping.- Each row becomes a
result, andList.filter_map Result.to_optionkeeps the good ones; the bad ones are reported, not silently dropped. %Sprints a string as an OCaml literal, with quotes, which makes empty strings and stray spaces visible in error messages. A small habit that saves debugging time.%-10spads a string to ten characters, aligned left;%4dand%8.2fpad numbers to the right. That is all you need for neat tables.String.starts_with ~prefixandString.ends_with ~suffix(OCaml 4.13) have labelled arguments, so you cannot mix up which string is which.
Remember from lesson 2 that these functions work on bytes. They are correct for UTF-8 text when you split or search on ASCII characters such as commas, spaces and newlines, which is the usual case; for counting or slicing characters in other scripts, use String.get_utf_8_uchar or a Unicode library.
Lazy sequences and composable printers
(* Seq: lazy sequences, computed on demand. *)
let is_prime n =
n >= 2 && Seq.ints 2 |> Seq.take_while (fun d -> d * d <= n) |> Seq.for_all (fun d -> n mod d <> 0)
let fibs = Seq.unfold (fun (a, b) -> Some (a, (b, a + b))) (0, 1)
let show_ints s = String.concat " " (List.map string_of_int (List.of_seq s))
(* Format: printers that compose with %a. *)
type point = { x : float; y : float }
let pp_point ppf p = Format.fprintf ppf "(%.1f, %.1f)" p.x p.y
let pp_points =
Format.pp_print_list ~pp_sep:(fun ppf () -> Format.pp_print_string ppf "; ") pp_point
let () =
print_endline (show_ints (Seq.ints 1 |> Seq.filter is_prime |> Seq.take 10));
print_endline (show_ints (Seq.take 12 fibs));
print_endline (show_ints (Seq.iterate (fun x -> x * 3) 1 |> Seq.take_while (fun x -> x < 1000)));
print_endline (String.to_seq "harambee" |> Seq.map Char.uppercase_ascii |> String.of_seq);
let a = { x = 1.; y = 2.5 } and b = { x = -3.; y = 0. } in
Format.printf "A = %a, B = %a@." pp_point a pp_point b;
let s = Format.asprintf "[%a]" pp_points [ a; b; { x = 0.5; y = 0.5 } ] in
print_endline s;
Printf.printf "%d characters\n" (String.length s)2 3 5 7 11 13 17 19 23 29
0 1 1 2 3 5 8 13 21 34 55 89
1 3 9 27 81 243 729
HARAMBEE
A = (1.0, 2.5), B = (-3.0, 0.0)
[(1.0, 2.5); (-3.0, 0.0); (0.5, 0.5)]
37 charactersSeq.ints 1 is the infinite sequence 1, 2, 3, and so on; filtering it and taking ten elements computes only as much as needed. Seq.unfold builds a sequence from a state (here the pair of the last two Fibonacci numbers) and a function giving the next element and the next state. Seq.iterate f x is x, f x, f (f x), .... Strings, lists, arrays, maps and hash tables all convert to and from sequences (String.to_seq, List.of_seq, Hashtbl.to_seq and so on), which makes Seq the common currency between collections. OCaml is strict, so laziness here is explicit: you get it exactly where you ask for it, through the Seq type.
Format is the more powerful sibling of Printf. A printer is a function taking a formatter (conventionally ppf) and a value. The %a directive takes two arguments, a printer and a value, so printers for small types compose into printers for larger ones: pp_print_list turns pp_point into a printer for lists of points. @. ends the line and flushes the output. Format.asprintf prints into a string instead. Libraries conventionally export a pp function for each of their types, and the ppx_deriving preprocessor can generate them for you.
Files
(* Writing and reading a file with Out_channel and In_channel (OCaml 4.14 and later). *)
let () =
let path = Filename.temp_file "harvest" ".txt" in
Out_channel.with_open_text path (fun oc ->
List.iter (fun (crop, tonnes) -> Printf.fprintf oc "%s %d\n" crop tonnes)
[ ("maize", 120); ("cassava", 340); ("sorghum", 95) ]);
let lines = In_channel.with_open_text path In_channel.input_lines in
Printf.printf "%d lines\n" (List.length lines);
let parsed =
List.filter_map (fun line -> Scanf.sscanf_opt line "%s %d" (fun crop t -> (crop, t))) lines
in
List.iter (fun (crop, t) -> Printf.printf "%-8s %4d\n" crop t) parsed;
Printf.printf "total %d\n" (List.fold_left (fun acc (_, t) -> acc + t) 0 parsed);
let size = In_channel.with_open_bin path In_channel.length in
Printf.printf "%Ld bytes\n" size;
Sys.remove path;
Printf.printf "still there? %b\n" (Sys.file_exists path)3 lines
maize 120
cassava 340
sorghum 95
total 555
33 bytes
still there? falseFilename.temp_file creates a fresh file in the system's temporary directory. Out_channel.with_open_text path f opens the file, calls f with the channel, and closes it when f returns or raises: the same guarantee as Fun.protect from the previous lesson, packaged for files, so you never leak an open file handle. Printf.fprintf is printf to a channel.
Reading is symmetric. In_channel.input_lines (OCaml 5.1) reads all lines into a list; In_channel.input_all reads the whole file into one string; In_channel.input_line reads one line at a time, returning None at the end, which is how you process files too large to hold in memory. Scanf.sscanf_opt (OCaml 5.0) parses a string with a format, the inverse of sprintf, returning None if it does not match. In_channel.length returns an Int64.t, printed with %Ld.
Other everyday modules: Sys (command-line arguments in Sys.argv, environment variables with Sys.getenv_opt, files and directories), Filename (portable path manipulation), Random (pseudo-random numbers; call Random.self_init () for unpredictable values, or Random.init seed for reproducible ones), and Buffer and Bytes for efficient text and binary data.
Choosing a collection, and reading the documentation
With the whole course behind you, here is the standard library's set of containers side by side. Most "my program is slow" questions in OCaml are answered by moving from the wrong row of this table to the right one.
| Structure | Mutable? | Typical costs | Use it for |
|---|---|---|---|
list | no | :: constant; nth, length, @ linear | sequences built and consumed front to back |
array | yes | get and set constant; fixed length | indexed data, numeric work, tables |
Dynarray (OCaml 5.2) | yes | get and set constant; amortised constant add_last | an array that grows, like a vector in other languages |
Map.Make, Set.Make | no | lookup, add, remove logarithmic; sorted iteration | dictionaries and sets you share, keep old versions of, or iterate in order |
Hashtbl | yes | lookup, add, remove constant on average; unordered | large, local dictionaries where speed matters |
Queue, Stack | yes | push and pop constant | work lists, breadth-first and depth-first search |
Seq | no | each element computed when needed | streams, infinite or large sequences, conversions between containers |
Buffer | yes | amortised constant append | building long strings |
string / Bytes | no / yes | indexed access constant | text and binary data |
Three habits make the documentation at ocaml.org/api easy to use:
- Read the type first.
val find_opt : ('a -> bool) -> 'a list -> 'a optiontells you almost everything: a predicate, a list, and maybe an element. - Look for the
@sinceline. Every function says which OCaml version introduced it. If your project must build with an older compiler, this is how you know whether you can use, say,In_channel.input_lines(5.1). - Know the naming conventions.
_optversions return anoptioninstead of raising;_exn(in Base and Core) marks the raising versions; modules such asListLabelsandStdLabelsprovide the same functions with labelled arguments, for codebases that prefer them.
Beyond the standard library
Two libraries ship with the compiler but must be linked explicitly: unix (processes, sockets, file descriptors, time) and str (simple regular expressions). In a dune project you list them in a libraries field, as lesson 9 shows.
For anything bigger, teams choose from opam. Being honest about the landscape helps you read other people's code:
- Base and Core, from Jane Street, are complete alternative standard libraries, used throughout Real World OCaml and in many companies. They are consistent (every container has the same set of functions with the same labels), prefer
optionandOr_errorto exceptions, and add many data structures. The cost is a larger dependency and a different vocabulary from theStdlibyou have learned. Code that opensCoreat the top looks noticeably different:List.map l ~f:(fun x -> ...)with labelled arguments. - Containers extends the standard library instead of replacing it, keeping its naming and style.
- Specialised libraries cover the rest. Among the most used: yojson (JSON), re (regular expressions), cmdliner (command-line interfaces), ppx_deriving and ppx_sexp_conv (generated printers and serialisers), lwt and eio (concurrent I/O), cohttp and dream (HTTP), zarith (arbitrary-precision numbers), and sqlite3 and caqti (databases).
A practical rule: start with Stdlib, which is enough for a surprising amount, and add a library when it removes real code from your project. When you join a team, follow its choice; mixing Stdlib and Base styles in one codebase is a common source of friction.
Common misconceptions
Misconception
"OCaml can print any value, as the toplevel does." The toplevel prints values because it has their types at hand while you type. A compiled program has no general show function: types are erased at run time. You write printers (often with Format and %a) or generate them with ppx_deriving.
Misconception
"Seq is like a list, so I can traverse it twice for free." A sequence is a recipe for producing elements. Traversing it twice runs the recipe twice, which repeats any work (and repeats side effects, if the sequence reads from a file). If you need the elements more than once, convert it to a list or array with List.of_seq.
Misconception
"open_in and close_in are the way to read files." They still work, but forgetting close_in on an error path leaks a file handle. In_channel.with_open_text closes the file for you in every case, and is what modern code uses.
Misconception
"Whatever printf prints appears on the screen immediately." Standard output is buffered: text is collected and written in chunks, and is flushed when a newline is printed by print_endline, when the program exits normally, or when you ask. If a program prints a progress message and then crashes or blocks, the message may never appear. Add %! at the end of a format string (Printf.printf "loading...%!") or call flush stdout when timing matters, and write diagnostics to standard error with Printf.eprintf.
Misconception
"The standard library is too small for real work." It is smaller than some, but it covers collections, text, formatting, files, sequences, hashing, and since OCaml 5, parallelism and effects. Many tools and services are written with Stdlib plus a handful of focused libraries.
Exercises
1. The standard library in practice
Warm-upComputationalWhat does this program print?
let () = Printf.printf "[%5d][%-5d][%.3f]\n" 42 42 3.14159
2. The standard library in practice
CoreComputationalWhat does this program print?
let () = Printf.printf "%S|%s|%S\n" "say \"hi\"" "plain" ""
3. The standard library in practice
CoreComputationalWhat does this program print?
let () =
Seq.ints 10
|> Seq.filter (fun x -> x mod 7 = 0)
|> Seq.take 3
|> List.of_seq
|> List.map string_of_int
|> String.concat " "
|> print_endline
4. The standard library in practice
CoreComputationalWhat does this program print?
let () = Printf.printf "%d\n" (List.length (String.split_on_char ',' "a,,b,"))
5. The standard library in practice
CoreComputationalWhat does this program print?
let () =
Seq.unfold (fun p -> if p > 20 then None else Some (p, p * 2)) 1
|> Seq.fold_left ( + ) 0
|> Printf.printf "%d\n"
6. The standard library in practice
Warm-upHumanWhy is In_channel.with_open_text path f preferred over open_in path followed later by close_in?
7. The standard library in practice
CoreHumanWhich statement about Jane Street's Base and Core libraries is accurate?
Further reading and resources
- Standard library APIEvery module, with the version in which each function appeared.
- The String module
- The Seq moduleLazy sequences and the functions that build and consume them.
- The Format modulePretty-printing with boxes and break hints, and composable printers.
- The In_channel moduleReading files, added in OCaml 4.14.