1
``Stdcompat``: compatibility module for OCaml standard library
2
==============================================================
4
``Stdcompat`` is a compatibility layer allowing programs to use some
5
recent additions to the OCaml standard library while preserving the
6
ability to be compiled on former versions of OCaml.
8
The ``Stdcompat`` API is not intended to be stable, but there will be
9
efforts to allow future versions of ``Stdcompat`` to be compiled on a
10
large range of versions of OCaml: ``Stdcompat`` should compile (at least)
11
on every version of OCaml from 3.07 (included).
13
The module ``Stdcompat`` provides some definitions for values and
14
types introduced in recent versions of the standard library. These
15
definitions are just aliases to the matching definition of the standard
16
library if the latter is recent enough. Otherwise, the module
17
``Stdcompat`` provides an alternative implementation.
19
The signature of ``Stdcompat`` follows the signature of the standard library.
20
All the modules are defined as sub-modules of ``Stdcompat.Stdlib``, such as
21
``Stdcompat.Stdlib.Pervasives``, ``Stdcompat.Stdlib.List``, etc. The module
22
``Stdcompat.Stdlib.Pervasives`` is included in ``Stdcompat.Stdlib``, and
23
the module ``Stdcompat.Stdlib`` is included in ``Stdcompat`` itself.
24
For instance, the function
25
``Stdcompat.really_input_string`` is an alias for
26
``Stdcompat.Pervasives.really_input_string``,
27
which is an alias for ``Stdcompat.Stdlib.Pervasives.really_input_string``,
28
which is itself an alias for
29
``Pervasives.really_input_string`` when the version of the OCaml
30
compiler is above 4.02.0, or an alternative definition otherwise.
32
The types ``Stdcompat.bytes`` and ``Stdcompat.floatarray`` are aliases
33
to the built-in ones is the latter are available (above 4.02.0 for
34
``bytes`` and above 4.06.0 for ``floatarray``), and are aliases to
35
``string`` and ``float array`` respectively otherwise.
37
Sub-modules match the names of the standard library modules. For
38
instance, ``Stdcompat.List.find_opt`` is an alias for
39
``List.find_opt`` on 4.05.0 and above, or an alternative definition
40
otherwise. Definitions from the standard library are reexported so that
41
``Stdcompat`` can be open without hiding unchanged definitions.
43
Functors ``Set.Make``, ``Map.Make``, ``Hashtbl.Make``, ``Weak.Make``
44
are redefined to provide the additional definitions appeared on recent
47
If ``Pervasives.result``, ``Uchar.t`` and/or ``Seq.t`` are not
48
provided by the standard library and if the compatibility packages
49
``result``, ``uchar``, and/or ``seq`` are available via ``ocamlfind``,
50
then the types ``Stdcompat.Pervasives.result``, ``Stdcompat.Uchar.t``
51
and ``Stdcompat.Seq.t`` are defined as alias to the types defined in
52
those packages (these packages should then appear before ``Stdcompat``
53
in the linking chain).
55
Some redefinitions access to the internal representation of
56
the data structures when they are abstracted: it is the case for
57
``{Set,Map,Hashtbl,Queue,Stack}.to_seq*``,
58
``Hashtbl.filter_map_inplace``, ``Hashtbl.stats``, ``Stack.fold``,
59
``Set.find*``, ``Set.map``.
60
Pure (but less efficient) implementations are available by configuring
61
``Stdcompat`` with ``./configure --disable-magic``.
62
Note that redefinitions can still have bad time complexity:
63
for instance, ``Set.map`` uses the function ``union`` to rebuild trees
64
instead of the internal function ``try_join``, because using the
65
latter would require to redefine too much internal functions.
67
Redefinitions cannot even guarantee some security fixes: for instance,
68
seeds and randomization are ignored with ``Hashtbl`` prior to 4.00.0.
70
See the generated documentation (in ``doc/``) for available
added
removed
bundles/stdcompat/stdcompat-current/README.md
