io.takamaka.code.util.StorageArray Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of io-takamaka-code Show documentation
This module defines the support library of the Takamaka language.
The newest version!
/*
Copyright 2021 Fausto Spoto

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 io.takamaka.code.util;

import java.util.function.IntFunction;
import java.util.function.Supplier;
import java.util.function.UnaryOperator;

/**
 * An array of (possibly {@code null}) storage values, that can be kept in storage.
 * By iterating on this object, one gets the values of the array, in increasing index
 * order, including {@code null}s. This interface contains both read and modification methods.
 * 
 * @param  the type of the values
 */

public interface StorageArray extends StorageArrayView {

	/**
	 * Sets the value at the given index. This operation runs in logarithmic time.
	 *
	 * @param index the index
	 * @param value the value
	 * @throws ArrayIndexOutOfBoundsException if {@code index} is outside the bounds of the array
	 */
	void set(int index, V value);

	/**
	 * Replaces the old value {@code e} at {@code index} with {@code how.apply(e)}.
	 * If {@code index} was unmapped, it will be replaced with {@code how.apply(null)},
	 * which might well lead to a run-time exception.
	 *
	 * @param index the index whose value must be replaced
	 * @param how the replacement function
	 * @throws ArrayIndexOutOfBoundsException if {@code index} is outside the bounds of the array
	 */
	void update(int index, UnaryOperator how);

	/**
	 * Replaces the old value {@code e} at {@code index} with {@code how.apply(e)}.
	 * If {@code index} was unmapped, it will be replaced with {@code how.apply(_default)}.
	 *
	 * @param index the index whose value must be replaced
	 * @param _default the default value
	 * @param how the replacement function
	 * @throws ArrayIndexOutOfBoundsException if {@code index} is outside the bounds of the array
	 */
	void update(int index, V _default, UnaryOperator how);

	/**
	 * Replaces the old value {@code e} at {@code index} with {@code how.apply(e)}.
	 * If {@code index} was unmapped, it will be replaced with {@code how.apply(_default.get())}.
	 *
	 * @param index the index whose value must be replaced
	 * @param _default the supplier of the default value
	 * @param how the replacement function
	 * @throws ArrayIndexOutOfBoundsException if {@code index} is outside the bounds of the array
	 */
	void update(int index, Supplier _default, UnaryOperator how);

	/**
	 * If the given index is unmapped or is mapped to {@code null}, map it to the given value.
	 * 
	 * @param index the index
	 * @param value the value
	 * @return the previous value at the given index. Yields {@code null} if {@code index} was previously unmapped
	 *         or was mapped to {@code null}
	 */
	V setIfAbsent(int index, V value);

	/**
	 * If the given index is unmapped or is mapped to {@code null}, map it to the value given by a supplier.
	 * 
	 * @param index the index
	 * @param supplier the supplier
	 * @return the previous value at the given index, if it was already mapped to a non-{@code null} value.
	 *         If the index was unmapped or was mapped to {@code null}, yields the new value
	 */
	V computeIfAbsent(int index, Supplier supplier);

	/**
	 * If the given index is unmapped or is mapped to {@code null}, map it to the value given by a supplier.
	 * 
	 * @param index the index
	 * @param supplier the supplier
	 * @return the previous value at the given index, if it was already mapped to a non-{@code null} value.
	 *         If the index was unmapped or was mapped to {@code null}, yields the new value
	 */
	V computeIfAbsent(int index, IntFunction supplier);

	/**
	 * Yields a view of this array. The view reflects the elements in this array:
	 * any future modification of this array will be seen also through the view.
	 * A view is always {@link io.takamaka.code.lang.Exported}.
	 * 
	 * @return a view of this array
	 */
	StorageArrayView view();
}