org.javimmutable.collections.JImmutableMap Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of javimmutable-collections Show documentation
Show all versions of javimmutable-collections Show documentation
Library providing immutable/persistent collection classes for
Java. While collections are immutable they provide methods for
adding and removing values by creating new modified copies of
themselves. Each copy shares almost all of its structure with
other copies to minimize memory consumption.
///###////////////////////////////////////////////////////////////////////////
//
// 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);
}
}