// 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.Entry;
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 javax.annotation.Nonnull;

/**
 * Represents the common behavior of an edge that can have upper-case value(s) and a lower-case one.
 * <p>
 * In CSTNUs, each edge can have more upper-case and one lower-case value.
 * <p>
 * In CSTNPSUs, each edge can have more upper-case and <b>more</b> lower-case values.
 * <p>
 * So, this interface represents the common part.
 * <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("UnusedReturnValue")
public interface BasicCSTNUEdge extends CSTNEdge {
	/**
	 * Clears the labeled lowercase values. For CSTNU, there is always only one value, but for some extensions, it can be more.
	 */
	void clearLowerCaseValue();

	/**
	 * Clears all uppercase labeled values.
	 */
	void clearUpperCaseValues();

	/**
	 * 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 upper-case ones. The labeled values have an empty ALabel.
	 */
	ObjectSet<Object2ObjectMap.Entry<ALabel, Entry<Label>>> getAllUpperCaseAndLabeledValues();

	/**
	 * @param aLabel the upper-case label
	 *
	 * @return the set of all labels associated with upper-case label aLabel if any, empty set otherwise.
	 */
	ObjectSet<Label> getLabelsOfUpperCaseValues(@Nonnull ALabel aLabel);

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

	/**
	 * @return the minimal value (with the ALabel) among all upper-case labeled values if there are some of them,
	 *    {@link it.univr.di.labeledvalue.Constants#INT_NULL} otherwise.
	 */
	Object2ObjectMap.Entry<Label, Entry<ALabel>> getMinUpperCaseValue();

	/**
	 * @param upperCaseLabel a non-null upper-case label.
	 *
	 * @return a copy of the entry containing the minimal value associated with 'upperCaseLabel' if there are some of them; otherwise, it is null.
	 */
	Entry<Label> getMinUpperCaseValue(@Nonnull ALabel upperCaseLabel);

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

	/**
	 * @param l    a {@link it.univr.di.labeledvalue.Label} object.
	 * @param name a {@link it.univr.di.labeledvalue.ALabel} node name.
	 *
	 * @return the value associated with the upper label of the occurrence of node n if it exists, {@link it.univr.di.labeledvalue.Constants#INT_NULL} otherwise.
	 */
	int getUpperCaseValue(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 upper-case values, if any, an empty set otherwise.
	 */
	ObjectSet<Object2ObjectMap.Entry<ALabel, Entry<Label>>> getUpperCaseValues();

	/**
	 * Don't use this set for scanning that requires modifying the internal map; otherwise, this set will become invalid after the first modification.
	 *
	 * @param upperCaseLabel the upper-case label
	 *
	 * @return the set of labeled upper-case values associated with the upper-case label. If there are no values, it returns an empty set.
	 */
	ObjectSet<Entry<Label>> getUpperCaseValues(@Nonnull ALabel upperCaseLabel);

	/**
	 * @return the representation of the lower-case value(s) of the edge.
	 */
	String lowerCaseValueAsString();

	/**
	 * @return the number of lower-case value(s) of the edge.
	 */
	int lowerCaseValueSize();

	/**
	 * Merge an upper label constraint with delay {@code i} for the node name n with propositional label {@code l}.
	 * <p>
	 * If the new value makes other already present values redundant, such values are removed. If the new value is redundant, it is ignored.
	 *
	 * @param l        label of the value
	 * @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 mergeUpperCaseValue(Label l, ALabel nodeName, int i);

	/**
	 * Set or add a lower label constraint with delay i for the node n with label l.
	 * <p>
	 * If a value with a lower-case nodeName and label l for node n is already present, it is overwritten.
	 *
	 * @param l        the label
	 * @param nodeName the node name. It cannot be null.
	 * @param i        the new value
	 */
	void putLowerCaseValue(@Nonnull Label l, @Nonnull ALabel nodeName, int i);

	/**
	 * Put an upper label constraint with delay i for the node name n with label l.
	 * <p>
	 * There is no optimization of the labeled values present after the insertion of this one.
	 *
	 * @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 putUpperCaseValue(Label l, ALabel nodeName, int i);

	/**
	 * Remove the upper label for node name n with label l.
	 *
	 * @param l a {@link it.univr.di.labeledvalue.Label} object.
	 * @param n a {@link it.univr.di.labeledvalue.ALabel} node name
	 *
	 * @return the old value
	 */
	int removeUpperCaseValue(Label l, ALabel n);

	/**
	 * @param labeledValue the upper-case labeled value map to use for initializing the set
	 */
	void setUpperCaseValueMap(LabeledALabelIntTreeMap labeledValue);

	/**
	 * @return the total number of values in the edge
	 */
	int size();

	/**
	 * @return the number of upper-case values of the edge.
	 */
	int upperCaseValueSize();

	/**
	 * @return the representation of all upper-case values of the edge.
	 */
	String upperCaseValuesAsString();
}