// Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT // file at the top-level directory of this distribution and at // http://rust-lang.org/COPYRIGHT. // // Licensed under the Apache License, Version 2.0 or the MIT license // , at your // option. This file may not be copied, modified, or distributed // except according to those terms. //! A doubly-linked list with owned nodes. //! //! The DList allows pushing and popping elements at either end. // DList is constructed like a singly-linked list over the field `next`. // including the last link being None; each Node owns its `next` field. // // Backlinks over DList::prev are raw pointers that form a full chain in // the reverse direction. use std::cast; use std::cmp; use std::ptr; use std::util; use std::iterator::FromIterator; use container::Deque; /// A doubly-linked list pub struct DList { priv length: uint, priv list_head: Link, priv list_tail: Rawlink>, } type Link = Option<~Node>; struct Rawlink { priv p: *mut T } struct Node { priv next: Link, priv prev: Rawlink>, priv value: T, } /// DList iterator pub struct ForwardIterator<'self, T> { priv list: &'self DList, priv next: &'self Link, priv nelem: uint, } /// DList reverse iterator pub struct ReverseIterator<'self, T> { priv list: &'self DList, priv next: Rawlink>, priv nelem: uint, } /// DList mutable iterator pub struct MutForwardIterator<'self, T> { priv list: &'self mut DList, priv curs: Rawlink>, priv nelem: uint, } /// DList mutable reverse iterator pub struct MutReverseIterator<'self, T> { priv list: &'self mut DList, priv next: Rawlink>, priv nelem: uint, } /// DList consuming iterator pub struct ConsumeIterator { priv list: DList } /// DList reverse consuming iterator pub struct ConsumeRevIterator { priv list: DList } /// Rawlink is a type like Option but for holding a raw pointer impl Rawlink { /// Like Option::None for Rawlink fn none() -> Rawlink { Rawlink{p: ptr::mut_null()} } /// Like Option::Some for Rawlink fn some(n: &mut T) -> Rawlink { Rawlink{p: ptr::to_mut_unsafe_ptr(n)} } /// Convert the `Rawlink` into an Option value fn resolve_immut(&self) -> Option<&T> { unsafe { self.p.to_option() } } /// Convert the `Rawlink` into an Option value fn resolve(&mut self) -> Option<&mut T> { if self.p.is_null() { None } else { Some(unsafe { cast::transmute(self.p) }) } } } /// Set the .prev field on `next`, then return `Some(next)` fn link_with_prev(mut next: ~Node, prev: Rawlink>) -> Link { next.prev = prev; Some(next) } impl Container for DList { /// O(1) fn is_empty(&self) -> bool { self.list_head.is_none() } /// O(1) fn len(&self) -> uint { self.length } } impl Mutable for DList { /// Remove all elements from the DList /// /// O(N) fn clear(&mut self) { *self = DList::new() } } impl Deque for DList { /// Provide a reference to the front element, or None if the list is empty fn front<'a>(&'a self) -> Option<&'a T> { self.list_head.chain_ref(|x| Some(&x.value)) } /// Provide a mutable reference to the front element, or None if the list is empty fn front_mut<'a>(&'a mut self) -> Option<&'a mut T> { match self.list_head { None => None, Some(ref mut head) => Some(&mut head.value), } } /// Provide a reference to the back element, or None if the list is empty fn back<'a>(&'a self) -> Option<&'a T> { match self.list_tail.resolve_immut() { None => None, Some(tail) => Some(&tail.value), } } /// Provide a mutable reference to the back element, or None if the list is empty fn back_mut<'a>(&'a mut self) -> Option<&'a mut T> { match self.list_tail.resolve() { None => None, Some(tail) => Some(&mut tail.value), } } /// Add an element last in the list /// /// O(1) fn push_back(&mut self, elt: T) { match self.list_tail.resolve() { None => return self.push_front(elt), Some(tail) => { let mut new_tail = ~Node{value: elt, next: None, prev: self.list_tail}; self.list_tail = Rawlink::some(new_tail); tail.next = Some(new_tail); } } self.length += 1; } /// Remove the last element and return it, or None if the list is empty /// /// O(1) #[inline] fn pop_back(&mut self) -> Option { match self.list_tail.resolve() { None => None, Some(tail) => { self.length -= 1; let tail_own = match tail.prev.resolve() { None => { self.list_tail = Rawlink::none(); self.list_head.swap_unwrap() }, Some(tail_prev) => { self.list_tail = tail.prev; tail_prev.next.swap_unwrap() } }; Some(tail_own.value) } } } /// Add an element first in the list /// /// O(1) fn push_front(&mut self, elt: T) { let mut new_head = ~Node{value: elt, next: None, prev: Rawlink::none()}; match self.list_head { None => { self.list_tail = Rawlink::some(new_head); self.list_head = Some(new_head); } Some(ref mut head) => { head.prev = Rawlink::some(new_head); util::swap(head, &mut new_head); head.next = Some(new_head); } } self.length += 1; } /// Remove the first element and return it, or None if the list is empty /// /// O(1) fn pop_front(&mut self) -> Option { match util::replace(&mut self.list_head, None) { None => None, Some(old_head) => { self.length -= 1; match *old_head { Node{value: value, next: Some(next), prev: _} => { self.list_head = link_with_prev(next, Rawlink::none()); Some(value) } Node{value: value, next: None, prev: _} => { self.list_tail = Rawlink::none(); Some(value) } } } } } } impl DList { /// Create an empty DList #[inline] pub fn new() -> DList { DList{list_head: None, list_tail: Rawlink::none(), length: 0} } /// Add all elements from `other` to the end of the list /// /// O(1) pub fn append(&mut self, other: DList) { match self.list_tail.resolve() { None => *self = other, Some(tail) => { match other { DList{list_head: None, list_tail: _, length: _} => return, DList{list_head: Some(node), list_tail: o_tail, length: o_length} => { tail.next = link_with_prev(node, self.list_tail); self.list_tail = o_tail; self.length += o_length; } } } } } /// Add all elements from `other` to the beginning of the list /// /// O(1) pub fn prepend(&mut self, mut other: DList) { util::swap(self, &mut other); self.append(other); } /// Insert `elt` before the first `x` in the list where `f(x, elt)` is true, /// or at the end. /// /// O(N) #[inline] pub fn insert_when(&mut self, elt: T, f: &fn(&T, &T) -> bool) { { let mut it = self.mut_iter(); loop { match it.next() { None => break, Some(x) => if f(x, &elt) { it.insert_before(elt); return } } } } self.push_back(elt); } /// Merge, using the function `f`; take `a` if `f(a, b)` is true, else `b`. /// /// O(max(N, M)) pub fn merge(&mut self, mut other: DList, f: &fn(&T, &T) -> bool) { { let mut it = self.mut_iter(); loop { match (it.next(), other.front()) { (None , _ ) => break, (_ , None ) => return, (Some(x), Some(y)) => if f(x, y) { loop } } it.insert_before(other.pop_front().unwrap()); } } self.append(other); } /// Provide a forward iterator pub fn iter<'a>(&'a self) -> ForwardIterator<'a, T> { ForwardIterator{nelem: self.len(), list: self, next: &self.list_head} } /// Provide a reverse iterator pub fn rev_iter<'a>(&'a self) -> ReverseIterator<'a, T> { ReverseIterator{nelem: self.len(), list: self, next: self.list_tail} } /// Provide a forward iterator with mutable references pub fn mut_iter<'a>(&'a mut self) -> MutForwardIterator<'a, T> { MutForwardIterator{nelem: self.len(), list: self, curs: Rawlink::none()} } /// Provide a reverse iterator with mutable references pub fn mut_rev_iter<'a>(&'a mut self) -> MutReverseIterator<'a, T> { MutReverseIterator{nelem: self.len(), list: self, next: self.list_tail} } /// Consume the list into an iterator yielding elements by value pub fn consume_iter(self) -> ConsumeIterator { ConsumeIterator{list: self} } /// Consume the list into an iterator yielding elements by value, in reverse pub fn consume_rev_iter(self) -> ConsumeRevIterator { ConsumeRevIterator{list: self} } } /// Insert sorted in ascending order /// /// O(N) impl DList { fn insert_ordered(&mut self, elt: T) { self.insert_when(elt, |a, b| a.cmp(b) != cmp::Less); } } impl<'self, A> Iterator<&'self A> for ForwardIterator<'self, A> { #[inline] fn next(&mut self) -> Option<&'self A> { match *self.next { None => None, Some(ref next) => { self.nelem -= 1; self.next = &next.next; Some(&next.value) } } } fn size_hint(&self) -> (uint, Option) { (self.nelem, Some(self.nelem)) } } // MutForwardIterator is different because it implements ListInsertion, // and can modify the list during traversal, used in insert_when and merge. impl<'self, A> Iterator<&'self mut A> for MutForwardIterator<'self, A> { #[inline] fn next(&mut self) -> Option<&'self mut A> { match self.curs.resolve() { None => { match self.list.list_head { None => None, Some(ref mut head) => { self.nelem -= 1; self.curs = Rawlink::some(*head); Some(&mut head.value) } } } Some(curs) => { match curs.next { None => None, Some(ref mut head) => { self.nelem -= 1; self.curs = Rawlink::some(*head); Some(&mut head.value) } } } } } fn size_hint(&self) -> (uint, Option) { (self.nelem, Some(self.nelem)) } } impl<'self, A> Iterator<&'self A> for ReverseIterator<'self, A> { #[inline] fn next(&mut self) -> Option<&'self A> { match self.next.resolve() { None => None, Some(prev) => { self.nelem -= 1; self.next = prev.prev; Some(&prev.value) } } } fn size_hint(&self) -> (uint, Option) { (self.nelem, Some(self.nelem)) } } impl<'self, A> Iterator<&'self mut A> for MutReverseIterator<'self, A> { #[inline] fn next(&mut self) -> Option<&'self mut A> { match self.next.resolve() { None => None, Some(prev) => { self.nelem -= 1; self.next = prev.prev; Some(&mut prev.value) } } } fn size_hint(&self) -> (uint, Option) { (self.nelem, Some(self.nelem)) } } /// Allow mutating the DList while iterating pub trait ListInsertion { /// Insert `elt` just previous to the most recently yielded element fn insert_before(&mut self, elt: A); /// Provide a reference to the next element, without changing the iterator fn peek_next<'a>(&'a mut self) -> Option<&'a mut A>; } impl<'self, A> ListInsertion for MutForwardIterator<'self, A> { fn insert_before(&mut self, elt: A) { match self.curs.resolve() { None => { self.list.push_front(elt); self.next(); } Some(node) => { let prev_node = match node.prev.resolve() { None => return self.list.push_front(elt), Some(prev) => prev, }; let mut ins_node = ~Node{value: elt, next: None, prev: Rawlink::none()}; let node_own = prev_node.next.swap_unwrap(); ins_node.next = link_with_prev(node_own, Rawlink::some(ins_node)); prev_node.next = link_with_prev(ins_node, Rawlink::some(prev_node)); self.list.length += 1; } } } fn peek_next<'a>(&'a mut self) -> Option<&'a mut A> { match self.curs.resolve() { None => self.list.front_mut(), Some(curs) => match curs.next { None => None, Some(ref mut node) => Some(&mut node.value), } } } } impl Iterator for ConsumeIterator { fn next(&mut self) -> Option { self.list.pop_front() } fn size_hint(&self) -> (uint, Option) { (self.list.length, Some(self.list.length)) } } impl Iterator for ConsumeRevIterator { fn next(&mut self) -> Option { self.list.pop_back() } fn size_hint(&self) -> (uint, Option) { (self.list.length, Some(self.list.length)) } } impl> FromIterator for DList { fn from_iterator(iterator: &mut T) -> DList { let mut ret = DList::new(); for iterator.advance |elt| { ret.push_back(elt); } ret } } impl Eq for DList { fn eq(&self, other: &DList) -> bool { self.len() == other.len() && self.iter().zip(other.iter()).all(|(a, b)| a.eq(b)) } fn ne(&self, other: &DList) -> bool { !self.eq(other) } } impl Clone for DList { fn clone(&self) -> DList { self.iter().transform(|x| x.clone()).collect() } } #[cfg(test)] pub fn check_links(list: &DList) { let mut len = 0u; let mut last_ptr: Option<&Node> = None; let mut node_ptr: &Node; match list.list_head { None => { assert_eq!(0u, list.length); return } Some(ref node) => node_ptr = &**node, } loop { match (last_ptr, node_ptr.prev.resolve_immut()) { (None , None ) => {} (None , _ ) => fail!("prev link for list_head"), (Some(p), Some(pptr)) => { assert_eq!(p as *Node, pptr as *Node); } _ => fail!("prev link is none, not good"), } match node_ptr.next { Some(ref next) => { last_ptr = Some(node_ptr); node_ptr = &**next; len += 1; } None => { len += 1; break; } } } assert_eq!(len, list.length); } #[cfg(test)] mod tests { use super::*; use std::rand; use std::int; use extra::test; #[test] fn test_basic() { let mut m = DList::new::<~int>(); assert_eq!(m.pop_front(), None); assert_eq!(m.pop_back(), None); assert_eq!(m.pop_front(), None); m.push_front(~1); assert_eq!(m.pop_front(), Some(~1)); m.push_back(~2); m.push_back(~3); assert_eq!(m.len(), 2); assert_eq!(m.pop_front(), Some(~2)); assert_eq!(m.pop_front(), Some(~3)); assert_eq!(m.len(), 0); assert_eq!(m.pop_front(), None); m.push_back(~1); m.push_back(~3); m.push_back(~5); m.push_back(~7); assert_eq!(m.pop_front(), Some(~1)); let mut n = DList::new(); n.push_front(2); n.push_front(3); { assert_eq!(n.front().unwrap(), &3); let x = n.front_mut().unwrap(); assert_eq!(*x, 3); *x = 0; } { assert_eq!(n.back().unwrap(), &2); let y = n.back_mut().unwrap(); assert_eq!(*y, 2); *y = 1; } assert_eq!(n.pop_front(), Some(0)); assert_eq!(n.pop_front(), Some(1)); } #[cfg(test)] fn generate_test() -> DList { list_from(&[0,1,2,3,4,5,6]) } #[cfg(test)] fn list_from(v: &[T]) -> DList { v.iter().transform(|x| copy *x).collect() } #[test] fn test_append() { { let mut m = DList::new(); let mut n = DList::new(); n.push_back(2); m.append(n); assert_eq!(m.len(), 1); assert_eq!(m.pop_back(), Some(2)); check_links(&m); } { let mut m = DList::new(); let n = DList::new(); m.push_back(2); m.append(n); assert_eq!(m.len(), 1); assert_eq!(m.pop_back(), Some(2)); check_links(&m); } let v = ~[1,2,3,4,5]; let u = ~[9,8,1,2,3,4,5]; let mut m = list_from(v); m.append(list_from(u)); check_links(&m); let sum = v + u; assert_eq!(sum.len(), m.len()); for sum.consume_iter().advance |elt| { assert_eq!(m.pop_front(), Some(elt)) } } #[test] fn test_prepend() { { let mut m = DList::new(); let mut n = DList::new(); n.push_back(2); m.prepend(n); assert_eq!(m.len(), 1); assert_eq!(m.pop_back(), Some(2)); check_links(&m); } let v = ~[1,2,3,4,5]; let u = ~[9,8,1,2,3,4,5]; let mut m = list_from(v); m.prepend(list_from(u)); check_links(&m); let sum = u + v; assert_eq!(sum.len(), m.len()); for sum.consume_iter().advance |elt| { assert_eq!(m.pop_front(), Some(elt)) } } #[test] fn test_iterator() { let m = generate_test(); for m.iter().enumerate().advance |(i, elt)| { assert_eq!(i as int, *elt); } let mut n = DList::new(); assert_eq!(n.iter().next(), None); n.push_front(4); let mut it = n.iter(); assert_eq!(it.size_hint(), (1, Some(1))); assert_eq!(it.next().unwrap(), &4); assert_eq!(it.size_hint(), (0, Some(0))); assert_eq!(it.next(), None); } #[test] fn test_rev_iter() { let m = generate_test(); for m.rev_iter().enumerate().advance |(i, elt)| { assert_eq!((6 - i) as int, *elt); } let mut n = DList::new(); assert_eq!(n.rev_iter().next(), None); n.push_front(4); let mut it = n.rev_iter(); assert_eq!(it.size_hint(), (1, Some(1))); assert_eq!(it.next().unwrap(), &4); assert_eq!(it.size_hint(), (0, Some(0))); assert_eq!(it.next(), None); } #[test] fn test_mut_iter() { let mut m = generate_test(); let mut len = m.len(); for m.mut_iter().enumerate().advance |(i, elt)| { assert_eq!(i as int, *elt); len -= 1; } assert_eq!(len, 0); let mut n = DList::new(); assert!(n.mut_iter().next().is_none()); n.push_front(4); let mut it = n.mut_iter(); assert_eq!(it.size_hint(), (1, Some(1))); assert!(it.next().is_some()); assert_eq!(it.size_hint(), (0, Some(0))); assert!(it.next().is_none()); } #[test] fn test_insert_prev() { let mut m = list_from(&[0,2,4,6,8]); let len = m.len(); { let mut it = m.mut_iter(); it.insert_before(-2); loop { match it.next() { None => break, Some(elt) => { it.insert_before(*elt + 1); match it.peek_next() { Some(x) => assert_eq!(*x, *elt + 2), None => assert_eq!(8, *elt), } } } } it.insert_before(0); it.insert_before(1); } check_links(&m); assert_eq!(m.len(), 3 + len * 2); assert_eq!(m.consume_iter().collect::<~[int]>(), ~[-2,1,0,3,2,5,4,7,6,9,0,1,8]); } #[test] fn test_merge() { let mut m = list_from([0, 1, 3, 5, 6, 7, 2]); let n = list_from([-1, 0, 0, 7, 7, 9]); let len = m.len() + n.len(); m.merge(n, |a, b| a <= b); assert_eq!(m.len(), len); check_links(&m); let res = m.consume_iter().collect::<~[int]>(); assert_eq!(res, ~[-1, 0, 0, 1, 0, 3, 5, 6, 7, 2, 7, 7, 9]); } #[test] fn test_insert_ordered() { let mut n = DList::new(); n.insert_ordered(1); assert_eq!(n.len(), 1); assert_eq!(n.pop_front(), Some(1)); let mut m = DList::new(); m.push_back(2); m.push_back(4); m.insert_ordered(3); check_links(&m); assert_eq!(~[2,3,4], m.consume_iter().collect::<~[int]>()); } #[test] fn test_mut_rev_iter() { let mut m = generate_test(); for m.mut_rev_iter().enumerate().advance |(i, elt)| { assert_eq!((6-i) as int, *elt); } let mut n = DList::new(); assert!(n.mut_rev_iter().next().is_none()); n.push_front(4); let mut it = n.mut_rev_iter(); assert!(it.next().is_some()); assert!(it.next().is_none()); } #[test] fn test_send() { let n = list_from([1,2,3]); do spawn { check_links(&n); assert_eq!(~[&1,&2,&3], n.iter().collect::<~[&int]>()); } } #[test] fn test_eq() { let mut n: DList = list_from([]); let mut m = list_from([]); assert_eq!(&n, &m); n.push_front(1); assert!(n != m); m.push_back(1); assert_eq!(&n, &m); } #[test] fn test_fuzz() { for 25.times { fuzz_test(3); fuzz_test(16); fuzz_test(189); } } #[cfg(test)] fn fuzz_test(sz: int) { let mut m = DList::new::(); let mut v = ~[]; for int::range(0i, sz) |i| { check_links(&m); let r: u8 = rand::random(); match r % 6 { 0 => { m.pop_back(); if v.len() > 0 { v.pop(); } } 1 => { m.pop_front(); if v.len() > 0 { v.shift(); } } 2 | 4 => { m.push_front(-i); v.unshift(-i); } 3 | 5 | _ => { m.push_back(i); v.push(i); } } } check_links(&m); let mut i = 0u; for m.consume_iter().zip(v.iter()).advance |(a, &b)| { i += 1; assert_eq!(a, b); } assert_eq!(i, v.len()); } #[bench] fn bench_collect_into(b: &mut test::BenchHarness) { let v = &[0, ..64]; do b.iter { let _: DList = v.iter().transform(|&x|x).collect(); } } #[bench] fn bench_collect_into_vec(b: &mut test::BenchHarness) { let v = &[0, ..64]; do b.iter { let _: ~[int] = v.iter().transform(|&x|x).collect(); } } #[bench] fn bench_push_front(b: &mut test::BenchHarness) { let mut m = DList::new::(); do b.iter { m.push_front(0); } } #[bench] fn bench_push_front_vec_size10(b: &mut test::BenchHarness) { let mut m = ~[0, ..10]; do b.iter { m.unshift(0); m.pop(); // to keep it fair, dont' grow the vec } } #[bench] fn bench_push_back(b: &mut test::BenchHarness) { let mut m = DList::new::(); do b.iter { m.push_back(0); } } #[bench] fn bench_push_back_vec(b: &mut test::BenchHarness) { let mut m = ~[]; do b.iter { m.push(0); } } #[bench] fn bench_push_back_pop_back(b: &mut test::BenchHarness) { let mut m = DList::new::(); do b.iter { m.push_back(0); m.pop_back(); } } #[bench] fn bench_push_back_pop_back_vec(b: &mut test::BenchHarness) { let mut m = ~[]; do b.iter { m.push(0); m.pop(); } } #[bench] fn bench_iter(b: &mut test::BenchHarness) { let v = &[0, ..128]; let m: DList = v.iter().transform(|&x|x).collect(); do b.iter { for m.iter().advance |_| {} } } #[bench] fn bench_iter_mut(b: &mut test::BenchHarness) { let v = &[0, ..128]; let mut m: DList = v.iter().transform(|&x|x).collect(); do b.iter { for m.mut_iter().advance |_| {} } } #[bench] fn bench_iter_rev(b: &mut test::BenchHarness) { let v = &[0, ..128]; let m: DList = v.iter().transform(|&x|x).collect(); do b.iter { for m.rev_iter().advance |_| {} } } #[bench] fn bench_iter_mut_rev(b: &mut test::BenchHarness) { let v = &[0, ..128]; let mut m: DList = v.iter().transform(|&x|x).collect(); do b.iter { for m.mut_rev_iter().advance |_| {} } } #[bench] fn bench_iter_vec(b: &mut test::BenchHarness) { let v = &[0, ..128]; do b.iter { for v.iter().advance |_| {} } } }