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 019import java.util.EmptyStackException; 020 021import org.apache.commons.collections.primitives.ArrayIntList; 022 023/** 024 * A primitive int based Stack. 025 * 026 * @author Apache Directory Project 027 * @since Commons Primitives 1.1 028 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $ 029 */ 030public class IntStack 031{ 032 /** the underlying dynamic primitive backing store */ 033 private ArrayIntList list = new ArrayIntList() ; 034 035 036 public IntStack() 037 { 038 } 039 040 041 public IntStack( int[] numbas ) 042 { 043 for ( int ii = 0; ii < numbas.length; ii++ ) 044 { 045 list.add( numbas[ii] ) ; 046 } 047 } 048 049 050 /** 051 * Tests if this stack is empty. 052 * 053 * @return true if and only if this stack contains no ints; false otherwise 054 */ 055 public boolean empty() 056 { 057 return list.isEmpty() ; 058 } 059 060 061 /** 062 * Looks at the int at the top of this stack without removing it from 063 * the stack. 064 * 065 * @return int at the top of this stack (last int in ArrayIntList) 066 * @throws EmptyStackException if this stack is empty 067 */ 068 public int peek() 069 { 070 if ( list.isEmpty() ) 071 { 072 throw new EmptyStackException() ; 073 } 074 075 return list.get( list.size() - 1 ) ; 076 } 077 078 079 /** 080 * Return the n'th int down the stack, where 0 is the top element and 081 * [size()-1] is the bottom element. 082 * 083 * @param n the element index 084 * @return the element at the index 085 * @throws EmptyStackException if the stack is empty 086 * @throws IndexOutOfBoundsException if the index is out of bounds 087 */ 088 public int peek( int n ) 089 { 090 if ( list.isEmpty() ) 091 { 092 throw new EmptyStackException() ; 093 } 094 095 return list.get( list.size() - n - 1 ) ; 096 } 097 098 099 /** 100 * Removes the int at the top of this stack and returns that object as the 101 * value of this function. 102 * 103 * @return int at the top of this stack (last int in ArrayIntList) 104 * @throws EmptyStackException if this stack is empty 105 */ 106 public int pop() 107 { 108 if ( list.isEmpty() ) 109 { 110 throw new EmptyStackException() ; 111 } 112 113 return list.removeElementAt( list.size() - 1 ) ; 114 } 115 116 117 /** 118 * Pushes an int item onto the top of this stack. 119 * 120 * @param item the int item to push onto this stack 121 * @return the item argument for call chaining 122 */ 123 public int push( int item ) 124 { 125 list.add( item ) ; 126 return item ; 127 } 128 129 130 /** 131 * Returns the 1-based position where an int is on this stack. If the int 132 * occurs as an item in this stack, this method returns the distance from 133 * the top of the stack of the occurrence nearest the top of the stack; the 134 * topmost item on the stack is considered to be at distance 1. 135 * 136 * @param item the int to search for from the top down 137 * @return the 1-based position from the top of the stack where the int is 138 * located; the return value -1 indicates that the int is not on the stack 139 */ 140 public int search( int item ) 141 { 142 for ( int ii = list.size() - 1; ii >= 0; ii-- ) 143 { 144 if ( list.get( ii ) == item ) 145 { 146 return list.size() - ii ; 147 } 148 } 149 150 151 return -1 ; 152 } 153 154 155 /** 156 * Gets items from the stack where the index is zero based and the top of 157 * the stack is at an index of size()-1 with the bottom of the stack at an 158 * index of 0. 159 * 160 * @param index the index into the stack treated as a list 161 * @return the int value at the index 162 */ 163 public int get( int index ) 164 { 165 return list.get( index ) ; 166 } 167 168 169 /** 170 * Gets the size of this stack. 171 * 172 * @return the size of this stack 173 */ 174 public int size() 175 { 176 return list.size() ; 177 } 178 179 180 /** 181 * Empties the contents of the stack. 182 */ 183 public void clear() 184 { 185 list.clear() ; 186 } 187}