001/* Copyright (C) 2013 TU Dortmund
002 * This file is part of AutomataLib, http://www.automatalib.net/.
003 * 
004 * AutomataLib is free software; you can redistribute it and/or
005 * modify it under the terms of the GNU Lesser General Public
006 * License version 3.0 as published by the Free Software Foundation.
007 * 
008 * AutomataLib is distributed in the hope that it will be useful,
009 * but WITHOUT ANY WARRANTY; without even the implied warranty of
010 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
011 * Lesser General Public License for more details.
012 * 
013 * You should have received a copy of the GNU Lesser General Public
014 * License along with AutomataLib; if not, see
015 * http://www.gnu.de/documents/lgpl.en.html.
016 */
017package net.automatalib.commons.smartcollections;
018
019/**
020 * A double-ended queue (deque), allowing access, removal and insertion
021 * of elements both at the beginning and the end.
022 * 
023 * @author Malte Isberner
024 *
025 * @param <E> element class.
026 */
027public interface SmartDeque<E> extends SmartCollection<E> {
028
029        /**
030         * Adds an element at the beginning of the sequence.
031         * @param element the element to be added.
032         * @return the reference to the newly added element.
033         */
034        public abstract ElementReference pushFront(E element);
035
036        /**
037         * Adds an element at the end of the sequence.
038         * @param element the element to be added.
039         * @return the reference to the newly added element.
040         */
041        public abstract ElementReference pushBack(E element);
042        
043        /**
044         * Retrieves the element at the beginning of the sequence, or
045         * <code>null</code> if the sequence is empty.
046         * @return the first element or <code>null</code>.
047         */
048        public abstract E getFront();
049
050        /**
051         * Retrieves the element at the end of the sequence, or
052         * <code>null</code> if the sequence is empty.
053         * @return the last element or <code>null</code>.
054         */
055        public abstract E getBack();
056
057        
058        /**
059         * Retrieves the reference to the element at the beginning of the
060         * sequence, or <code>null</code> if the sequence is empty.
061         * @return reference to the first element or <code>null</code>.
062         */
063        public abstract ElementReference getFrontReference();
064
065        /**
066         * Retrieves the reference to the element at the end of the sequence,
067         * or <code>null</code> if the sequence is empty.
068         * @return reference to the last element or <code>null</code>.
069         */
070        public abstract ElementReference getBackReference();
071
072        
073        /**
074         * Retrieves and removes the element at the beginning of the sequence.
075         * If the sequence is empty, <code>null</code> is returned.
076         * @return the previously first element or <code>null</code>. 
077         */
078        public E popFront();
079        
080        /**
081         * Retrieves and removes the element at the beginning of the sequence.
082         * If the sequence is empty, <code>null</code> is returned.
083         * @return the previously first element or <code>null</code>. 
084         */
085        public abstract E popBack();
086
087}