001/**
002 * MutableScalarDomain.java
003 *
004 * Copyright (c) 2004-2012, Nicole C. Tedesco.  All rights reserved.
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at:
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package net.sf.jaccumulator.scalars;
020
021import net.sf.jaccumulator.AlgebraicStructure;
022import net.sf.jaccumulator.MutableAlgebraicStructure;
023import net.sf.jaccumulator.StructureProperties;
024
025/**
026 * A write-only contract for an {@link AlgebraicStructure algebraic} structure
027 * within which {@link Scalar Scalars} can be embedded
028 *
029 * @param <DOMAIN>
030 *      this domain type (facilitates chaining)
031 *
032 * @since JAccumulator 4.0
033 * @author Nicole Tedesco (<a href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>)
034 */
035public interface MutableScalarDomain<DOMAIN extends MutableScalarDomain<DOMAIN>>
036    extends
037        MutableAlgebraicStructure<DOMAIN>
038{
039    /**
040     * Convert the numeric {@link NumericPrecision precision} of this
041     * implementation to the closest available match for the proposed precision.
042     * Note that the precision of this implementation may <i>not</i> change as a
043     * result of calling this function if this structure is not configurable.
044     *
045     * @param prec
046     *        the proposed precision
047     * @return {@code this} object (facilitates operation chaining)
048     */
049    public DOMAIN assertPrecision( final NumericPrecision prec );
050
051    /**
052     * If this object's implementation is less {@link NumericPrecision precise}
053     * than the specified numeric precision, then convert this implementation to
054     * the closest available match for the proposed precision. Note that the
055     * precision of this implementation may <i>not</i> change as a result of
056     * calling this function if the proposed precision is less precise than the
057     * this object's current precision level or if this structure is not
058     * {@link StructureProperties#isConfigurable() configurable).
059     *
060     * @param prec
061     *        the proposed precision
062     * @return {@code this} object (facilitates operation chaining)
063     * @see StructureProperties#isConfigurable()
064     */
065    public DOMAIN promoteTo( final NumericPrecision prec );
066}