// SPDX-FileCopyrightText: 2020 Roberto Posenato <roberto.posenato@univr.it>
//
// SPDX-License-Identifier: LGPL-3.0-or-later
package it.univr.di.cstnu.graph;

import it.unimi.dsi.fastutil.objects.Object2IntMap;
import it.unimi.dsi.fastutil.objects.Object2ObjectMap;
import it.unimi.dsi.fastutil.objects.ObjectSet;
import it.univr.di.labeledvalue.ALabel;
import it.univr.di.labeledvalue.Label;
import it.univr.di.labeledvalue.LabeledALabelIntTreeMap;
import it.univr.di.labeledvalue.LabeledLowerCaseValue;

import javax.annotation.Nonnull;

/**
 * Represents the behavior of a CSTNPSU edge.
 * <p>
 * A CSTNPSU edge is a {@link it.univr.di.cstnu.algorithms.CSTNU} edge where it is also possible to have <b>more</b> lower-case values.
 * So, lower-case values are represented as a set of lower-case values.
 * {@link LabeledLowerCaseValue} is NOT used.
 * <p>
 * To promote greater efficiency, some methods return a view of the internal data structures (they are all methods that return a set of {@code Entry}).
 * Such a view could be dangerous because it could be modified directly (don't do that!) Such methods must be used only to read-only scan the labeled values or the labeled values' labels efficiently. Moreover, such views are not more valid if a value is added to or removed from the edge.
 *
 * @author posenato
 * @version $Rev$
 */
@SuppressWarnings("InterfaceWithOnlyOneDirectInheritor")
public interface CSTNPSUEdge extends BasicCSTNUEdge {

	/**
	 * Clears the labeled lowercase values.
	 */
	void clearLowerCaseValues();

	/**
	 * Don't use this set for scanning that requires modifying the internal map; otherwise, this set will become invalid after the first modification.
	 *
	 * @return the set of all labeled values and all labeled lower-case ones. The labeled values have an empty ALabel.
	 */
	ObjectSet<Object2ObjectMap.Entry<ALabel, Object2IntMap.Entry<Label>>> getAllLowerCaseAndLabeledValues();

	/**
	 * @param aLabel the lower-case label
	 *
	 * @return the set of all labels associated with lower-case label aLabel.
	 */
	ObjectSet<Label> getLabelsOfLowerCaseValues(@Nonnull ALabel aLabel);

	/**
	 * @return the set of all labels associated with all lower-case labeled values;
	 */
	ObjectSet<Label> getLabelsOfLowerCaseValues();

	/**
	 * @return the set of all lower-case labels.
	 */
	ObjectSet<ALabel> getLowerCaseLabels();

	/**
	 * @param l    a {@link it.univr.di.labeledvalue.Label} object.
	 * @param name a {@link it.univr.di.labeledvalue.ALabel} node name.
	 *
	 * @return the labeled lower-case value. {@link it.univr.di.labeledvalue.Constants#INT_NULL} if the value does not exist.
	 */
	int getLowerCaseValue(Label l, ALabel name);

	/**
	 * Don't use this set for scanning that requires modifying the internal map; otherwise, this set will become invalid after the first modification.
	 *
	 * @return the set of all labeled lower-case values.
	 */
	ObjectSet<Object2ObjectMap.Entry<ALabel, Object2IntMap.Entry<Label>>> getLowerCaseValues();

	/**
	 * @param lowerCaseValue the labeled lower case value to use for initializing the current one.
	 */
	void setLowerCaseValues(LabeledALabelIntTreeMap lowerCaseValue);

	/**
	 * @param lowerCaseLabel a non-null lower-case label.
	 *
	 * @return a view of the lower-case values associated with lowerCaseLabel if there are some of them, an empty set otherwise.
	 */
	@Nonnull
	ObjectSet<Object2IntMap.Entry<Label>> getLowerCaseValues(@Nonnull ALabel lowerCaseLabel);

	/**
	 * @return a copy of the minimal value (with the ALabel) among all upper-case labeled values if there are some of them,
	 * 	null otherwise.
	 */
	Object2ObjectMap.Entry<Label, Object2IntMap.Entry<ALabel>> getMinLowerCaseValue();

	/**
	 * Merge a lower label constraint with value {@code i} for the node name {@code n} with label {@code l}.<br>
	 *
	 * @param l        It cannot be null or empty.
	 * @param nodeName the node name. It cannot be null. It must be the unmodified name of the node.
	 * @param i        It cannot be null.
	 *
	 * @return true if the merge has been successful.
	 */
	boolean mergeLowerCaseValue(Label l, ALabel nodeName, int i);

	/**
	 * @param l a {@link it.univr.di.labeledvalue.Label} object.
	 * @param n a {@link it.univr.di.labeledvalue.ALabel} node name
	 */
	void removeLowerCaseValue(Label l, ALabel n);
}