<commit_before>/*
 *  Copyright (C) 2007 Google Inc.
 * 
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package org.yawni.util;

//import java.io.Serializable;
import com.google.common.collect.UnmodifiableIterator;
import java.util.ArrayList;
import static com.google.common.collect.ObjectArrays.newArray;
import java.util.Collection;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import java.util.ListIterator;
import java.util.NoSuchElementException;
import java.util.RandomAccess;

/**
 * This implementation is particularly useful when {@code E} is immutable (e.g., {@code String}, {@code Integer})
 * (aka "deeply immutable").
 * Strives for performance and memory characteristics of a C99 const array, especially for
 * small sizes (0-5).  "unrolled", "inside out" implementation for small sizes sacrifices 
 * verbosity for space (and probably asks more of the compiler, but who cares).
 *
 * Uses cases:
 * - especially useful when you have millions of short {@code List<T>}s
 *   - ImmutableMultimap
 *   - caches like Yawni uses all the time - impossible to "poison" :)
 *   ? XML parsing / parse tree (read-only JDOM? would be fun to template that anyway if JAXB isn't already far superior)
 *   ? graph / tree data structures
 *   ? ML data structures
 *   - Web-2.0 tags
 *
 * TODO
 * - make this class package private and move it accordingly ?  just an implementation detail for now
 * - take another crack at Restleton
 * - run Google Collections test suite on it
 * - copy Serializable functionality
 *
 * <p> Random notes
 * <ul>
 *   <li> Using {@code Iterator}s is slow compared to {@link LightImmutableList#get(int)} - unnecessary allocation / deallocation. </b>
 *        Unfortunately, the new {@code foreach} syntax is so convenient.
 *   </li>
 *   <li> speed: inefficiencies in most implementations of base {@link Collection} classes ({@link java.util.AbstractCollection},
 *        {@link java.util.AbstractList}, etc.) in the form of {@link Iterator}-based implementations of key methods<commit_msg>minor<commit_after>/*
 *  Copyright (C) 2007 Google Inc.
 * 
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package org.yawni.util;

//import java.io.Serializable;
import com.google.common.collect.UnmodifiableIterator;
import java.util.ArrayList;
import static com.google.common.collect.ObjectArrays.newArray;
import java.util.Collection;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import java.util.ListIterator;
import java.util.NoSuchElementException;
import java.util.RandomAccess;

/**
 * This implementation is particularly useful when {@code E} is immutable (e.g., {@code String}, {@code Integer})
 * (aka "deeply immutable").
 * Strives for performance and memory characteristics of a C99 const array, especially for
 * small sizes (0-5).  "unrolled", "inside out" implementation for small sizes sacrifices 
 * verbosity for space (and probably asks more of the compiler, but who cares).
 *
 * Uses cases:
 * - especially useful when you have millions of short {@code List<T>}s
 *   - ImmutableMultimap
 *   - caches like Yawni uses all the time - impossible to "poison" :)
 *   ? XML parsing / parse tree (read-only JDOM? would be fun to template that anyway if JAXB isn't already far superior)
 *   ? graph / tree data structures
 *   ? ML data structures
 *
 * TODO
 * - make this class package private and move it accordingly ?  just an implementation detail for now
 * - take another crack at Restleton
 * - run Google Collections test suite on it
 * - copy Serializable functionality
 *
 * <p> Random notes
 * <ul>
 *   <li> Using {@code Iterator}s is slow compared to {@link LightImmutableList#get(int)} - unnecessary allocation / deallocation. </b>
 *        Unfortunately, the new {@code foreach} syntax is so convenient.
 *   </li>
 *   <li> speed: inefficiencies in most implementations of base {@link Collection} classes ({@link java.util.AbstractCollection},
 *        {@link java.util.AbstractList}, etc.) in the form of {@link Iterator}-based implementations of key methods
{'fraction_non_alphanumeric': 0.08757564969740121, 'fraction_numerical': 0.004627981488074048, 'mean_word_length': 3.8903394255874675, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4040285', 'n_tokens_mistral': 1498, 'n_tokens_neox': 1478, 'n_words': 665}