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.collections4; 018 019import java.util.ArrayList; 020import java.util.Enumeration; 021import java.util.List; 022import java.util.StringTokenizer; 023 024import org.apache.commons.collections4.iterators.EnumerationIterator; 025import org.apache.commons.collections4.iterators.IteratorIterable; 026 027/** 028 * Provides utility methods for {@link Enumeration} instances. 029 * 030 * @since 3.0 031 */ 032public class EnumerationUtils { 033 034 /** 035 * Creates an {@link Iterable} that wraps an {@link Enumeration}. The returned {@link Iterable} can be used for a 036 * single iteration. 037 * 038 * @param <T> the element type 039 * @param enumeration the enumeration to use, may not be null 040 * @return a new, single use {@link Iterable} 041 * @since 4.5 042 */ 043 public static <T> Iterable<T> asIterable(final Enumeration<T> enumeration) { 044 return new IteratorIterable<>(new EnumerationIterator<>(enumeration)); 045 } 046 047 /** 048 * Returns the {@code index}-th value in the {@link Enumeration}, throwing 049 * {@code IndexOutOfBoundsException} if there is no such element. 050 * <p> 051 * The Enumeration is advanced to {@code index} (or to the end, if 052 * {@code index} exceeds the number of entries) as a side effect of this method. 053 * 054 * @param e the enumeration to get a value from 055 * @param index the index to get 056 * @param <T> the type of object in the {@link Enumeration} 057 * @return the object at the specified index 058 * @throws IndexOutOfBoundsException if the index is invalid 059 * @throws IllegalArgumentException if the object type is invalid 060 * @since 4.1 061 */ 062 public static <T> T get(final Enumeration<T> e, final int index) { 063 CollectionUtils.checkIndexBounds(index); 064 int i = index; 065 while (e.hasMoreElements()) { 066 i--; 067 if (i == -1) { 068 return e.nextElement(); 069 } 070 e.nextElement(); 071 } 072 throw new IndexOutOfBoundsException("Entry does not exist: " + i); 073 } 074 075 /** 076 * Creates a list based on an enumeration. 077 * 078 * <p>As the enumeration is traversed, an ArrayList of its values is 079 * created. The new list is returned.</p> 080 * 081 * @param <E> the element type 082 * @param enumeration the enumeration to traverse, which should not be {@code null}. 083 * @return a list containing all elements of the given enumeration 084 * @throws NullPointerException if the enumeration parameter is {@code null}. 085 */ 086 public static <E> List<E> toList(final Enumeration<? extends E> enumeration) { 087 return IteratorUtils.toList(new EnumerationIterator<>(enumeration)); 088 } 089 090 /** 091 * Override toList(Enumeration) for StringTokenizer as it implements Enumeration<Object> 092 * for the sake of backward compatibility. 093 * 094 * @param stringTokenizer the tokenizer to convert to a {@link List}<{@link String}> 095 * @return a list containing all tokens of the given StringTokenizer 096 */ 097 public static List<String> toList(final StringTokenizer stringTokenizer) { 098 final List<String> result = new ArrayList<>(stringTokenizer.countTokens()); 099 while (stringTokenizer.hasMoreTokens()) { 100 result.add(stringTokenizer.nextToken()); 101 } 102 return result; 103 } 104 105 /** 106 * Don't allow instances. 107 */ 108 private EnumerationUtils() { 109 // no instances. 110 } 111 112}