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 * Sequence interface. A sequence is a collection where elements are
021 * stored in a specific order, and elements can be inserted in between.
022 * 
023 * @author Malte Isberner <malte.isberner@gmail.com>
024 *
025 * @param <E> element class.
026 */
027public interface SmartSequence<E> extends SmartCollection<E> {
028        
029        
030        /**
031         * Retrieves the reference to the preceding element, or <code>null</code> if the
032         * given reference references the first element in the list. 
033         * @param ref the reference
034         * @return the reference to the preceding element
035         */
036        public ElementReference pred(ElementReference ref);
037        
038        /**
039         * Retrieves the reference to the succeeding element, or <code>null</code> if the
040         * given reference references the last element in the list.
041         * @param ref the reference
042         * @return the reference to the succeeding element
043         */
044        public ElementReference succ(ElementReference ref);
045        
046        /**
047         * Inserts the given element <i>before</i> the element referenced by
048         * the specified reference.
049         * @param element the element to be added.
050         * @param ref reference to the element before which the new element
051         * is to be inserted.
052         * @return reference to the newly added element.
053         */
054        public ElementReference insertBefore(E element, ElementReference ref);
055        
056        /**
057         * Inserts the given element <i>after</i> the element referenced by
058         * the specified reference.
059         * @param element the element to be added.
060         * @param ref reference to the element after which the new element
061         * is to be inserted.
062         * @return reference to the newly added element.
063         */
064        public ElementReference insertAfter(E element, ElementReference ref);
065}