mirror of
https://github.com/c-cube/tiny_httpd.git
synced 2026-01-22 01:06:41 -05:00
37 lines
46 KiB
HTML
37 lines
46 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Misc (ocaml.Misc)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 2.4.3"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../index.html">ocaml</a> » Misc</nav><header class="odoc-preamble"><h1>Module <code><span>Misc</span></code></h1><p>Miscellaneous useful types and functions</p><p><b>Warning:</b> this module is unstable and part of <span class="xref-unresolved" title="Compiler_libs">compiler-libs</span>.</p></header><nav class="odoc-toc"><ul><li><a href="#reporting-fatal-errors">Reporting fatal errors</a></li><li><a href="#exceptions-and-finalization">Exceptions and finalization</a></li><li><a href="#list-operations">List operations</a></li><li><a href="#hash-table-operations">Hash table operations</a></li><li><a href="#extensions-to-the-standard-library">Extensions to the standard library</a></li><li><a href="#operations-on-files-and-file-paths">Operations on files and file paths</a></li><li><a href="#integer-operations">Integer operations</a></li><li><a href="#string-operations">String operations</a></li><li><a href="#operations-on-references">Operations on references</a></li><li><a href="#operations-on-triples-and-quadruples">Operations on triples and quadruples</a></li><li><a href="#long-strings">Long strings</a></li><li><a href="#spell-checking-and-``did-you-mean''-suggestions">Spell checking and ``did you mean'' suggestions</a></li><li><a href="#colored-terminal-output">Colored terminal output</a></li><li><a href="#formatted-output">Formatted output</a></li><li><a href="#displaying-configuration-variables">Displaying configuration variables</a></li><li><a href="#handling-of-build-maps">Handling of build maps</a></li><li><a href="#handling-of-magic-numbers">Handling of magic numbers</a></li><li><a href="#miscellaneous-type-aliases">Miscellaneous type aliases</a></li></ul></nav><div class="odoc-content"><h2 id="reporting-fatal-errors"><a href="#reporting-fatal-errors" class="anchor"></a>Reporting fatal errors</h2><div class="odoc-spec"><div class="spec value anchored" id="val-fatal_error"><a href="#val-fatal_error" class="anchor"></a><code><span><span class="keyword">val</span> fatal_error : <span>string <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Raise the <code>Fatal_error</code> exception with the given string.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fatal_errorf"><a href="#val-fatal_errorf" class="anchor"></a><code><span><span class="keyword">val</span> fatal_errorf : <span><span><span>(<span class="type-var">'a</span>, <a href="../Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a>, unit, <span class="type-var">'b</span>)</span> <a href="../Stdlib/index.html#type-format4">format4</a></span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Format the arguments according to the given format string and raise <code>Fatal_error</code> with the resulting string.</p></div></div><div class="odoc-spec"><div class="spec exception anchored" id="exception-Fatal_error"><a href="#exception-Fatal_error" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">Fatal_error</span></span></code></div></div><h2 id="exceptions-and-finalization"><a href="#exceptions-and-finalization" class="anchor"></a>Exceptions and finalization</h2><div class="odoc-spec"><div class="spec value anchored" id="val-try_finally"><a href="#val-try_finally" class="anchor"></a><code><span><span class="keyword">val</span> try_finally :
|
||
<span><span class="optlabel">?always</span>:<span>(<span>unit <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?exceptionally</span>:<span>(<span>unit <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span>
|
||
<span><span>(<span>unit <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>try_finally work ~always ~exceptionally</code> is designed to run code in <code>work</code> that may fail with an exception, and has two kind of cleanup routines: <code>always</code>, that must be run after any execution of the function (typically, freeing system resources), and <code>exceptionally</code>, that should be run only if <code>work</code> or <code>always</code> failed with an exception (typically, undoing user-visible state changes that would only make sense if the function completes correctly). For example:</p><pre class="language-ocaml"><code>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);</code></pre><p>If <code>exceptionally</code> fail with an exception, it is propagated as usual.</p><p>If <code>always</code> or <code>exceptionally</code> use exceptions internally for control-flow but do not raise, then <code>try_finally</code> is careful to preserve any exception backtrace coming from <code>work</code> or <code>always</code> for easier debugging.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-reraise_preserving_backtrace"><a href="#val-reraise_preserving_backtrace" class="anchor"></a><code><span><span class="keyword">val</span> reraise_preserving_backtrace : <span>exn <span class="arrow">-></span></span> <span><span>(<span>unit <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>reraise_preserving_backtrace e f</code> is (f (); raise e) except that the current backtrace is preserved, even if <code>f</code> uses exceptions internally.</p></div></div><h2 id="list-operations"><a href="#list-operations" class="anchor"></a>List operations</h2><div class="odoc-spec"><div class="spec value anchored" id="val-map_end"><a href="#val-map_end" class="anchor"></a><code><span><span class="keyword">val</span> map_end : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> list</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'b</span> list</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> list</span></span></code></div><div class="spec-doc"><p><code>map_end f l t</code> is <code>map f l @ t</code>, just more efficient.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-map_left_right"><a href="#val-map_left_right" class="anchor"></a><code><span><span class="keyword">val</span> map_left_right : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> list</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> list</span></span></code></div><div class="spec-doc"><p>Like <code>List.map</code>, with guaranteed left-to-right evaluation order</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-for_all2"><a href="#val-for_all2" class="anchor"></a><code><span><span class="keyword">val</span> for_all2 : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <span class="arrow">-></span></span> bool)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> list</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'b</span> list</span> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p>Same as <code>List.for_all</code> but for a binary predicate. In addition, this <code>for_all2</code> never fails: given two lists with different lengths, it returns false.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-replicate_list"><a href="#val-replicate_list" class="anchor"></a><code><span><span class="keyword">val</span> replicate_list : <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><span class="type-var">'a</span> list</span></span></code></div><div class="spec-doc"><p><code>replicate_list elem n</code> is the list with <code>n</code> elements all identical to <code>elem</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-list_remove"><a href="#val-list_remove" class="anchor"></a><code><span><span class="keyword">val</span> list_remove : <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> list</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> list</span></span></code></div><div class="spec-doc"><p><code>list_remove x l</code> returns a copy of <code>l</code> with the first element equal to <code>x</code> removed.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-split_last"><a href="#val-split_last" class="anchor"></a><code><span><span class="keyword">val</span> split_last : <span><span><span class="type-var">'a</span> list</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> list</span> * <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Return the last element and the other elements of the given list.</p></div></div><h2 id="hash-table-operations"><a href="#hash-table-operations" class="anchor"></a>Hash table operations</h2><div class="odoc-spec"><div class="spec value anchored" id="val-create_hashtable"><a href="#val-create_hashtable" class="anchor"></a><code><span><span class="keyword">val</span> create_hashtable : <span>int <span class="arrow">-></span></span> <span><span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span>)</span> list</span> <span class="arrow">-></span></span> <span><span>(<span class="type-var">'a</span>, <span class="type-var">'b</span>)</span> <a href="../Stdlib/Hashtbl/index.html#type-t">Stdlib.Hashtbl.t</a></span></span></code></div><div class="spec-doc"><p>Create a hashtable with the given initial size and fills it with the given bindings.</p></div></div><h2 id="extensions-to-the-standard-library"><a href="#extensions-to-the-standard-library" class="anchor"></a>Extensions to the standard library</h2><div class="odoc-spec"><div class="spec module anchored" id="module-Stdlib"><a href="#module-Stdlib" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Stdlib/index.html">Stdlib</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><h2 id="operations-on-files-and-file-paths"><a href="#operations-on-files-and-file-paths" class="anchor"></a>Operations on files and file paths</h2><div class="odoc-spec"><div class="spec value anchored" id="val-find_in_path"><a href="#val-find_in_path" class="anchor"></a><code><span><span class="keyword">val</span> find_in_path : <span><span>string list</span> <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p>Search a file in a list of directories.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-find_in_path_rel"><a href="#val-find_in_path_rel" class="anchor"></a><code><span><span class="keyword">val</span> find_in_path_rel : <span><span>string list</span> <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p>Search a relative file in a list of directories.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-find_in_path_uncap"><a href="#val-find_in_path_uncap" class="anchor"></a><code><span><span class="keyword">val</span> find_in_path_uncap : <span><span>string list</span> <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p>Same, but search also for uncapitalized name, i.e. if name is <code>Foo.ml</code>, allow <code>/path/Foo.ml</code> and <code>/path/foo.ml</code> to match.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-remove_file"><a href="#val-remove_file" class="anchor"></a><code><span><span class="keyword">val</span> remove_file : <span>string <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Delete the given file if it exists and is a regular file. Does nothing for other kinds of files. Never raises an error.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-expand_directory"><a href="#val-expand_directory" class="anchor"></a><code><span><span class="keyword">val</span> expand_directory : <span>string <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>expand_directory alt file</code> eventually expands a <code>+</code> at the beginning of file into <code>alt</code> (an alternate root directory)</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-split_path_contents"><a href="#val-split_path_contents" class="anchor"></a><code><span><span class="keyword">val</span> split_path_contents : <span><span class="optlabel">?sep</span>:char <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <span>string list</span></span></code></div><div class="spec-doc"><p><code>split_path_contents ?sep s</code> interprets <code>s</code> as the value of a "PATH"-like variable and returns the corresponding list of directories. <code>s</code> is split using the platform-specific delimiter, or <code>~sep</code> if it is passed.</p><p>Returns the empty list if <code>s</code> is empty.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-copy_file"><a href="#val-copy_file" class="anchor"></a><code><span><span class="keyword">val</span> copy_file : <span><a href="../Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <span><a href="../Stdlib/index.html#type-out_channel">out_channel</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>copy_file ic oc</code> reads the contents of file <code>ic</code> and copies them to <code>oc</code>. It stops when encountering EOF on <code>ic</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-copy_file_chunk"><a href="#val-copy_file_chunk" class="anchor"></a><code><span><span class="keyword">val</span> copy_file_chunk : <span><a href="../Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> <span><a href="../Stdlib/index.html#type-out_channel">out_channel</a> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>copy_file_chunk ic oc n</code> reads <code>n</code> bytes from <code>ic</code> and copies them to <code>oc</code>. It raises <code>End_of_file</code> when encountering EOF on <code>ic</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-string_of_file"><a href="#val-string_of_file" class="anchor"></a><code><span><span class="keyword">val</span> string_of_file : <span><a href="../Stdlib/index.html#type-in_channel">in_channel</a> <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>string_of_file ic</code> reads the contents of file <code>ic</code> and copies them to a string. It stops when encountering EOF on <code>ic</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-output_to_file_via_temporary"><a href="#val-output_to_file_via_temporary" class="anchor"></a><code><span><span class="keyword">val</span> output_to_file_via_temporary :
|
||
<span><span class="optlabel">?mode</span>:<span><a href="../Stdlib/index.html#type-open_flag">open_flag</a> list</span> <span class="arrow">-></span></span>
|
||
<span>string <span class="arrow">-></span></span>
|
||
<span><span>(<span>string <span class="arrow">-></span></span> <span><a href="../Stdlib/index.html#type-out_channel">out_channel</a> <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Produce output in temporary file, then rename it (as atomically as possible) to the desired output file name. <code>output_to_file_via_temporary filename fn</code> opens a temporary file which is passed to <code>fn</code> (name + output channel). When <code>fn</code> returns, the channel is closed and the temporary file is renamed to <code>filename</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-protect_writing_to_file"><a href="#val-protect_writing_to_file" class="anchor"></a><code><span><span class="keyword">val</span> protect_writing_to_file : <span><span class="label">filename</span>:string <span class="arrow">-></span></span> <span><span class="label">f</span>:<span>(<span><a href="../Stdlib/index.html#type-out_channel">out_channel</a> <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p>Open the given <code>filename</code> for writing (in binary mode), pass the <code>out_channel</code> to the given function, then close the channel. If the function raises an exception then <code>filename</code> will be removed.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-concat_null_terminated"><a href="#val-concat_null_terminated" class="anchor"></a><code><span><span class="keyword">val</span> concat_null_terminated : <span><span>string list</span> <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>concat_null_terminated [x1;x2; ... xn]</code> is <code>x1 ^ "\000" ^ x2 ^ "\000" ^ ... ^ xn ^ "\000"</code></p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-split_null_terminated"><a href="#val-split_null_terminated" class="anchor"></a><code><span><span class="keyword">val</span> split_null_terminated : <span>string <span class="arrow">-></span></span> <span>string list</span></span></code></div><div class="spec-doc"><p><code>split_null_terminated s</code> is similar <code>String.split_on_char '\000'</code> but ignores the trailing separator, if any</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-chop_extensions"><a href="#val-chop_extensions" class="anchor"></a><code><span><span class="keyword">val</span> chop_extensions : <span>string <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p>Return the given file name without its extensions. The extensions is the longest suffix starting with a period and not including a directory separator, <code>.xyz.uvw</code> for instance.</p><p>Return the given name if it does not contain an extension.</p></div></div><h2 id="integer-operations"><a href="#integer-operations" class="anchor"></a>Integer operations</h2><div class="odoc-spec"><div class="spec value anchored" id="val-log2"><a href="#val-log2" class="anchor"></a><code><span><span class="keyword">val</span> log2 : <span>int <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>log2 n</code> returns <code>s</code> such that <code>n = 1 lsl s</code> if <code>n</code> is a power of 2</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-align"><a href="#val-align" class="anchor"></a><code><span><span class="keyword">val</span> align : <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>align n a</code> rounds <code>n</code> upwards to a multiple of <code>a</code> (a power of 2).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-no_overflow_add"><a href="#val-no_overflow_add" class="anchor"></a><code><span><span class="keyword">val</span> no_overflow_add : <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>no_overflow_add n1 n2</code> returns <code>true</code> if the computation of <code>n1 + n2</code> does not overflow.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-no_overflow_sub"><a href="#val-no_overflow_sub" class="anchor"></a><code><span><span class="keyword">val</span> no_overflow_sub : <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>no_overflow_sub n1 n2</code> returns <code>true</code> if the computation of <code>n1 - n2</code> does not overflow.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-no_overflow_mul"><a href="#val-no_overflow_mul" class="anchor"></a><code><span><span class="keyword">val</span> no_overflow_mul : <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>no_overflow_mul n1 n2</code> returns <code>true</code> if the computation of <code>n1 * n2</code> does not overflow.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-no_overflow_lsl"><a href="#val-no_overflow_lsl" class="anchor"></a><code><span><span class="keyword">val</span> no_overflow_lsl : <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>no_overflow_lsl n k</code> returns <code>true</code> if the computation of <code>n lsl k</code> does not overflow.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Int_literal_converter"><a href="#module-Int_literal_converter" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Int_literal_converter/index.html">Int_literal_converter</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-find_first_mono"><a href="#val-find_first_mono" class="anchor"></a><code><span><span class="keyword">val</span> find_first_mono : <span><span>(<span>int <span class="arrow">-></span></span> bool)</span> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>find_first_mono p</code> takes an integer predicate <code>p : int -> bool</code> that we assume: 1. is monotonic on natural numbers: if <code>a <= b</code> then <code>p a</code> implies <code>p b</code>, 2. is satisfied for some natural numbers in range <code>0; max_int</code> (this is equivalent to: <code>p max_int = true</code>).</p><p><code>find_first_mono p</code> is the smallest natural number N that satisfies <code>p</code>, computed in O(log(N)) calls to <code>p</code>.</p><p>Our implementation supports two cases where the preconditions on <code>p</code> are not respected:</p><ul><li>If <code>p</code> is always <code>false</code>, we silently return <code>max_int</code> instead of looping or crashing.</li><li>If <code>p</code> is non-monotonic but eventually true, we return some satisfying value.</li></ul></div></div><h2 id="string-operations"><a href="#string-operations" class="anchor"></a>String operations</h2><div class="odoc-spec"><div class="spec value anchored" id="val-search_substring"><a href="#val-search_substring" class="anchor"></a><code><span><span class="keyword">val</span> search_substring : <span>string <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>search_substring pat str start</code> returns the position of the first occurrence of string <code>pat</code> in string <code>str</code>. Search starts at offset <code>start</code> in <code>str</code>. Raise <code>Not_found</code> if <code>pat</code> does not occur.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-replace_substring"><a href="#val-replace_substring" class="anchor"></a><code><span><span class="keyword">val</span> replace_substring : <span><span class="label">before</span>:string <span class="arrow">-></span></span> <span><span class="label">after</span>:string <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>replace_substring ~before ~after str</code> replaces all occurrences of <code>before</code> with <code>after</code> in <code>str</code> and returns the resulting string.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-rev_split_words"><a href="#val-rev_split_words" class="anchor"></a><code><span><span class="keyword">val</span> rev_split_words : <span>string <span class="arrow">-></span></span> <span>string list</span></span></code></div><div class="spec-doc"><p><code>rev_split_words s</code> splits <code>s</code> in blank-separated words, and returns the list of words in reverse order.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-cut_at"><a href="#val-cut_at" class="anchor"></a><code><span><span class="keyword">val</span> cut_at : <span>string <span class="arrow">-></span></span> <span>char <span class="arrow">-></span></span> string * string</span></code></div><div class="spec-doc"><p><code>String.cut_at s c</code> returns a pair containing the sub-string before the first occurrence of <code>c</code> in <code>s</code>, and the sub-string after the first occurrence of <code>c</code> in <code>s</code>. <code>let (before, after) = String.cut_at s c in
|
||
before ^ String.make 1 c ^ after</code> is the identity if <code>s</code> contains <code>c</code>.</p><p>Raise <code>Not_found</code> if the character does not appear in the string</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 4.01</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-ordinal_suffix"><a href="#val-ordinal_suffix" class="anchor"></a><code><span><span class="keyword">val</span> ordinal_suffix : <span>int <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>ordinal_suffix n</code> is the appropriate suffix to append to the numeral <code>n</code> as an ordinal number: <code>1</code> -> <code>"st"</code>, <code>2</code> -> <code>"nd"</code>, <code>3</code> -> <code>"rd"</code>, <code>4</code> -> <code>"th"</code>, and so on. Handles larger numbers (e.g., <code>42</code> -> <code>"nd"</code>) and the numbers 11--13 (which all get <code>"th"</code>) correctly.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-normalise_eol"><a href="#val-normalise_eol" class="anchor"></a><code><span><span class="keyword">val</span> normalise_eol : <span>string <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>normalise_eol s</code> returns a fresh copy of <code>s</code> 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)</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-delete_eol_spaces"><a href="#val-delete_eol_spaces" class="anchor"></a><code><span><span class="keyword">val</span> delete_eol_spaces : <span>string <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>delete_eol_spaces s</code> returns a fresh copy of <code>s</code> with any end of line spaces removed. Intended to normalize the output of the toplevel for tests.</p></div></div><h2 id="operations-on-references"><a href="#operations-on-references" class="anchor"></a>Operations on references</h2><div class="odoc-spec"><div class="spec type anchored" id="type-ref_and_value"><a href="#type-ref_and_value" class="anchor"></a><code><span><span class="keyword">type</span> ref_and_value</span><span> = </span></code><ol><li id="type-ref_and_value.R" class="def variant constructor anchored"><a href="#type-ref_and_value.R" class="anchor"></a><code><span>| </span><span><span class="constructor">R</span> : <span><span class="type-var">'a</span> <a href="../Stdlib/index.html#type-ref">ref</a></span> * <span class="type-var">'a</span> <span class="arrow">-></span> <a href="#type-ref_and_value">ref_and_value</a></span></code></li></ol></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-protect_refs"><a href="#val-protect_refs" class="anchor"></a><code><span><span class="keyword">val</span> protect_refs : <span><span><a href="#type-ref_and_value">ref_and_value</a> list</span> <span class="arrow">-></span></span> <span><span>(<span>unit <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>protect_refs l f</code> temporarily sets <code>r</code> to <code>v</code> for each <code>R (r, v)</code> in <code>l</code> while executing <code>f</code>. The previous contents of the references is restored even if <code>f</code> raises an exception, without altering the exception backtrace.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get_ref"><a href="#val-get_ref" class="anchor"></a><code><span><span class="keyword">val</span> get_ref : <span><span><span><span class="type-var">'a</span> list</span> <a href="../Stdlib/index.html#type-ref">ref</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> list</span></span></code></div><div class="spec-doc"><p><code>get_ref lr</code> returns the content of the list reference <code>lr</code> and reset its content to the empty list.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-set_or_ignore"><a href="#val-set_or_ignore" class="anchor"></a><code><span><span class="keyword">val</span> set_or_ignore : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> option</span>)</span> <span class="arrow">-></span></span> <span><span><span><span class="type-var">'b</span> option</span> <a href="../Stdlib/index.html#type-ref">ref</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>set_or_ignore f opt x</code> sets <code>opt</code> to <code>f x</code> if it returns <code>Some _</code>, or leaves it unmodified if it returns <code>None</code>.</p></div></div><h2 id="operations-on-triples-and-quadruples"><a href="#operations-on-triples-and-quadruples" class="anchor"></a>Operations on triples and quadruples</h2><div class="odoc-spec"><div class="spec value anchored" id="val-fst3"><a href="#val-fst3" class="anchor"></a><code><span><span class="keyword">val</span> fst3 : <span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span> * <span class="type-var">'c</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-snd3"><a href="#val-snd3" class="anchor"></a><code><span><span class="keyword">val</span> snd3 : <span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span> * <span class="type-var">'c</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'b</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-thd3"><a href="#val-thd3" class="anchor"></a><code><span><span class="keyword">val</span> thd3 : <span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span> * <span class="type-var">'c</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'c</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fst4"><a href="#val-fst4" class="anchor"></a><code><span><span class="keyword">val</span> fst4 : <span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span> * <span class="type-var">'c</span> * <span class="type-var">'d</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-snd4"><a href="#val-snd4" class="anchor"></a><code><span><span class="keyword">val</span> snd4 : <span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span> * <span class="type-var">'c</span> * <span class="type-var">'d</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'b</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-thd4"><a href="#val-thd4" class="anchor"></a><code><span><span class="keyword">val</span> thd4 : <span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span> * <span class="type-var">'c</span> * <span class="type-var">'d</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'c</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-for4"><a href="#val-for4" class="anchor"></a><code><span><span class="keyword">val</span> for4 : <span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span> * <span class="type-var">'c</span> * <span class="type-var">'d</span>)</span> <span class="arrow">-></span></span> <span class="type-var">'d</span></span></code></div></div><h2 id="long-strings"><a href="#long-strings" class="anchor"></a>Long strings</h2><p>``Long strings'' are mutable arrays of characters that are not limited in length to <code>Sys.max_string_length</code>.</p><div class="odoc-spec"><div class="spec module anchored" id="module-LongString"><a href="#module-LongString" class="anchor"></a><code><span><span class="keyword">module</span> <a href="LongString/index.html">LongString</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><h2 id="spell-checking-and-``did-you-mean''-suggestions"><a href="#spell-checking-and-``did-you-mean''-suggestions" class="anchor"></a>Spell checking and ``did you mean'' suggestions</h2><div class="odoc-spec"><div class="spec value anchored" id="val-edit_distance"><a href="#val-edit_distance" class="anchor"></a><code><span><span class="keyword">val</span> edit_distance : <span>string <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span>int option</span></span></code></div><div class="spec-doc"><p><code>edit_distance a b cutoff</code> computes the edit distance between strings <code>a</code> and <code>b</code>. To help efficiency, it uses a cutoff: if the distance <code>d</code> is smaller than <code>cutoff</code>, it returns <code>Some d</code>, else <code>None</code>.</p><p>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.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-spellcheck"><a href="#val-spellcheck" class="anchor"></a><code><span><span class="keyword">val</span> spellcheck : <span><span>string list</span> <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <span>string list</span></span></code></div><div class="spec-doc"><p><code>spellcheck env name</code> takes a list of names <code>env</code> that exist in the current environment and an erroneous <code>name</code>, and returns a list of suggestions taken from <code>env</code>, that are close enough to <code>name</code> that it may be a typo for one of them.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-did_you_mean"><a href="#val-did_you_mean" class="anchor"></a><code><span><span class="keyword">val</span> did_you_mean : <span><a href="../Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span> <span><span>(<span>unit <span class="arrow">-></span></span> <span>string list</span>)</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>did_you_mean ppf get_choices</code> hints that the user may have meant one of the option returned by calling <code>get_choices</code>. It does nothing if the returned list is empty.</p><p>The <code>unit -> ...</code> thunking is meant to delay any potentially-slow computation (typically computing edit-distance with many things from the current environment) to when the hint message is to be printed. You should print an understandable error message before calling <code>did_you_mean</code>, so that users get a clear notification of the failure even if producing the hint is slow.</p></div></div><h2 id="colored-terminal-output"><a href="#colored-terminal-output" class="anchor"></a>Colored terminal output</h2><div class="odoc-spec"><div class="spec module anchored" id="module-Color"><a href="#module-Color" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Color/index.html">Color</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Error_style"><a href="#module-Error_style" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Error_style/index.html">Error_style</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><h2 id="formatted-output"><a href="#formatted-output" class="anchor"></a>Formatted output</h2><div class="odoc-spec"><div class="spec value anchored" id="val-print_if"><a href="#val-print_if" class="anchor"></a><code><span><span class="keyword">val</span> print_if :
|
||
<span><a href="../Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span>
|
||
<span><span>bool <a href="../Stdlib/index.html#type-ref">ref</a></span> <span class="arrow">-></span></span>
|
||
<span><span>(<span><a href="../Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <span class="arrow">-></span></span>
|
||
<span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>print_if ppf flag fmt x</code> prints <code>x</code> with <code>fmt</code> on <code>ppf</code> if <code>b</code> is true.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-pp_two_columns"><a href="#val-pp_two_columns" class="anchor"></a><code><span><span class="keyword">val</span> pp_two_columns :
|
||
<span><span class="optlabel">?sep</span>:string <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?max_lines</span>:int <span class="arrow">-></span></span>
|
||
<span><a href="../Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span>
|
||
<span><span><span>(string * string)</span> list</span> <span class="arrow">-></span></span>
|
||
unit</span></code></div><div class="spec-doc"><p><code>pp_two_columns ?sep ?max_lines ppf l</code> prints the lines in <code>l</code> as two columns separated by <code>sep</code> ("|" by default). <code>max_lines</code> can be used to indicate a maximum number of lines to print -- an ellipsis gets inserted at the middle if the input has too many lines.</p><p>Example:</p><pre>pp_two_columns ~max_lines:3 Format.std_formatter [
|
||
"abc", "hello";
|
||
"def", "zzz";
|
||
"a" , "bllbl";
|
||
"bb" , "dddddd";
|
||
]</pre><p>prints</p><pre> abc | hello
|
||
...
|
||
bb | dddddd</pre></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-print_see_manual"><a href="#val-print_see_manual" class="anchor"></a><code><span><span class="keyword">val</span> print_see_manual : <span><a href="../Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span> <span><span>int list</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>See manual section</p></div></div><h2 id="displaying-configuration-variables"><a href="#displaying-configuration-variables" class="anchor"></a>Displaying configuration variables</h2><div class="odoc-spec"><div class="spec value anchored" id="val-show_config_and_exit"><a href="#val-show_config_and_exit" class="anchor"></a><code><span><span class="keyword">val</span> show_config_and_exit : <span>unit <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Display the values of all compiler configuration variables from module <code>Config</code>, then exit the program with code 0.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-show_config_variable_and_exit"><a href="#val-show_config_variable_and_exit" class="anchor"></a><code><span><span class="keyword">val</span> show_config_variable_and_exit : <span>string <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p>Display the value of the given configuration variable, then exit the program with code 0.</p></div></div><h2 id="handling-of-build-maps"><a href="#handling-of-build-maps" class="anchor"></a>Handling of build maps</h2><p>Build maps cause the compiler to normalize file names embedded in object files, thus leading to more reproducible builds.</p><div class="odoc-spec"><div class="spec value anchored" id="val-get_build_path_prefix_map"><a href="#val-get_build_path_prefix_map" class="anchor"></a><code><span><span class="keyword">val</span> get_build_path_prefix_map : <span>unit <span class="arrow">-></span></span> <span><a href="../Build_path_prefix_map/index.html#type-map">Build_path_prefix_map.map</a> option</span></span></code></div><div class="spec-doc"><p>Returns the map encoded in the <code>BUILD_PATH_PREFIX_MAP</code> environment variable.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-debug_prefix_map_flags"><a href="#val-debug_prefix_map_flags" class="anchor"></a><code><span><span class="keyword">val</span> debug_prefix_map_flags : <span>unit <span class="arrow">-></span></span> <span>string list</span></span></code></div><div class="spec-doc"><p>Returns the list of <code>--debug-prefix-map</code> flags to be passed to the assembler, built from the <code>BUILD_PATH_PREFIX_MAP</code> environment variable.</p></div></div><h2 id="handling-of-magic-numbers"><a href="#handling-of-magic-numbers" class="anchor"></a>Handling of magic numbers</h2><div class="odoc-spec"><div class="spec module anchored" id="module-Magic_number"><a href="#module-Magic_number" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Magic_number/index.html">Magic_number</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>a typical magic number is "Caml1999I011"; it is formed of an alphanumeric prefix, here Caml1990I, followed by a version, here 011. The prefix identifies the kind of the versioned data: here the I indicates that it is the magic number for .cmi files.</p></div></div><h2 id="miscellaneous-type-aliases"><a href="#miscellaneous-type-aliases" class="anchor"></a>Miscellaneous type aliases</h2><div class="odoc-spec"><div class="spec type anchored" id="type-filepath"><a href="#type-filepath" class="anchor"></a><code><span><span class="keyword">type</span> filepath</span><span> = string</span></code></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-modname"><a href="#type-modname" class="anchor"></a><code><span><span class="keyword">type</span> modname</span><span> = string</span></code></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-crcs"><a href="#type-crcs" class="anchor"></a><code><span><span class="keyword">type</span> crcs</span><span> = <span><span>(<a href="#type-modname">modname</a> * <span><a href="../Stdlib/Digest/index.html#type-t">Stdlib.Digest.t</a> option</span>)</span> list</span></span></code></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-alerts"><a href="#type-alerts" class="anchor"></a><code><span><span class="keyword">type</span> alerts</span><span> = <span>string <a href="Stdlib/String/Map/index.html#type-t">Stdlib.String.Map.t</a></span></span></code></div></div></div></body></html>
|