org.javimmutable.collections.JImmutableMap Maven / Gradle / Ivy

Go to download
///###////////////////////////////////////////////////////////////////////////
//
// Burton Computer Corporation
// http://www.burton-computer.com
//
// Copyright (c) 2018, Burton Computer Corporation
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
//     Redistributions of source code must retain the above copyright
//     notice, this list of conditions and the following disclaimer.
//
//     Redistributions in binary form must reproduce the above copyright
//     notice, this list of conditions and the following disclaimer in
//     the documentation and/or other materials provided with the
//     distribution.
//
//     Neither the name of the Burton Computer Corporation nor the names
//     of its contributors may be used to endorse or promote products
//     derived from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package org.javimmutable.collections;

import javax.annotation.Nonnull;
import javax.annotation.concurrent.Immutable;
import java.util.Map;
import java.util.stream.Collector;

/**
 * Interface for immutable data structures that allow storage and retrieval of
 * key/value pairs.  null is always an allowed value within the map but is not
 * an allowed key.
 */
@Immutable
public interface JImmutableMap
    extends Insertable, JImmutableMap>,
            Mapped,
            IterableStreamable>,
            Cursorable>,
            InvariantCheckable
{
    /**
     * An immutable entry in the map.  Contains the key and value for that entry.
     * key must not be null but value can be null.
     */
    @Immutable
    interface Entry
    {
        @Nonnull
        K getKey();

        V getValue();
    }

    /**
     * Add key/value entry to the map, replacing any existing entry with same key.
     */
    @Nonnull
    @Override
    JImmutableMap insert(@Nonnull Entry value);

    /**
     * Search for a value within the map and return a Holder indicating if the value
     * was found and, if it was found, the value itself.  Holder allows null values
     * to be returned unambiguously.
     *
     * @param key non-null key to search for
     * @return empty Holder if not found, otherwise filled Holder with value
     */
    @Nonnull
    @Override
    Holder find(@Nonnull K key);

    /**
     * Search for an Entry within the map and return a Holder indicating if the Entry
     * was found and, if it was found, the Entry itself.
     *
     * @param key non-null key to search for
     * @return empty Holder if not found, otherwise filled Holder with Entry
     */
    @Nonnull
    Holder> findEntry(@Nonnull K key);

    /**
     * Sets the value associated with a specific key.  Key must be non-null but value
     * can be null.  If the key already has a value in the map the old value is discarded
     * and the new value is stored in its place.  Returns a new JImmutableMap reflecting
     * any changes.  The original map is always left unchanged.
     *
     * @param key   non-null key
     * @param value possibly null value
     * @return new map reflecting the change
     */
    @Nonnull
    JImmutableMap assign(@Nonnull K key,
                               V value);

    /**
     * Copies all key-value pairs from the given map. The map itself and its keys must be
     * nonnull, but values can be null.  If a key already has a value in the map, the old
     * value is replaced with the new value. Returns a new JImmutableMap with the changes.
     *
     * @param map JImmutableMap to take values from
     * @return new map reflecting the change
     */
    @Nonnull
    JImmutableMap assignAll(@Nonnull JImmutableMap map);


    /**
     * Copies all key-value pairs from the given map. The map itself and its keys must be
     * nonnull, but values can be null.  If a key already has a value in the map, the old
     * value is replaced with the new value. Returns a new JImmutableMap with the changes.
     *
     * @param map Map to take values from
     * @return new map reflecting the change
     */
    @Nonnull
    JImmutableMap assignAll(@Nonnull Map map);

    /**
     * Deletes the entry for the specified key (if any).  Returns a new map if the value
     * was deleted or the current map if the key was not contained in the map.
     *
     * @param key non-null key
     * @return same or different map depending on whether key was removed
     */
    @Nonnull
    JImmutableMap delete(@Nonnull K key);

    /**
     * Return the number of entries in the map.
     */
    int size();

    /**
     * @return true only if list contains no values
     */
    boolean isEmpty();

    /**
     * @return an equivalent collection with no values
     */
    @Nonnull
    JImmutableMap deleteAll();

    /**
     * Creates an unmodifiable java.util.Map reflecting the values of this JImmutableMap.
     *
     * @return Map view of this JImmutableMap
     */
    @Nonnull
    Map getMap();

    /**
     * Creates a Cursor to access all of the Map's keys.
     */
    @Nonnull
    Cursor keysCursor();

    /**
     * Creates a Cursor to access all of the Map's values.
     */
    @Nonnull
    Cursor valuesCursor();

    /**
     * Creates a Streamable to access all of the Map's keys.
     */
    @Nonnull
    IterableStreamable keys();

    /**
     * Creates a Streamable to access all of the Map's values.
     */
    @Nonnull
    IterableStreamable values();

    /**
     * Returns a Collector that creates a set of the same type as this containing all
     * of the collected values inserted over whatever starting values this already contained.
     */
    @Nonnull
    default Collector, ?, JImmutableMap> mapCollector()
    {
        return GenericCollector.unordered(this, deleteAll(), a -> a.isEmpty(), (a, v) -> a.insert(v), (a, b) -> a.insertAll(b));
    }

    /**
     * Update the value at the key.  A Holder containing the value currently stored at the key,
     * or an empty Holder if the key is not currently bound, is passed to the generator function.
     *
     * @param key       non-null key
     * @param generator function to call with current value to create value if key is already bound
     * @return new map with changes applied
     */
    @Nonnull
    default JImmutableMap update(@Nonnull K key,
                                       @Nonnull Func1, V> generator)
    {
        final Holder current = find(key);
        final V newValue = generator.apply(current);
        return assign(key, newValue);
    }
}