net.openhft.koloboke.collect.map.ObjCharCursor Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of koloboke-api-jdk8 Show documentation
Carefully designed and efficient extension of the Java Collections Framework with primitive specializations and more, built for Java 8 (API)
The newest version!
/*
 * Copyright 2014 the original author or authors.
 *
 * Licensed 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 net.openhft.koloboke.collect.map;

import net.openhft.koloboke.collect.Cursor;
import net.openhft.koloboke.function.ObjCharConsumer;

import javax.annotation.Nonnull;


/**
 * A mutable pointer to the entry in an iteration of entries with {@code Object} keys and
 * {@code char} values.
 *
 * See the comparison of iteration ways
 * in the library.
 *
 * 
{@code ObjCharCursors} of immutable maps don't support {@link #setValue(char)}
 * operation. More about mutability profiles.
 * 
 *
 * @see ObjCharMap#cursor()
 */
public interface ObjCharCursor extends Cursor {

    /**
     * Performs the given action for each entry of the iteration after the cursor in forward
     * direction until all entries have been processed or the action throws an exception.
     * Exceptions thrown by the action are relayed to the caller.
     *
     * {@code cur.forEachForward(action)} is exact equivalent of
     * 
 {@code
     * while (cur.moveNext())
     *     action.accept(cur.key(), cur.value());}
     *
     * @param action the action to be performed for each entry
     */
    void forEachForward(@Nonnull ObjCharConsumer action);

    /**
     * Returns the key of the entry to which the cursor currently points.
     *
     * Throws {@code IllegalStateException}, if the cursor isn't pointing to any entry: if it
     * is in front of the first entry, after the last, or the current entry has been removed
     * using {@link #remove()} operation.
     *
     * @return the key of the entry to which the cursor currently points
     * @throws IllegalStateException if this cursor is initially in front of the first entry
     *         and {@link #moveNext()} hasn't been called yet,
     *         or the previous call of {@code moveNext} returned {@code false},
     *         or {@code remove()} has been performed after the previous cursor movement
     */
    K key();

    /**
     * Returns the value of the entry to which the cursor currently points.
     *
     * 
Throws {@code IllegalStateException}, if the cursor isn't pointing to any entry: if it
     * is in front of the first entry, after the last, or the current entry has been removed
     * using {@link #remove()} operation.
     *
     * @return the value of the entry to which the cursor currently points
     * @throws IllegalStateException if this cursor is initially in front of the first entry
     *         and {@link #moveNext()} hasn't been called yet,
     *         or the previous call of {@code moveNext} returned {@code false},
     *         or {@code remove()} has been performed after the previous cursor movement
     */
    char value();

    /**
     * Replaces the value of the entry to which the cursor currently points (optional operation).
     *
     * Throws {@code IllegalStateException} if the cursor isn't pointing to any entry: if it
     * is in front of the first entry, after the last, or the current entry has been removed
     * using {@link #remove()} operation.
     *
     * @param value new value to be stored in the entry to which the cursor currently points
     * @throws UnsupportedOperationException if the {@code setValue} operation is not supported
     *         by this cursor
     * @throws IllegalArgumentException if some property this value prevents it from being stored
     *         in the entries of the iteration
     * @throws IllegalStateException if this cursor is initially in front of the first entry
     *         and {@link #moveNext()} hasn't been called yet,
     *         or the previous call of {@code moveNext} returned {@code false},
     *         or {@code remove()} has been performed after the previous cursor movement
     */
    void setValue(char value);
}