mirror of
https://github.com/c-cube/ocaml-containers.git
synced 2025-12-10 13:13:56 -05:00
87 lines
2.6 KiB
OCaml
87 lines
2.6 KiB
OCaml
|
|
(* This file is free software, part of containers. See file "license" for more details. *)
|
|
|
|
(** {1 List Zipper}
|
|
|
|
@since 1.0 *)
|
|
|
|
type 'a t = 'a list * 'a list
|
|
(** The pair [l, r] represents the list [List.rev_append l r], but
|
|
with the focus on [r]. *)
|
|
|
|
val empty : 'a t
|
|
(** Empty zipper *)
|
|
|
|
val is_empty : _ t -> bool
|
|
(** Empty zipper? Returns true iff the two lists are empty. *)
|
|
|
|
(*$T
|
|
(is_empty empty)
|
|
not ([42] |> make |> right |> is_empty)
|
|
*)
|
|
|
|
val to_list : 'a t -> 'a list
|
|
(** Convert the zipper back to a list.
|
|
[to_list (l,r)] is [List.rev_append l r] *)
|
|
|
|
val to_rev_list : 'a t -> 'a list
|
|
(** Convert the zipper back to a {i reversed} list.
|
|
In other words, [to_list (l,r)] is [List.rev_append r l] *)
|
|
|
|
val make : 'a list -> 'a t
|
|
(** Create a zipper pointing at the first element of the list *)
|
|
|
|
val left : 'a t -> 'a t
|
|
(** Go to the left, or do nothing if the zipper is already at leftmost pos *)
|
|
|
|
val left_exn : 'a t -> 'a t
|
|
(** Go to the left, or
|
|
@raise Invalid_argument if the zipper is already at leftmost pos *)
|
|
|
|
val right : 'a t -> 'a t
|
|
(** Go to the right, or do nothing if the zipper is already at rightmost pos *)
|
|
|
|
val right_exn : 'a t -> 'a t
|
|
(** Go to the right, or
|
|
@raise Invalid_argument if the zipper is already at rightmost pos *)
|
|
|
|
val modify : ('a option -> 'a option) -> 'a t -> 'a t
|
|
(** Modify the current element, if any, by returning a new element, or
|
|
returning [None] if the element is to be deleted *)
|
|
|
|
val insert : 'a -> 'a t -> 'a t
|
|
(** Insert an element at the current position. If an element was focused,
|
|
[insert x l] adds [x] just before it, and focuses on [x] *)
|
|
|
|
val remove : 'a t -> 'a t
|
|
(** [remove l] removes the current element, if any. *)
|
|
|
|
val is_focused : _ t -> bool
|
|
(** Is the zipper focused on some element? That is, will {!focused}
|
|
return a [Some v]? *)
|
|
|
|
val focused : 'a t -> 'a option
|
|
(** Returns the focused element, if any. [focused zip = Some _] iff
|
|
[empty zip = false] *)
|
|
|
|
val focused_exn : 'a t -> 'a
|
|
(** Returns the focused element, or
|
|
@raise Not_found if the zipper is at an end *)
|
|
|
|
val drop_before : 'a t -> 'a t
|
|
(** Drop every element on the "left" (calling {!left} then will do nothing). *)
|
|
|
|
val drop_after : 'a t -> 'a t
|
|
(** Drop every element on the "right" (calling {!right} then will do nothing),
|
|
keeping the focused element, if any. *)
|
|
|
|
val drop_after_and_focused : 'a t -> 'a t
|
|
(** Drop every element on the "right" (calling {!right} then will do nothing),
|
|
{i including} the focused element if it is present. *)
|
|
|
|
(*$=
|
|
([1], [2]) (drop_after ([1], [2;3]))
|
|
([1], []) (drop_after ([1], []))
|
|
([1], []) (drop_after_and_focused ([1], [2;3]))
|
|
*)
|
|
|