001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.collections.primitives; 018 019/** 020 * A bi-directional iterator over <code>byte</code> values. 021 * 022 * @see org.apache.commons.collections.primitives.adapters.ByteListIteratorListIterator 023 * @see org.apache.commons.collections.primitives.adapters.ListIteratorByteListIterator 024 * 025 * @since Commons Collections 2.2 026 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $ 027 * 028 * @author Rodney Waldhoff 029 */ 030public interface ByteListIterator extends ByteIterator { 031 /** 032 * Inserts the specified element into my underlying collection 033 * (optional operation). 034 * The element is inserted immediately before the next element 035 * that would have been returned by {@link #next}, if any, 036 * and immediately after the next element that would have been 037 * returned by {@link #previous}, if any. 038 * <p/> 039 * The new element is inserted immediately before the implied 040 * cursor. A subsequent call to {@link #previous} will return 041 * the added element, a subsequent call to {@link #next} will 042 * be unaffected. This call increases by one the value that 043 * would be returned by a call to {@link #nextIndex} or 044 * {@link #previousIndex}. 045 * 046 * @param element the value to be inserted 047 * 048 * @throws UnsupportedOperationException when this operation is not 049 * supported 050 * @throws IllegalArgumentException if some aspect of the specified element 051 * prevents it from being added 052 */ 053 void add(byte element); 054 055 /** 056 * Returns <code>true</code> iff I have more elements 057 * when traversed in the forward direction. 058 * (In other words, returns <code>true</code> iff 059 * a call to {@link #next} will return an element 060 * rather than throwing an exception. 061 * 062 * @return <code>true</code> iff I have more elements when 063 * traversed in the forward direction 064 */ 065 boolean hasNext(); 066 067 /** 068 * Returns <code>true</code> iff I have more elements 069 * when traversed in the reverse direction. 070 * (In other words, returns <code>true</code> iff 071 * a call to {@link #previous} will return an element 072 * rather than throwing an exception. 073 * 074 * @return <code>true</code> iff I have more elements when 075 * traversed in the reverse direction 076 */ 077 boolean hasPrevious(); 078 079 /** 080 * Returns the next element in me when traversed in the 081 * forward direction. 082 * 083 * @return the next element in me 084 * @throws java.util.NoSuchElementException if there is no next element 085 */ 086 byte next(); 087 088 /** 089 * Returns the index of the element that would be returned 090 * by a subsequent call to {@link #next}, or the number 091 * of elements in my iteration if I have no next element. 092 * 093 * @return the index of the next element in me 094 */ 095 int nextIndex(); 096 097 /** 098 * Returns the next element in me when traversed in the 099 * reverse direction. 100 * 101 * @return the previous element in me 102 * @throws java.util.NoSuchElementException if there is no previous element 103 */ 104 byte previous(); 105 106 /** 107 * Returns the index of the element that would be returned 108 * by a subsequent call to {@link #previous}, or 109 * <code>-1</code> if I have no previous element. 110 * 111 * @return the index of the previous element in me 112 */ 113 int previousIndex(); 114 115 /** 116 * Removes from my underlying collection the last 117 * element returned by {@link #next} or {@link #previous} 118 * (optional operation). 119 * 120 * @throws UnsupportedOperationException if this operation is not 121 * supported 122 * @throws IllegalStateException if neither {@link #next} nor 123 * {@link #previous} has yet been called, or 124 * {@link #remove} or {@link #add} has already been called since 125 * the last call to {@link #next} or {@link #previous}. 126 */ 127 void remove(); 128 129 /** 130 * Replaces in my underlying collection the last 131 * element returned by {@link #next} or {@link #previous} 132 * with the specified value (optional operation). 133 * 134 * @param element the value to replace the last returned element with 135 * @throws UnsupportedOperationException if this operation is not 136 * supported 137 * @throws IllegalStateException if neither {@link #next} nor 138 * {@link #previous} has yet been called, or 139 * {@link #remove} or {@link #add} has already been called since 140 * the last call to {@link #next} or {@link #previous}. 141 * @throws IllegalArgumentException if some aspect of the specified element 142 * prevents it from being added 143 */ 144 void set(byte element); 145}