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.0-M1 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 * </p> 054 * 055 * @param e the enumeration to get a value from 056 * @param index the index to get 057 * @param <T> the type of object in the {@link Enumeration} 058 * @return the object at the specified index 059 * @throws IndexOutOfBoundsException if the index is invalid 060 * @throws IllegalArgumentException if the object type is invalid 061 * @since 4.1 062 */ 063 public static <T> T get(final Enumeration<T> e, final int index) { 064 CollectionUtils.checkIndexBounds(index); 065 int i = index; 066 while (e.hasMoreElements()) { 067 i--; 068 if (i == -1) { 069 return e.nextElement(); 070 } 071 e.nextElement(); 072 } 073 throw new IndexOutOfBoundsException("Entry does not exist: " + i); 074 } 075 076 /** 077 * Creates a list based on an enumeration. 078 * 079 * <p>As the enumeration is traversed, an ArrayList of its values is 080 * created. The new list is returned.</p> 081 * 082 * @param <E> the element type 083 * @param enumeration the enumeration to traverse, which should not be {@code null}. 084 * @return a list containing all elements of the given enumeration 085 * @throws NullPointerException if the enumeration parameter is {@code null}. 086 */ 087 public static <E> List<E> toList(final Enumeration<? extends E> enumeration) { 088 return IteratorUtils.toList(new EnumerationIterator<>(enumeration)); 089 } 090 091 /** 092 * Override toList(Enumeration) for StringTokenizer as it implements Enumeration<Object> 093 * for the sake of backward compatibility. 094 * 095 * @param stringTokenizer the tokenizer to convert to a {@link List}<{@link String}> 096 * @return a list containing all tokens of the given StringTokenizer 097 */ 098 public static List<String> toList(final StringTokenizer stringTokenizer) { 099 final List<String> result = new ArrayList<>(stringTokenizer.countTokens()); 100 while (stringTokenizer.hasMoreTokens()) { 101 result.add(stringTokenizer.nextToken()); 102 } 103 return result; 104 } 105 106 /** 107 * Don't allow instances. 108 */ 109 private EnumerationUtils() { 110 // no instances. 111 } 112 113}