From 04ce0c1f5def7b8112449b8df674b4e7c4e748ba Mon Sep 17 00:00:00 2001 From: Alex Coventry Date: Sun, 20 Aug 2017 04:07:07 +0000 Subject: [PATCH] Utils: various doc improvements --- src/minutils/hex_encode.ml | 44 ++++---------------------------------- src/minutils/mBytes.mli | 8 +++++++ src/minutils/utils.ml | 2 +- src/minutils/utils.mli | 41 ++++++++++++++++++++++++++++++----- 4 files changed, 49 insertions(+), 46 deletions(-) diff --git a/src/minutils/hex_encode.ml b/src/minutils/hex_encode.ml index 3dc05256e..906b15e93 100644 --- a/src/minutils/hex_encode.ml +++ b/src/minutils/hex_encode.ml @@ -9,7 +9,8 @@ (* Tezos Utility library - Hexadecimal encoding *) -(* From OCaml's stdlib. See [Digest.to_hex] *) +(* From OCaml's stdlib. See [Digest.to_hex], and [hex_of_bytes], [hex_encode] + below for examples. *) let gen_encode length get s = let n = length s in let result = Bytes.create (n*2) in @@ -21,7 +22,8 @@ let gen_encode length get s = let hex_of_bytes = gen_encode MBytes.length MBytes.get_uint8 let hex_encode = gen_encode String.length (fun s i -> int_of_char s.[i]) -(* From OCaml's stdlib. See [Digest.from_hex]. *) +(* From OCaml's stdlib. See [Digest.from_hex], and [hex_decode], [bytes_of_hex] + below for examples. *) let gen_decode create set h = let n = String.length h in if n mod 2 <> 0 then invalid_arg ("hex_decode: " ^ h); @@ -45,41 +47,3 @@ let hex_decode s = let bytes_of_hex s = gen_decode MBytes.create MBytes.set_int8 s - -(* -let hex_bytes = - let open Data_encoding in - let schema = - let open Json_schema in - create - { title = None ; - description = None ; - default = None; - enum = None; - kind = String { - pattern = Some "^[a-zA-Z0-9]+$"; - min_length = 0; - max_length = None; - }; - format = None ; - id = None } in - conv ~schema hex_of_bytes (Json.wrap_error bytes_of_hex) string - -let sha256 = - let open Data_encoding in - let schema = - let open Json_schema in - create - { title = None ; - description = None ; - default = None; - enum = None; - kind = String { - pattern = Some "^[a-zA-Z0-9]+$"; - min_length = 64; - max_length = Some 64; - }; - format = Some "sha256" ; - id = None } in - conv ~schema hex_of_bytes (Json.wrap_error bytes_of_hex) string -*) diff --git a/src/minutils/mBytes.mli b/src/minutils/mBytes.mli index 93a55267a..52adf6990 100644 --- a/src/minutils/mBytes.mli +++ b/src/minutils/mBytes.mli @@ -7,11 +7,18 @@ (* *) (**************************************************************************) +(** Low-level byte array querying and manipulation. + + Default layout for numeric operations is big-endian. + Little-endian operations in the LE submodule. **) + open Bigarray +(* Arrays are of characters, represented as uint8's, in row-major layout. *) type t = (char, int8_unsigned_elt, c_layout) Array1.t val create: int -> t +(** [create n] allocates and returns an array of size [n] **) val length: t -> int @@ -143,3 +150,4 @@ val (>) : t -> t -> bool val compare : t -> t -> int val concat: t -> t -> t +(** Returns a new array with adjacent copies of the two input arrays **) diff --git a/src/minutils/utils.ml b/src/minutils/utils.ml index 54d24e972..8c44ebecc 100644 --- a/src/minutils/utils.ml +++ b/src/minutils/utils.ml @@ -307,5 +307,5 @@ let parse_addr_port s = check_port port ; addr, port | _pos -> - invalid_arg "split_url_port: IPv6 addresses must be bracketed" + invalid_arg "Utils.parse_addr_port: IPv6 addresses must be bracketed" end diff --git a/src/minutils/utils.mli b/src/minutils/utils.mli index 2ba60cd35..af1e62e47 100644 --- a/src/minutils/utils.mli +++ b/src/minutils/utils.mli @@ -18,32 +18,57 @@ val split_path: string -> string list string, if [limit] is passed, stops after [limit] split(s). *) val split: char -> ?dup:bool -> ?limit: int -> string -> string list +(** [Some (f x)] if input is [Some x], or [None] if it's [None] **) val map_option: f:('a -> 'b) -> 'a option -> 'b option + +(** [(f x)] if input is [Some x], or [None] if it's [None] **) val apply_option: f:('a -> 'b option) -> 'a option -> 'b option + +(** Call [(f x)] if input is [Some x], noop if it's [None] **) val iter_option: f:('a -> unit) -> 'a option -> unit + +(** [x] if input is [Some x], default if it's [None] **) val unopt: default:'a -> 'a option -> 'a + +(** [unopt_map f d x] is [y] if [x] is [Some y], [d] if [x] is [None] **) val unopt_map: f:('a -> 'b) -> default:'b -> 'a option -> 'b + +(** [x] for elements [Some x] in input. [None]s are dropped. **) val unopt_list: 'a option list -> 'a list + +(** First input of form [Some x], or [None] if none **) val first_some: 'a option -> 'a option -> 'a option +(** Print a paragraph in a box **) val display_paragraph: Format.formatter -> string -> unit (** [remove nb list] remove the first [nb] elements from the list [list]. *) val remove_elem_from_list: int -> 'a list -> 'a list + +(** Return pair (list of first n items, remaining items) **) val split_list_at: int -> 'a list -> 'a list * 'a list +(** [true] if input has prefix **) val has_prefix: prefix:string -> string -> bool + +(** Some (input with [prefix] removed), if string has [prefix], else [None] **) val remove_prefix: prefix:string -> string -> string option + +(** Length of common prefix of input strings *) val common_prefix: string -> string -> int - +(** [filter_map f l] is [[y for x in l where (f x) = Some y]] **) val filter_map: ('a -> 'b option) -> 'a list -> 'b list -(** [list_rev_sub l n] is (List.rev l) capped to max n elements *) +(** [list_rev_sub l n] is [List.rev l] capped to max [n] elements *) val list_rev_sub : 'a list -> int -> 'a list -(** [list_sub l n] is l capped to max n elements *) +(** [list_sub l n] is [l] capped to max [n] elements *) val list_sub: 'a list -> int -> 'a list + +(** Like [List.hd], but [Some hd] or [None] if empty **) val list_hd_opt: 'a list -> 'a option + +(** Last elt of list, or raise Not_found if empty **) val list_last_exn: 'a list -> 'a (** [merge_filter_list2 ~compare ~f l1 l2] merges two lists ordered by [compare] @@ -65,9 +90,13 @@ val merge_list2 : 'a list -> 'a list -> 'a list +(** [finalize f g ] ensures g() called after f(), even if exception raised **) val finalize: (unit -> 'a) -> (unit -> unit) -> 'a +(** Return contents of file at given filename. **) val read_file: ?bin:bool -> string -> string + +(** [write_file p c] writes c to file at path p **) val write_file: ?bin:bool -> string -> string -> unit (** Compose functions from right to left. *) @@ -76,9 +105,10 @@ val (<<) : ('b -> 'c) -> ('a -> 'b) -> 'a -> 'c (** Sequence: [i--j] is the sequence [i;i+1;...;j-1;j] *) val (--) : int -> int -> int list +(** [repeat n x] is a list of [n] [x]'s **) val repeat: int -> 'a -> 'a list -(** [take_n n l] returns the [n] first elements of [n]. When [compare] +(** [take_n n l] returns the [n] first elements of [l]. When [compare] is provided, it returns the [n] greatest element of [l]. *) val take_n: ?compare:('a -> 'a -> int) -> int -> 'a list -> 'a list @@ -90,8 +120,9 @@ module Bounded(E: Set.OrderedType) : sig val get: t -> E.t list end +(** [select n l] is ([n]th element of [l], [l] without that element) **) val select: int -> 'a list -> 'a * 'a list -(** [split_url_port uri] is (node, service) where [node] is the DNS or +(** [parse_addr_port uri] is (node, service) where [node] is the DNS or IP and service is the optional port number or service name. *) val parse_addr_port: string -> string * string