elki.database.ids.DBIDIter Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of elki-core-dbids Show documentation

ELKI - Core DBIDs API – Open-Source Data-Mining Framework with Index Acceleration

The newest version!

/*
 * This file is part of ELKI:
 * Environment for Developing KDD-Applications Supported by Index-Structures
 *
 * Copyright (C) 2022
 * ELKI Development Team
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program. If not, see .
 */
package elki.database.ids;

import elki.utilities.datastructures.iterator.Iter;

/**
 * Iterator for DBIDs.
 * 
 * Important note: this iterator has a significantly different syntax
 * and semantics than the Java iterators. It is much more aligned with C than
 * with Java, but at the same time, the syntax is much more compatible with for
 * loops.
 * 

 * Usage example:
 *
 * 
 * {@code 
 * for (DBIDIter iter = ids.iter(); iter.valid(); iter.advance()) {
 *   Object o = relation.get(iter); // Many interfaces allow direct use
 *   DBID id = DBIDUtil.deref(iter); // Materialize only if you need to!
 * }
 * }
 * 
 *
 * We list some fundamental differences.
 * 
 * {@link DBIDIter#valid() iter.valid()} refers to the current element,
 * {@code Iterator.next()} to the next.
 * {@link DBIDIter#advance() iter.advance()} does not return an element. Use
 * {@code get...} to access it.
 * {@code DBIDIter.get...} do not advance the iterator.
 * 
 *
 * @author Erich Schubert
 * @since 0.5.0
 *
 * @opt nodefillcolor LemonChiffon
 */
public interface DBIDIter extends DBIDRef, Iter {
  @Override
  DBIDIter advance();

  /**
   * Add all remaining elements of an iterator to an existing collection.
   * 
   * @param  Collection type
   * @param collection Existing collection
   * @return The existing collection
   */
  default  T addTo(T collection) {
    while(valid()) {
      collection.add(this);
      advance();
    }
    return collection;
  }
}