/**
 * StructureProperties.java
 * 
 * Copyright (c) 2004-2012, Nicole C. Tedesco. All rights reserved.
 * 
 * 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 net.sf.jaccumulator;

import java.util.Set;
import java.util.SortedSet;

import net.sf.jaccumulator.primitives.Variant;
import net.sf.jaccumulator.scalars.MutableScalarDomain;
import net.sf.jaccumulator.scalars.NumericPrecision;

/**
 * Prepositions for querying general properties of algebraic
 * {@link AlgebraicStructure structures}
 * 
 * @since JAccumulator 4.0
 * @author Nicole Tedesco (<a
 *         href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>)
 */
public interface StructureProperties
{
    /**
     * Answer {@code true} if the implementation of this object can be changed.<br/>
     * <br/>
     * A configurable object has a structure that can be {@link #isExpandable()
     * expanded}, or {@link #isReducible() reduced}, or has replaceable
     * components. Configurable structures are necessarily
     * {@link Mutable#isMutable() mutable}; in fact, "configurability" can be
     * used as a strict definition of mutability. This predicate however
     * overrides {@link #isMutable} in the respect that, for some types of
     * objects such as {@link Variant Variants}, mutability can be changed by
     * switching from a non-mutable implementation to a mutable one (e.g., via
     * {@link MutableScalarDomain#assertPrecision(NumericPrecision)
     * assertPrecision}).
     * 
     * @return {@code true} if the implementation of this object can be changed
     */
    public boolean isConfigurable();

    /**
     * Answer {@code true} if this structure contains a countable number of
     * elements. A countable set is a set with the same cardinality as some
     * subset of the set of natural numbers. A set that is not countable
     * contains an infinite number of elements.
     * 
     * @return {@code true} if this structure contains a <i>countable</i> number
     *         of elements, otherwise {@code false} if it contains an infinite
     *         number of elements
     * @see <a href="http://en.wikipedia.org/wiki/Countable_set">Countable
     *      set</a> (Wikipedia)
     */
    public boolean isCountable();

    /**
     * Answer {@code true} if this structure, <i>in principle</i>, can be
     * reduced via element removal or expanded via element addition. Empty
     * collections are, in principle, reducible, but <i>read-only</i>
     * collections are neither reducible or expandable.
     * 
     * @return {@code true} if this structure can be either
     *         {@link #isReducible() reduced} or {@link #isExpandable()
     *         expanded}
     */
    public boolean isElastic();

    /**
     * Answer {@code true} if this structure contains no elements. For
     * {@link Text strings} this would indicate an empty string (no characters
     * in an empty array). For scalars this would indicate an empty set, or a
     * zero bit count, which would be the case of {@code null} values. Note
     * that, although the {@code null} constant technically contains zero
     * elements, its {@link String string} value evaluates to "null", which from
     * a String perspective is not empty.
     * 
     * @return {@code true} if this structure contains no elements
     */
    public boolean isEmpty();

    /**
     * @return {@code true} if this structure can be expanded via element
     *         insertion
     */
    public boolean isExpandable();

    /**
     * Answer {@code true} if <i>the elements of this structure</i> necessarily
     * share a partial or total order between each other within the context of
     * this structure. Ordering does not necessarily imply a simple sequencing
     * between randomly selected elements, but rather a necessary sorting order
     * between elements independent of the sets they are related by. A
     * {@link SortedSet} is ordered, not merely because its elements are <i>de
     * facto</i> sorted, but because the {@code SortedSet} defines a universe in
     * which only sortable elements can exist and it defines a sorting function
     * which places those elements in their sorted order at the time of
     * iteration. An <a href="http://en.wikipedia.org/wiki/Order_theory">ordered
     * set</a> has elements with values that are reflexive, antisymmetric, and
     * transitive relative to each other. Necessarily empty sets are not
     * considered ordered.
     * 
     * @return {@code true} if the structure has either a partial or total order
     *         over its elements
     * 
     * @see <a href="http://en.wikipedia.org/wiki/Order_theory">order theory</a>
     *      (Wikipedia)
     */
    public boolean isOrdered();

    /**
     * Answer {@code true} if this structure, <i>in principle</i>, can be
     * reduced via element removal. Empty collections are, in principle,
     * reducible, but <i>read-only</i> collections are not.
     * 
     * @return {@code true} if this structure, <i>in principle</i>, can be
     *         reduced via element removal
     */
    public boolean isReducible();

    /**
     * @return {@code true} if the elements in this structure are, by definition
     *         of the structure's algebra, unique (e.g., {@link Set sets})
     */
    public boolean isUnique();
}