Stdlib: Add function composition combinator

Changes

@@ -278,6 +278,9 @@ Working version
 - #12784: Fix computation of minor-heap allocation in Gc.counters()
   and Gc.allocated_bytes(). (Nick Barnes, review by Gabriel Scherer)
 
+- #12770: Add `Fun.compose`.
+  (Justin Frank, review by Nicolás Ojeda Bär, Daniel Bünzli and Jeremy Yallop)
+
 ### Other libraries:
 
 - #12213: Dynlink library, improve legibility of error messages

stdlib/fun.ml

@@ -15,6 +15,7 @@
 
 external id : 'a -> 'a = "%identity"
 let const c _ = c
+let compose f g x = f (g x)
 let flip f x y = f y x
 let negate p v = not (p v)
 

stdlib/fun.mli

@@ -26,6 +26,12 @@ val const : 'a -> (_ -> 'a)
 (** [const c] is a function that always returns the value [c]. For any
     argument [x], [(const c) x] is [c]. *)
 
+val compose : ('b -> 'c) -> ('a -> 'b) -> 'a -> 'c
+(** [compose f g] is a function composition of applying [g] then [f].
+    For any arguments [f], [g], and [x], [compose f g x] is [f (g x)].
+
+    @since 5.2 *)
+
 val flip : ('a -> 'b -> 'c) -> ('b -> 'a -> 'c)
 (** [flip f] reverses the argument order of the binary function
     [f]. For any arguments [x] and [y], [(flip f) x y] is [f y x]. *)

testsuite/tests/backtrace/backtrace_dynlink.flambda.reference

@@ -5,7 +5,7 @@ Called from Dynlink.Native.run in file "native/dynlink.ml", line 82, characters
 Called from Dynlink_common.Make.load.(fun) in file "dynlink_common.ml", line 358, characters 11-54
 Called from Stdlib__List.iter in file "list.ml" (inlined), line 112, characters 12-15
 Called from Dynlink_common.Make.load.(fun) in file "dynlink_common.ml" (inlined), line 354, characters 6-372
-Called from Stdlib__Fun.protect in file "fun.ml" (inlined), line 33, characters 8-15
+Called from Stdlib__Fun.protect in file "fun.ml" (inlined), line 34, characters 8-15
 Called from Dynlink_common.Make.load in file "dynlink_common.ml", line 347, characters 4-662
 Called from Dynlink_common.Make.loadfile in file "dynlink_common.ml" (inlined), line 366, characters 26-45
 Called from Backtrace_dynlink in file "backtrace_dynlink.ml", line 39, characters 4-52
@@ -17,9 +17,9 @@ Called from Dynlink.Native.run in file "native/dynlink.ml", line 82, characters
 Called from Dynlink_common.Make.load.(fun) in file "dynlink_common.ml", line 358, characters 11-54
 Called from Stdlib__List.iter in file "list.ml" (inlined), line 112, characters 12-15
 Called from Dynlink_common.Make.load.(fun) in file "dynlink_common.ml" (inlined), line 354, characters 6-372
-Called from Stdlib__Fun.protect in file "fun.ml" (inlined), line 33, characters 8-15
+Called from Stdlib__Fun.protect in file "fun.ml" (inlined), line 34, characters 8-15
 Called from Dynlink_common.Make.load in file "dynlink_common.ml", line 347, characters 4-662
-Re-raised at Stdlib__Fun.protect in file "fun.ml" (inlined), line 38, characters 6-52
+Re-raised at Stdlib__Fun.protect in file "fun.ml" (inlined), line 39, characters 6-52
 Called from Dynlink_common.Make.load in file "dynlink_common.ml", line 347, characters 4-662
 Called from Dynlink_common.Make.loadfile in file "dynlink_common.ml" (inlined), line 366, characters 26-45
 Called from Backtrace_dynlink in file "backtrace_dynlink.ml", line 39, characters 4-52

testsuite/tests/backtrace/backtrace_dynlink.reference

