(** Byte range management for partial downloads and chunked caching

    This module provides utilities for working with byte ranges,
    primarily used for HTTP Range requests and partial file caching.
    Ranges are inclusive on both ends (e.g., bytes 0-99 includes 100 bytes).

    {2 Example}

    {[
    let r1 = Range.create ~start:0L ~end_:999L in
    let r2 = Range.create ~start:1000L ~end_:1999L in
    assert (Range.adjacent r1 r2 = true);
    assert (Range.length r1 = 1000L);
    match Range.merge r1 r2 with
    | Some merged -> assert (Range.length merged = 2000L)
    | None -> failwith "Should merge"
    ]}*)

(** A byte range with inclusive start and end positions.
    For example, range [0,99] includes bytes 0 through 99 (100 bytes total). *)
type t

(** Create a range from start to end (inclusive) *)
val create : start:int64 -> end_:int64 -> t

(** Get the start position *)
val start : t -> int64

(** Get the end position (inclusive) *)
val end_ : t -> int64

(** Calculate the length of a range *)
val length : t -> int64

(** Check if two ranges are adjacent (no gap between them) *)
val adjacent : t -> t -> bool

(** Check if two ranges overlap *)
val overlaps : t -> t -> bool

(** Check if a range contains a position *)
val contains : t -> int64 -> bool

(** Merge two ranges if they overlap or are adjacent *)
val merge : t -> t -> t option

(** Compare ranges by start position *)
val compare : t -> t -> int

(** Convert to string format "start-end" *)
val to_string : t -> string

(** Parse from string format "start-end" *)
val of_string : string -> t option

(** Pretty printer *)
val pp : Format.formatter -> t -> unit