IncrementalIntHash.java

/*******************************************************************************
 * Copyright 2014 Trevor Robinson
 * 
 * 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 com.scurrilous.circe;

import java.nio.ByteBuffer;

/**
 * Incremental stateless integer hash function, which has the property that its
 * output is the same as (or easily derivable from) its state. Specifically, for
 * any sequence M partitioned arbitrarily into two subsequences M<sub>1</sub>
 * M<sub>2</sub>:
 * 
 * <pre>
 * h(M) = h'(h(M<sub>1</sub>), M<sub>2</sub>)
 * </pre>
 * 
 * where h corresponds to the {@link StatelessIntHash#calculate calculate}
 * function and h' corresponds to the {@link #resume} function.
 * <p>
 * Note that stateful hash functions obtained from incremental stateless hash
 * functions are also {@linkplain StatefulHash#supportsIncremental incremental}.
 */
public interface IncrementalIntHash extends StatelessIntHash {

    /**
     * Evaluates this hash function as if the entire given input array were
     * appended to the previously hashed input.
     * 
     * @param current the hash output for input hashed so far
     * @param input the input array
     * @return the output of the hash function for the concatenated input
     */
    int resume(int current, byte[] input);

    /**
     * Evaluates this hash function as if the given range of the given input
     * array were appended to the previously hashed input.
     * 
     * @param current the hash output for input hashed so far
     * @param input the input array
     * @param index the starting index of the first input byte
     * @param length the length of the input range
     * @return the output of the hash function for the concatenated input
     * @throws IndexOutOfBoundsException if index is negative or
     *             {@code index + length} is greater than the array length
     */
    int resume(int current, byte[] input, int index, int length);

    /**
     * Evaluates this hash function as if the remaining contents of the given
     * input buffer were appended to the previously hashed input. This method
     * leaves the buffer position at the limit.
     * 
     * @param current the hash output for input hashed so far
     * @param input the input buffer
     * @return the output of the hash function for the concatenated input
     */
    int resume(int current, ByteBuffer input);

    /**
     * Evaluates this hash function as if the memory with the given address and
     * length were appended to the previously hashed input. The arguments are
     * generally not checked in any way and will likely lead to a VM crash or
     * undefined results if invalid.
     * 
     * @param current the hash output for input hashed so far
     * @param address the base address of the input
     * @param length the length of the input
     * @return the output of the hash function for the concatenated input
     * @throws UnsupportedOperationException if this function does not support
     *             unsafe memory access
     * @see #supportsUnsafe()
     */
    int resume(int current, long address, long length);
}