From b9f7d2e18a4d95f2c455e46eb61c7088d1114180 Mon Sep 17 00:00:00 2001 From: Simon Cruanes Date: Tue, 19 Apr 2016 00:19:13 +0200 Subject: [PATCH] comments and doc for CCDeque --- src/data/CCDeque.ml | 29 +++++------------------------ src/data/CCDeque.mli | 43 ++++++++++++++----------------------------- 2 files changed, 19 insertions(+), 53 deletions(-) diff --git a/src/data/CCDeque.ml b/src/data/CCDeque.ml index b2ae66d3..8de3afcb 100644 --- a/src/data/CCDeque.ml +++ b/src/data/CCDeque.ml @@ -1,27 +1,5 @@ -(* -Copyright (c) 2013, Simon Cruanes -All rights reserved. -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -Redistributions of source code must retain the above copyright notice, this -list of conditions and the following disclaimer. Redistributions in binary -form must reproduce the above copyright notice, this list of conditions and the -following disclaimer in the documentation and/or other materials provided with -the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -*) +(* This file is free software, part of containers. See file "license" for more details. *) (** {1 Imperative deque} *) @@ -37,7 +15,10 @@ type 'a node = { mutable next : 'a node; mutable prev : 'a node; } -(** Linked list of cells *) +(** Linked list of cells. + + invariant: only the first and last cells are allowed to + be anything but [Three] (all the intermediate ones are [Three]) *) type 'a t = { mutable cur : 'a node; diff --git a/src/data/CCDeque.mli b/src/data/CCDeque.mli index e18e6eb7..c0bde886 100644 --- a/src/data/CCDeque.mli +++ b/src/data/CCDeque.mli @@ -1,29 +1,10 @@ -(* -Copyright (c) 2013, Simon Cruanes -All rights reserved. -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: +(* This file is free software, part of containers. See file "license" for more details. *) -Redistributions of source code must retain the above copyright notice, this -list of conditions and the following disclaimer. Redistributions in binary -form must reproduce the above copyright notice, this list of conditions and the -following disclaimer in the documentation and/or other materials provided with -the distribution. +(** {1 Imperative deque} -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -*) - -(** {1 Imperative deque} *) + This structure provides fast access to its front and back elements, + with O(1) operations*) type 'a t (** Contains 'a elements, queue in both ways *) @@ -76,10 +57,12 @@ val take_front : 'a t -> 'a val append_front : into:'a t -> 'a t -> unit (** [append_front ~into q] adds all elements of [q] at the front of [into] + O(length q) in time @since 0.13 *) val append_back : into:'a t -> 'a t -> unit -(** [append_back ~into q] adds all elements of [q] at the back of [into] +(** [append_back ~into q] adds all elements of [q] at the back of [into]. + O(length q) in time @since 0.13 *) val iter : ('a -> unit) -> 'a t -> unit @@ -100,6 +83,7 @@ val of_seq : 'a sequence -> 'a t {!add_seq_back} instead *) val to_seq : 'a t -> 'a sequence +(** iterate on the elements *) val of_gen : 'a gen -> 'a t (** [of_gen g] makes a deque containing the elements of [g] @@ -111,24 +95,25 @@ val to_gen : 'a t -> 'a gen val add_seq_front : 'a t -> 'a sequence -> unit (** [add_seq_front q seq] adds elements of [seq] into the front of [q], - in reverse order + in reverse order. + O(n) in time, where [n] is the number of elements to add. @since 0.13 *) val add_seq_back : 'a t -> 'a sequence -> unit (** [add_seq_back q seq] adds elements of [seq] into the back of [q], - in order + in order. + O(n) in time, where [n] is the number of elements to add. @since 0.13 *) val copy : 'a t -> 'a t -(** Fresh copy *) +(** Fresh copy, O(n) in time *) val of_list : 'a list -> 'a t (** Conversion from list, in order @since 0.13 *) val to_list : 'a t -> 'a list -(** List of elements, in order - {b warning: not tailrec} +(** List of elements, in order. Less efficient than {!to_rev_list}. @since 0.13 *) val to_rev_list : 'a t -> 'a list