Documentation of "undefined behaviors"

Changes

@@ -8,12 +8,21 @@ Working version
 
 ### Standard library:
 
+* #7812, #10475: `Filename.chop_suffix name suff` now checks that `suff`
+  is actually a suffix of `name` and raises Invalid_argument otherwise.
+  (Xavier Leroy, report by whitequark, review by David Allsopp)
+
 ### Other libraries:
 
 ### Tools:
 
 ### Manual and documentation:
 
+- #7812, #10475: reworded the description of the behaviors of
+  float->int conversions in case of overflow, and of iterators
+  in case of concurrent modifications.
+  (Xavier Leroy, report by whitequark, review by David Allsopp)
+
 ### Compiler user-interface and warnings:
 
 - #10328: Give more precise error when disambiguation could not possibly work.

stdlib/buffer.mli

@@ -186,12 +186,14 @@ val add_channel : t -> in_channel -> int -> unit
 
 val to_seq : t -> char Seq.t
 (** Iterate on the buffer, in increasing order.
-    Modification of the buffer during iteration is undefined behavior.
+
+    The behavior is not specified if the buffer is modified during iteration.
     @since 4.07 *)
 
 val to_seqi : t -> (int * char) Seq.t
 (** Iterate on the buffer, in increasing order, yielding indices along chars.
-    Modification of the buffer during iteration is undefined behavior.
+
+    The behavior is not specified if the buffer is modified during iteration.
     @since 4.07 *)
 
 val add_seq : t -> char Seq.t -> unit

stdlib/filename.ml

@@ -293,8 +293,9 @@ let concat dirname filename =
   else dirname ^ dir_sep ^ filename
 
 let chop_suffix name suff =
-  let n = String.length name - String.length suff in
-  if n < 0 then invalid_arg "Filename.chop_suffix" else String.sub name 0 n
+  if check_suffix name suff
+  then String.sub name 0 (String.length name - String.length suff)
+  else invalid_arg "Filename.chop_suffix"
 
 let extension_len name =
   let rec check i0 i =

stdlib/filename.mli

@@ -51,9 +51,8 @@ val check_suffix : string -> string -> bool
 
 val chop_suffix : string -> string -> string
 (** [chop_suffix name suff] removes the suffix [suff] from
-   the filename [name]. The behavior is undefined if [name] does not
-   end with the suffix [suff]. [chop_suffix_opt] is thus recommended
-   instead.
+    the filename [name].
+    @raise Invalid_argument if [name] does not end with the suffix [suff].
 *)
 
 val chop_suffix_opt: suffix:string -> string -> string option

stdlib/hashtbl.mli

@@ -133,7 +133,7 @@ val iter : ('a -> 'b -> unit) -> ('a, 'b) t -> unit
    of OCaml.  For randomized hash tables, the order of enumeration
    is entirely random.
 
-   The behavior is not defined if the hash table is modified
+   The behavior is not specified if the hash table is modified
    by [f] during the iteration.
 *)
 
@@ -166,7 +166,7 @@ val fold : ('a -> 'b -> 'c -> 'c) -> ('a, 'b) t -> 'c -> 'c
    of OCaml.  For randomized hash tables, the order of enumeration
    is entirely random.
 
-   The behavior is not defined if the hash table is modified
+   The behavior is not specified if the hash table is modified
    by [f] during the iteration.
 *)
 
@@ -246,7 +246,7 @@ val to_seq : ('a,'b) t -> ('a * 'b) Seq.t
     several bindings for the same key, they appear in reversed order of
     introduction, that is, the most recent binding appears first.
 
-    The behavior is not defined if the hash table is modified
+    The behavior is not specified if the hash table is modified
     during the iteration.
 
     @since 4.07 *)

stdlib/int32.mli

@@ -147,8 +147,9 @@ external of_float : float -> int32
   [@@unboxed] [@@noalloc]
 (** Convert the given floating-point number to a 32-bit integer,
    discarding the fractional part (truncate towards 0).
-   The result of the conversion is undefined if, after truncation,
-   the number is outside the range \[{!Int32.min_int}, {!Int32.max_int}\]. *)
+   If the truncated floating-point number is outside the range
+   \[{!Int32.min_int}, {!Int32.max_int}\], no exception is raised, and
+   an unspecified, platform-dependent integer is returned. *)
 
 external to_float : int32 -> float
   = "caml_int32_to_float" "caml_int32_to_float_unboxed"

