Misc(3)

💖 Misc(3) — OCaml library 💖

Manual name: Misc(3). Library: OCaml library. Okay bestie, this is the miscellaneous toolbox — unstable, part of the compiler libs, and lowkey full of useful little gremlins. Let’s get into it. ✨

🌸 NAME 🌸

Misc - Miscellaneous useful types and functions

🧩 Module 🧩

Module Misc

📚 Documentation 📚

Module Misc
 : sig end

Miscellaneous useful types and functions

⚠️ Warning: this module is unstable and part of Compiler_libs .

🚨 Reporting fatal errors 🚨

• val fatal_error : string -> 'a — Raise the Fatal_error exception with the given string. Short king behavior. 💅
• val fatal_errorf : ('a, Format.formatter, unit, 'b) format4 -> 'a — Format the arguments according to the given format string and raise Fatal_error with the resulting string. Fancy formatting before the chaos. 🎀
• exception Fatal_error — yep, that’s the exception declaration, right there.

🧼 Exceptions and finalization 🧼

• val try_finally : ?always:(unit -> unit) -> ?exceptionally:(unit -> unit) -> (unit -> 'a) -> 'a — try_finally work ~always ~exceptionally is designed to run code in work that may fail with an exception, and it has two kind of cleanup routines: always, that must be run after any execution of the function (typically, freeing system resources), and exceptionally, that should be run only if work or always failed with an exception (typically, undoing user-visible state changes that would only make sense if the function completes correctly). It’s giving responsible main character energy. 🫶

Example from the page:

let objfile = outputprefix ^ ".cmo" in
let oc = open_out_bin objfile in
Misc.try_finally
  (fun () ->
     bytecode
     ++ Timings.(accumulate_time (Generate sourcefile))
         (Emitcode.to_file oc modulename objfile);
     Warnings.check_fatal ())
  ~always:(fun () -> close_out oc)
  ~exceptionally:(fun _exn -> remove_file objfile);

If exceptionally fail with an exception, it is propagated as usual.

If always or exceptionally use exceptions internally for control-flow but do not raise, then try_finally is careful to preserve any exception backtrace coming from work or always for easier debugging.

• val reraise_preserving_backtrace : exn -> (unit -> unit) -> 'a — reraise_preserving_backtrace e f is (f (); raise e) except that the current backtrace is preserved, even if f uses exceptions internally. Backtrace protection? We love to see it. 🔥

📋 List operations 📋

• val map_end : ('a -> 'b) -> 'a list -> 'b list -> 'b list — map_end f l t is map f l @ t , just more efficient. No cap.
• val rev_map_end : ('a -> 'b) -> 'a list -> 'b list -> 'b list — The page literally says: map_end f l t is map f (rev l) @ t , just more efficient. We are not fixing the wording, we are respecting the lore. 🦋
• val map_left_right : ('a -> 'b) -> 'a list -> 'b list — Like List.map , with guaranteed left-to-right evaluation order. Order matters, bestie. ✨
• val for_all2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool — Same as List.for_all but for a binary predicate. In addition, this for_all2 never fails: given two lists with different lengths, it returns false. No crashing, just honesty. 😭
• val replicate_list : 'a -> int -> 'a list — replicate_list elem n is the list with n elements all identical to elem . Copy-paste but make it functional. 🎀
• val list_remove : 'a -> 'a list -> 'a list — list_remove x l returns a copy of l with the first element equal to x removed. First match only, periodt. 💅
• val split_last : 'a list -> 'a list * 'a — Return the last element and the other elements of the given list. Last one out, plus the rest. 🫶
• val repeated_label : (string option * 'a) list -> string option — Detects a repeated label - for use with labeled tuples. Label detective behavior. 🔍

🗂️ Hash table operations 🗂️

• val create_hashtable : int -> ('a * 'b) list -> ('a, 'b) Hashtbl.t — Create a hashtable with the given initial size and fills it with the given bindings. Preloaded and ready. 🌈

🧱 Extensions to the standard library 🧱

• module Stdlib : sig end — module signature, that’s the whole entry. Mysterious but valid. 🎀

📁 Operations on files and file paths 📁

• val find_in_path : string list -> string -> string — Search a file in a list of directories.
• val find_in_path_rel : string list -> string -> string — Search a relative file in a list of directories.
• val normalized_unit_filename : string -> (string, string) Result.t — Normalize file name Foo.ml to foo.ml , using NFC and case-folding. Return Error if the input is not a valid utf-8 byte sequence. Normalization era. ✨
• val find_in_path_normalized : string list -> string -> string — Same as Misc.find_in_path_rel , but search also for normalized unit filename, i.e. if name is Foo.ml , allow /path/Foo.ml and /path/foo.ml to match. Case-folding said “both can stay.” 💅
• val remove_file : string -> unit — Delete the given file if it exists and is a regular file. Does nothing for other kinds of files. Never raises an error. No drama, no exceptions. 🫶
• val expand_directory : string -> string -> string — expand_directory alt file eventually expands a + at the beginning of file into alt (an alternate root directory). Plus sign glow-up. ⭐
• val split_path_contents : ?sep:char -> string -> string list — split_path_contents ?sep s interprets s as the value of a "PATH"-like variable and returns the corresponding list of directories. s is split using the platform-specific delimiter, or ~sep if it is passed. Returns the empty list if s is empty. PATH vibes, parsed. 🦋
• val copy_file : in_channel -> out_channel -> unit — copy_file ic oc reads the contents of file ic and copies them to oc . It stops when encountering EOF on ic . Copy until EOF, no cap. 🎀
• val copy_file_chunk : in_channel -> out_channel -> int -> unit — copy_file_chunk ic oc n reads n bytes from ic and copies them to oc . It raises End_of_file when encountering EOF on ic . Chunked, and it will raise if the file ghosts you. 😭
• val string_of_file : in_channel -> string — string_of_file ic reads the contents of file ic and copies them to a string. It stops when encountering EOF on ic . File to string, iconic. 💜
• val output_to_file_via_temporary : ?mode:open_flag list -> string -> (string -> out_channel -> 'a) -> 'a — Produce output in temporary file, then rename it (as atomically as possible) to the desired output file name. output_to_file_via_temporary filename fn opens a temporary file which is passed to fn (name + output channel). When fn returns, the channel is closed and the temporary file is renamed to filename . Temporary era, then atomic-ish rename. 🔥
• val protect_writing_to_file : filename:string -> f:(out_channel -> 'a) -> 'a — Open the given filename for writing (in binary mode), pass the out_channel to the given function, then close the channel. If the function raises an exception then filename will be removed. Cleanup on failure? We stan. 🫶
• val concat_null_terminated : string list -> string — concat_null_terminated [x1;x2; ... xn] is x1 ^ "\000" ^ x2 ^ "\000" ^ ... ^ xn ^ "\000". Null-terminated join, exactly like that. ✨
• val split_null_terminated : string -> string list — split_null_terminated s is similar String.split_on_char '\000' but ignores the trailing separator, if any. Trailing separator? Ignored. 🎀
• val chop_extensions : string -> string — Return the given file name without its extensions. The extensions is the longest suffix starting with a period and not including a directory separator, .xyz.uvw for instance. Return the given name if it does not contain an extension. Extensions chopped, name preserved. 💅

🔢 Integer operations 🔢

• val log2 : int -> int — log2 n returns s such that n = 1 lsl s if n is a power of 2. Power-of-two detective. 🔍
• val align : int -> int -> int — align n a rounds n upwards to a multiple of a (a power of 2). Round up, bestie. ⭐
• val no_overflow_add : int -> int -> bool — no_overflow_add n1 n2 returns true if the computation of n1 + n2 does not overflow. Overflow check, no surprises. 🎀
• val no_overflow_sub : int -> int -> bool — no_overflow_sub n1 n2 returns true if the computation of n1 - n2 does not overflow. Subtraction safety check. 🦋
• val no_overflow_mul : int -> int -> bool — no_overflow_mul n1 n2 returns true if the computation of n1 * n2 does not overflow. Multiplication, but keep it contained. 💅
• val no_overflow_lsl : int -> int -> bool — no_overflow_lsl n k returns true if the computation of n lsl k does not overflow. Shift left with a vibe check. 🌈
• val letter_of_int : int -> string — signature only on this page, bestie. No extra lore here. 🎀
• module Int_literal_converter : sig end — module signature, that’s it. Mysterious module energy. ✨
• val find_first_mono : (int -> bool) -> int — find_first_mono p takes an integer predicate p : int -> bool that we assume:
  1. is monotonic on natural numbers: if a <= b then p a implies p b ,
  2. is satisfied for some natural numbers in range 0; max_int (this is equivalent to: p max_int = true ).

find_first_mono p is the smallest natural number N that satisfies p , computed in O(log(N)) calls to p .

Our implementation supports two cases where the preconditions on p are not respected:

-If p is always false , we silently return max_int instead of looping or crashing.

-If p is non-monotonic but eventually true, we return some satisfying value.

🔤 String operations 🔤

• val search_substring : string -> string -> int -> int — search_substring pat str start returns the position of the first occurrence of string pat in string str . Search starts at offset start in str . Raise Not_found if pat does not occur. Search era, with a Not_found cliffhanger. 😭
• val replace_substring : before:string -> after:string -> string -> string — replace_substring ~before ~after str replaces all occurrences of before with after in str and returns the resulting string. Global replace, no crumbs. 💅
• val rev_split_words : string -> string list — rev_split_words s splits s in blank-separated words, and returns the list of words in reverse order. Words, but backwards. 🦋
• val cut_at : string -> char -> string * string — cut_at s c returns a pair containing the sub-string before the first occurrence of c in s , and the sub-string after the first occurrence of c in s .

let (before, after) = String.cut_at s c in
    before ^ String.make 1 c ^ after

is the identity if s contains c .

Raise Not_found if the character does not appear in the string.

Since 4.01

• val ordinal_suffix : int -> string — ordinal_suffix n is the appropriate suffix to append to the numeral n as an ordinal number: 1 -> "st" , 2 -> "nd" , 3 -> "rd" , 4 -> "th" , and so on. Handles larger numbers (e.g., 42 -> "nd" ) and the numbers 11--13 (which all get "th" ) correctly. Ordinal grammar ate. 🎀
• val normalise_eol : string -> string — normalise_eol s returns a fresh copy of s with any '\r' characters removed. Intended for pre-processing text which will subsequently be printed on a channel which performs EOL transformations (i.e. Windows). Windows preprocessing realness. 🫶
• val delete_eol_spaces : string -> string — delete_eol_spaces s returns a fresh copy of s with any end of line spaces removed. Intended to normalize the output of the toplevel for tests. Test-output cleanup behavior. ✨

🔗 Operations on references 🔗

type ref_and_value =
 | R : 'a ref * 'a -> ref_and_value

• val protect_refs : ref_and_value list -> (unit -> 'a) -> 'a — protect_refs l f temporarily sets r to v for each R (r, v) in l while executing f . The previous contents of the references is restored even if f raises an exception, without altering the exception backtrace. Reference protection with backtrace respect. 💅
• val get_ref : 'a list ref -> 'a list — get_ref lr returns the content of the list reference lr and reset its content to the empty list. Read it, then reset it. 🦋
• val set_or_ignore : ('a -> 'b option) -> 'b option ref -> 'a -> unit — set_or_ignore f opt x sets opt to f x if it returns Some _ , or leaves it unmodified if it returns None . Set only if there’s a Some, bestie. 🎀

🎁 Operations on triples and quadruples 🎁

• val fst3 : 'a * 'b * 'c -> 'a — first of three. Accessor.
• val snd3 : 'a * 'b * 'c -> 'b — second of three. Accessor.
• val thd3 : 'a * 'b * 'c -> 'c — third of three. Accessor.
• val fst4 : 'a * 'b * 'c * 'd -> 'a — first of four. Accessor.
• val snd4 : 'a * 'b * 'c * 'd -> 'b — second of four. Accessor.
• val thd4 : 'a * 'b * 'c * 'd -> 'c — third of four. Accessor.
• val for4 : 'a * 'b * 'c * 'd -> 'd — fourth of four. Yes, it’s named for4, and yes, that’s iconic. 🌈

✨ Spell checking and “did you mean” suggestions ✨

• val edit_distance : string -> string -> int -> int option — okay so edit_distance a b cutoff computes the edit distance between strings a and b. To help efficiency, it uses a cutoff: if the distance d is smaller than cutoff, it returns Some d, else None. The distance algorithm currently used is Damerau-Levenshtein: it computes the number of insertion, deletion, substitution of letters, or swapping of adjacent letters to go from one word to the other. The particular algorithm may change in the future. 👀
• val spellcheck : string list -> string -> string list — spellcheck env name takes a list of names env that exist in the current environment and an erroneous name, and returns a list of suggestions taken from env, that are close enough to name that it may be a typo for one of them. Bestie, it's giving “did you mean” energy fr fr. 💅
• val align_hint : prefix:string -> main:Format_doc.t -> hint:Format_doc.t -> Format_doc.t * Format_doc.t — aligned_hint main hint vertically aligns a main message and a hint message. The vertical alignment is controlled by the use of @{<ralign> ... @} boxes: the start of one box, in either the hint or the main message, will be shifted on the left to ensure that the end of the two boxes are vertically aligned, taking in account a pre-existing prefix before the main message. For instance:

let main, sub =
  align_hint
    ~prefix:"Error: "
    (doc_printf "@{<ralign>The value @}%a is not an instance variable"
      Style.inline_code "foobar"
    )
    (doc_printf
      "@{<ralign>Did you mean @}%a" Style.inline_code "foobaz"
    ) in
   printf "Error: %a%a" pp_doc main pp_doc sub

produces the following text:

Error:   The value "foobaz" is not an instance variable
Hint: Did you mean "foobar"?

where the main message has been shifted to the left to align "foobaz" and "foobar". ✨

• val align_error_hint : main:Format_doc.t -> hint:Format_doc.t -> Format_doc.t * Format_doc.t — Same as align_hint ~prefix:"Error: ". That's it, that's the whole vibe. 🎀
• val aligned_hint : prefix:string -> Format_doc.formatter -> ('a, Format_doc.formatter, unit, Format_doc.t option -> unit) format4 -> 'a — aligned_hint ~prefix fmt ... hint align the potential hint with the main error message generated by the format string fmt before printing the two message. 🫶
• val did_you_mean : ?pp:string Format_doc.printer -> string list -> Format_doc.t option — did_you_mean ~pp choices hints that the user may have meant one of the option in choices. Each choice is printed with the pp function, or Style.inline_code if pp = None. 🦋
• module Color : sig end — listed right here, exactly as module Color : sig end. No extra docs attached, no cap. 💜

---

🌈 Color support detection

Color support detection is a whole heading, bestie. It's giving “we detect color support” main character energy. 🌸

💅 Styling handling for terminal output

• module Style : sig end — the Style module is listed exactly as module Style : sig end. Iconic. 👑
• module Error_style : sig end — and Error_style is listed exactly as module Error_style : sig end. Periodt. 💅

---

🖨️ Formatted output

• val print_if : Format.formatter -> bool ref -> (Format.formatter -> 'a -> unit) -> 'a -> 'a — print_if ppf flag fmt x prints x with fmt on ppf if b is true. That's the whole note, fr fr. ✨
• val print_see_manual : int list Format_doc.printer — See manual section. Literally that. 🎀

---

⚙️ Displaying configuration variables

• val show_config_and_exit : unit -> unit — Display the values of all compiler configuration variables from module Config, then exit the program with code 0. Slay, then dip. 💅
• val show_config_variable_and_exit : string -> unit — Display the value of the given configuration variable, then exit the program with code 0. Same energy, one variable at a time. ✨

---

🗺️ Handling of build maps

Build maps cause the compiler to normalize file names embedded in object files, thus leading to more reproducible builds. Reproducible builds are so valid. 🫶

• val get_build_path_prefix_map : unit -> Build_path_prefix_map.map option — Returns the map encoded in the BUILD_PATH_PREFIX_MAP environment variable. 🦋
• val invert_build_path_prefix_map : string -> string list — Returns the potential paths (in priority order) from which the given path can originate from before rewrite using BUILD_PATH_PREFIX_MAP environment variable. 🌈
• val debug_prefix_map_flags : unit -> string list — Returns the list of --debug-prefix-map flags to be passed to the assembler, built from the BUILD_PATH_PREFIX_MAP environment variable. 🔥

---

🔮 Handling of magic numbers

• module Magic_number : sig end — yes bestie, Magic_number is listed exactly as module Magic_number : sig end. Mysterious, iconic, no further notes. ✨

---

🌈 Minimal support for Unicode characters in identifiers

Characters allowed in identifiers are, currently:

• -ASCII letters A-Z a-z
• -Latin-1 letters (U+00C0 - U+00FF except U+00D7 and U+00F7)
• -Character sequences which normalize to the above character under NFC
• -digits 0-9, underscore, single quote
• module Utf8_lexeme : sig end — listed exactly as module Utf8_lexeme : sig end. 💜
• module RuntimeID : sig end — listed exactly as module RuntimeID : sig end. 🎀

---

🏷️ Miscellaneous type aliases

• type filepath = string — a filepath is a string, no cap. 🦋
• type modname = string — a modname is a string, periodt. ✨
• type crcs = (modname * Digest.BLAKE128.t option) list — exactly this little list of modname paired with an optional Digest.BLAKE128.t. 💅
• type alerts = string Stdlib.String.Map.t — alerts are a string Stdlib.String.Map.t, and that's the whole alias. 🌸

---

💖 That's the whole Misc(3) vibe, bestie — source/version is OCamldoc, dated 2026-06-22, and the page is Misc(3). Bye, love you, read your manpages! 🫶✨