comments and doc for CCDeque

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
+(* This file is free software, part of containers. See file "license" for more details. *)
-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.
-*)
 
 (** {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;

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
+(* This file is free software, part of containers. See file "license" for more details. *)
-modification, are permitted provided that the following conditions are met:
 
-Redistributions of source code must retain the above copyright notice, this
+(** {1 Imperative deque}
-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
+    This structure provides fast access to its front and back elements,
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+    with O(1) operations*)
-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} *)
 
 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
+(** List of elements, in order. Less efficient than {!to_rev_list}.
-    {b warning: not tailrec}
     @since 0.13 *)
 
 val to_rev_list : 'a t -> 'a list