stdlib/int64.mli

@@ -146,8 +146,9 @@ external of_float : float -> int64
   [@@unboxed] [@@noalloc]
 (** Convert the given floating-point number to a 64-bit integer,
    discarding the fractional part (truncate towards 0).
-   The result of the conversion is undefined if, after truncation,
-   the number is outside the range \[{!Int64.min_int}, {!Int64.max_int}\]. *)
+   If the truncated floating-point number is outside the range
+   \[{!Int64.min_int}, {!Int64.max_int}\], no exception is raised, and
+   an unspecified, platform-dependent integer is returned. *)
 
 external to_float : int64 -> float
   = "caml_int64_to_float" "caml_int64_to_float_unboxed"

stdlib/moreLabels.mli

@@ -150,7 +150,7 @@ module Hashtbl : sig
      of OCaml.  For randomized hash tables, the order of enumeration
      is entirely random.
 
-     The behavior is not defined if the hash table is modified
+     The behavior is not specified if the hash table is modified
      by [f] during the iteration.
   *)
 
@@ -183,7 +183,7 @@ module Hashtbl : sig
      of OCaml.  For randomized hash tables, the order of enumeration
      is entirely random.
 
-     The behavior is not defined if the hash table is modified
+     The behavior is not specified if the hash table is modified
      by [f] during the iteration.
   *)
 
@@ -263,7 +263,7 @@ module Hashtbl : sig
       several bindings for the same key, they appear in reversed order of
       introduction, that is, the most recent binding appears first.
 
-      The behavior is not defined if the hash table is modified
+      The behavior is not specified if the hash table is modified
       during the iteration.
 
       @since 4.07 *)

stdlib/nativeint.mli

@@ -164,9 +164,9 @@ external of_float : float -> nativeint
   [@@unboxed] [@@noalloc]
 (** Convert the given floating-point number to a native integer,
    discarding the fractional part (truncate towards 0).
-   The result of the conversion is undefined if, after truncation,
-   the number is outside the range
-   \[{!Nativeint.min_int}, {!Nativeint.max_int}\]. *)
+   If the truncated floating-point number is outside the range
+   \[{!Nativeint.min_int}, {!Nativeint.max_int}\], no exception is raised,
+   and an unspecified, platform-dependent integer is returned. *)
 
 external to_float : nativeint -> float
   = "caml_nativeint_to_float" "caml_nativeint_to_float_unboxed"

stdlib/queue.mli

@@ -95,7 +95,7 @@ val transfer : 'a t -> 'a t -> unit
 
 val to_seq : 'a t -> 'a Seq.t
 (** Iterate on the queue, in front-to-back order.
-    The behavior is not defined if the queue is modified
+    The behavior is not specified if the queue is modified
     during the iteration.
     @since 4.07 *)
 

stdlib/templates/hashtbl.template.mli

@@ -133,7 +133,7 @@ val iter : f:(key:'a -> data:'b -> unit) -> ('a, 'b) t -> unit
    of OCaml.  For randomized hash tables, the order of enumeration
    is entirely random.
 
-   The behavior is not defined if the hash table is modified
+   The behavior is not specified if the hash table is modified
    by [f] during the iteration.
 *)
 
@@ -166,7 +166,7 @@ val fold : f:(key:'a -> data:'b -> 'c -> 'c) -> ('a, 'b) t -> init:'c -> 'c
    of OCaml.  For randomized hash tables, the order of enumeration
    is entirely random.
 
-   The behavior is not defined if the hash table is modified
+   The behavior is not specified if the hash table is modified
    by [f] during the iteration.
 *)
 
@@ -246,7 +246,7 @@ val to_seq : ('a,'b) t -> ('a * 'b) Seq.t
     several bindings for the same key, they appear in reversed order of
     introduction, that is, the most recent binding appears first.
 
-    The behavior is not defined if the hash table is modified
+    The behavior is not specified if the hash table is modified
     during the iteration.
 
     @since 4.07 *)