@@ -3,7 +3,7 @@ Called from Dynlink.Native.run.(fun) in file "native/dynlink.ml", line 83, chara
 Called from Stdlib__List.iter in file "list.ml", line 112, characters 12-15
 Called from Dynlink_common.Make.load.(fun) in file "dynlink_common.ml", line 358, characters 11-54
 Called from Stdlib__List.iter in file "list.ml", line 112, characters 12-15
-Called from Stdlib__Fun.protect in file "fun.ml", line 33, characters 8-15
+Called from Stdlib__Fun.protect in file "fun.ml", line 34, characters 8-15
 Called from Dynlink_common.Make.loadfile in file "dynlink_common.ml" (inlined), line 366, characters 26-45
 Called from Backtrace_dynlink in file "backtrace_dynlink.ml", line 39, characters 4-52
 execution of module initializers in the shared library failed: Failure("SUCCESS")
@@ -12,7 +12,7 @@ Re-raised at Dynlink.Native.run.(fun) in file "native/dynlink.ml", line 85, char
 Called from Stdlib__List.iter in file "list.ml", line 112, characters 12-15
 Called from Dynlink_common.Make.load.(fun) in file "dynlink_common.ml", line 358, characters 11-54
 Called from Stdlib__List.iter in file "list.ml", line 112, characters 12-15
-Called from Stdlib__Fun.protect in file "fun.ml", line 33, characters 8-15
-Re-raised at Stdlib__Fun.protect in file "fun.ml", line 38, characters 6-52
+Called from Stdlib__Fun.protect in file "fun.ml", line 34, characters 8-15
+Re-raised at Stdlib__Fun.protect in file "fun.ml", line 39, characters 6-52
 Called from Dynlink_common.Make.loadfile in file "dynlink_common.ml" (inlined), line 366, characters 26-45
 Called from Backtrace_dynlink in file "backtrace_dynlink.ml", line 39, characters 4-52

testsuite/tests/lib-dynlink-initializers/test10_main.byte.reference

@@ -7,6 +7,6 @@ Called from Dynlink.Bytecode.run in file "byte/dynlink.ml", line 152, characters
 Re-raised at Dynlink.Bytecode.run in file "byte/dynlink.ml", line 154, characters 6-137
 Called from Dynlink_common.Make.load.(fun) in file "dynlink_common.ml", line 358, characters 11-54
 Called from Stdlib__List.iter in file "list.ml", line 112, characters 12-15
-Called from Stdlib__Fun.protect in file "fun.ml", line 33, characters 8-15
-Re-raised at Stdlib__Fun.protect in file "fun.ml", line 38, characters 6-52
+Called from Stdlib__Fun.protect in file "fun.ml", line 34, characters 8-15
+Re-raised at Stdlib__Fun.protect in file "fun.ml", line 39, characters 6-52
 Called from Test10_main in file "test10_main.ml", line 51, characters 13-69

testsuite/tests/lib-dynlink-initializers/test10_main.native.reference

@@ -4,7 +4,7 @@ Re-raised at Dynlink.Native.run.(fun) in file "native/dynlink.ml", line 85, char
 Called from Stdlib__List.iter in file "list.ml", line 112, characters 12-15
 Called from Dynlink_common.Make.load.(fun) in file "dynlink_common.ml", line 358, characters 11-54
 Called from Stdlib__List.iter in file "list.ml", line 112, characters 12-15
-Called from Stdlib__Fun.protect in file "fun.ml", line 33, characters 8-15
-Re-raised at Stdlib__Fun.protect in file "fun.ml", line 38, characters 6-52
+Called from Stdlib__Fun.protect in file "fun.ml", line 34, characters 8-15
+Re-raised at Stdlib__Fun.protect in file "fun.ml", line 39, characters 6-52
 Called from Dynlink_common.Make.loadfile in file "dynlink_common.ml" (inlined), line 366, characters 26-45
 Called from Test10_main in file "test10_main.ml", line 49, characters 30-87