From ee0cac7dab824cfdb51e9cdc9423c96babe7bfad Mon Sep 17 00:00:00 2001 From: Hannes Mehnert Date: Wed, 22 May 2024 11:14:57 +0200 Subject: [PATCH 1/3] adapt the V6 of_string* docstrings from the V4 versions, fixes #81 --- .ocamlformat | 2 +- lib/ipaddr.mli | 19 +++++++++++-------- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/.ocamlformat b/.ocamlformat index 4076c83..009983a 100644 --- a/.ocamlformat +++ b/.ocamlformat @@ -1,4 +1,4 @@ -version = 0.26.0 +version = 0.26.2 profile = conventional break-infix = fit-or-vertical parse-docstrings = true diff --git a/lib/ipaddr.mli b/lib/ipaddr.mli index 95124ed..6faa699 100644 --- a/lib/ipaddr.mli +++ b/lib/ipaddr.mli @@ -338,14 +338,15 @@ module V6 : sig (** {3 Text string conversion} *) - val of_string_exn : string -> t - (** [of_string_exn ipv6_string] is the address represented by [ipv6_string]. - Raises {!Parse_error} if [ipv6_string] is not a valid representation of an - IPv6 address. *) - val of_string : string -> (t, [> `Msg of string ]) result - (** Same as [of_string_exn] but returns an option type instead of raising an - exception. *) + (** [of_string ipv6_string] is the address represented by the human-readable + IPv6 address [ipv6_string]. Returns a human-readable error string if + parsing failed. *) + + val of_string_exn : string -> t + (** [of_string_exn ipv6_string] is the address represented by the + human-readable IPv6 address [ipv6_string]. Raises {!Parse_error} if + [ipv6_string] is not exactly 16 bytes long. *) val with_port_of_string : default:int -> string -> (t * int, [> `Msg of string ]) result @@ -359,7 +360,9 @@ module V6 : sig val of_string_raw : string -> int ref -> t (** Same as [of_string_exn] but takes as an extra argument the offset into the - string for reading. *) + string for reading. [off] will be mutated to an unspecified value during + the function call. Raises {!Parse_error} if it is an invalid or truncated + IP address. *) val to_string : t -> string (** [to_string ipv6] is the string representation of [ipv6], i.e. From 2b9be67818a19658a2bb2b30414ecb89e8b705f5 Mon Sep 17 00:00:00 2001 From: Hannes Mehnert Date: Wed, 22 May 2024 11:33:14 +0200 Subject: [PATCH 2/3] minor: remove local map_result, use Stdlib instead --- lib/ipaddr.ml | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/lib/ipaddr.ml b/lib/ipaddr.ml index 64e74f4..617bb50 100644 --- a/lib/ipaddr.ml +++ b/lib/ipaddr.ml @@ -23,7 +23,6 @@ let try_with_result fn a = try Ok (fn a) with Parse_error (msg, _) -> Error (`Msg ("Ipaddr: " ^ msg)) let failwith_msg = function Ok x -> x | Error (`Msg m) -> failwith m -let map_result v f = match v with Ok v -> Ok (f v) | Error _ as e -> e let string_of_scope = function | Point -> "point" @@ -1271,12 +1270,12 @@ let of_domain_name n = | _ -> None let succ = function - | V4 addr -> map_result (V4.succ addr) (fun v -> V4 v) - | V6 addr -> map_result (V6.succ addr) (fun v -> V6 v) + | V4 addr -> Result.map (fun v -> V4 v) (V4.succ addr) + | V6 addr -> Result.map (fun v -> V6 v) (V6.succ addr) let pred = function - | V4 addr -> map_result (V4.pred addr) (fun v -> V4 v) - | V6 addr -> map_result (V6.pred addr) (fun v -> V6 v) + | V4 addr -> Result.map (fun v -> V4 v) (V4.pred addr) + | V6 addr -> Result.map (fun v -> V6 v) (V6.pred addr) module Prefix = struct module Addr = struct From 50e8768ff9525883d7e3e9391eaf5a5eb024f129 Mon Sep 17 00:00:00 2001 From: Hannes Mehnert Date: Wed, 22 May 2024 11:42:44 +0200 Subject: [PATCH 3/3] further clarifications --- lib/ipaddr.mli | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/lib/ipaddr.mli b/lib/ipaddr.mli index 6faa699..d3b8a15 100644 --- a/lib/ipaddr.mli +++ b/lib/ipaddr.mli @@ -59,7 +59,7 @@ module V4 : sig val of_string_exn : string -> t (** [of_string_exn s] is the address {!t} represented as a human-readable IPv4 - address [s]. Raises {!Parse_error} if [s] is not exactly 4 bytes long. *) + address [s]. Raises {!Parse_error} if [s] is invalid or truncated. *) val of_string_raw : string -> int ref -> t (** [of_string_raw s off] acts as {!of_string_exn} but takes as an extra @@ -93,16 +93,15 @@ module V4 : sig human-readable [192.168.1.2] address. *) val of_octets : ?off:int -> string -> (t, [> `Msg of string ]) result - (** [of_octets ?off s] is the address {!t} represented by the IPv4 octets - represented by [s] starting from offset [off] within the string. [s] must - be at least [off+4] bytes long. Returns a human-readable error string if - parsing fails. [off] defaults to 0. *) + (** [of_octets ?off s] is the IPv4 address {!t} represented by the octets in + [s] starting from offset [off] within the string. Returns a human-readable + error string if [s] is not at least [off+4] bytes long. [off] defaults to + 0. *) val of_octets_exn : ?off:int -> string -> t (** [of_octets_exn ipv4_octets] is the IPv4 address represented by - [ipv4_octets] starting from offset [off] within the string. Raises - {!Parse_error} if [ipv4_octets] is not at least [off+4] bytes long. [off] - defaults to 0. *) + [ipv4_octets] starting from offset [off]. Raises {!Parse_error} if + [ipv4_octets] is not at least [off+4] bytes long. [off] defaults to 0. *) val write_octets : ?off:int -> t -> bytes -> (unit, [> `Msg of string ]) result @@ -346,7 +345,7 @@ module V6 : sig val of_string_exn : string -> t (** [of_string_exn ipv6_string] is the address represented by the human-readable IPv6 address [ipv6_string]. Raises {!Parse_error} if - [ipv6_string] is not exactly 16 bytes long. *) + [ipv6_string] is invalid or truncated. *) val with_port_of_string : default:int -> string -> (t * int, [> `Msg of string ]) result @@ -379,14 +378,16 @@ module V6 : sig (** {3 Octets conversion} *) + val of_octets : ?off:int -> string -> (t, [> `Msg of string ]) result + (** [of_octets ?off s] is the IPv6 address {!t} represented by the octets [s] + starting from offset [off] within the string. Returns a human-readable + error string if [s] is not at least [off+16] bytes long. [off] defaults to + 0. *) + val of_octets_exn : ?off:int -> string -> t - (** [of_octets_exn ?off ipv6_octets] is the address represented by + (** [of_octets_exn ?off ipv6_octets] is the IPv6 address represented by [ipv6_octets], starting from offset [off]. Raises {!Parse_error} if - [ipv6_octets] is not a valid representation of an IPv6 address. *) - - val of_octets : ?off:int -> string -> (t, [> `Msg of string ]) result - (** Same as {!of_octets_exn} but returns an result type instead of raising an - exception. *) + [ipv6_octets] is not at least [off+16] bytes long. [off] defaults to 0. *) val write_octets_exn : ?off:int -> t -> bytes -> unit (** [write_octets_exn ?off ipv6 b] writes 16 bytes that encode [ipv6] into [b]