001/**
002 * ScalarReplicator.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.Replicator;
022
023/**
024 * A {@link Replicator replicator} for {@link Scalar scalar}
025 *
026 * @param <SCALAR>
027 *        the factory product
028 * @since JAccumulator 4.0
029 * @author Nicole Tedesco (<a
030 *         href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>)
031 */
032public interface ScalarReplicator<SCALAR extends ScalarReplicator<SCALAR>>
033    extends
034        Replicator<SCALAR>
035{
036    /**
037     * Using this object as a factory, produce a new scalar of an
038     * appropriately matching type but initialized with the value specified
039     *
040     * @param aValue
041     *        a new value
042     * @return a copy (clone) of this scalar initialized using the
043     *         specified value
044     */
045    public SCALAR copyUsing( final boolean aValue );
046
047    /**
048     * Using this object as a factory, produce a new scalar of an
049     * appropriately matching type but initialized with the value specified
050     *
051     * @param aValue
052     *        a new value
053     * @return a copy (clone) of this scalar initialized using the
054     *         specified value
055     */
056    public SCALAR copyUsing( final byte aValue );
057
058    /**
059     * Using this object as a factory, produce a new scalar of an
060     * appropriately matching type but initialized with the value specified
061     *
062     * @param aValue
063     *        a new value
064     * @return a copy (clone) of this scalar initialized using the
065     *         specified value
066     */
067    public SCALAR copyUsing( final char aValue );
068
069    /**
070     * Using this object as a factory, produce a new scalar of an
071     * appropriately matching type but initialized with the value specified
072     *
073     * @param aValue
074     *        a new value
075     * @return a copy (clone) of this scalar initialized using the
076     *         specified value
077     */
078    public SCALAR copyUsing( final double aValue );
079
080    /**
081     * Using this object as a factory, produce a new scalar of an
082     * appropriately matching type but initialized with the value specified
083     *
084     * @param aValue
085     *        a new value
086     * @return a copy (clone) of this scalar initialized using the
087     *         specified value
088     */
089    public SCALAR copyUsing( final float aValue );
090
091    /**
092     * Using this object as a factory, produce a new scalar of an
093     * appropriately matching type but initialized with the value specified
094     *
095     * @param aValue
096     *        a new value
097     * @return a copy (clone) of this scalar initialized using the
098     *         specified value
099     */
100    public SCALAR copyUsing( final int aValue );
101
102    /**
103     * Using this object as a factory, produce a new scalar of an
104     * appropriately matching type but initialized with the value specified
105     *
106     * @param aValue
107     *        a new value
108     * @return a copy (clone) of this scalar initialized using the
109     *         specified value
110     */
111    public SCALAR copyUsing( final long aValue );
112
113    /**
114     * Using this object as a factory, produce a new scalar of an
115     * appropriately matching type but initialized with the value specified
116     *
117     * @param aValue
118     *        a new value
119     * @return a copy (clone) of this scalar initialized using the
120     *         specified value
121     */
122    public SCALAR copyUsing( final short aValue );
123
124    /**
125     * Using this scalar as a factory, produce a new scalar of the
126     * same type but initialized with the value specified
127     *
128     * @param aValue
129     *        a new value
130     * @return a copy (clone) of this scalar initialized using the
131     *         specified value
132     */
133    public SCALAR copyUsingScalar( final SealedScalar<?> aValue );
134
135    /**
136     * If this scalar is already a {@link Scalar scalar} then simply
137     * call its {@link #copy()} function, otherwise produce a new scalar
138     * with scalar precision
139     * @return
140     *      a new scalar scalar
141     */
142    public Scalar<?> toScalar();
143}