001package Torello.Java.Additional;
002
003/**
004 * A simple wrapper class for passing variables by-reference to methods calls.
005 * 
006 * <BR /><BR />Note that this class is substantively identical to the class 
007 * {@link EffectivelyFinal}, but has a more apropos name.
008 * 
009 * @param <A> Any type.  Class {@code ByRef} serves as a wrapper for this type.
010 */
011public class ByRef<A> implements Cloneable
012{
013    /**
014     * The actual variable being <B STYLE='color: red;'><I>both</I></B> passed,
015     * <B STYLE='color: red;'><I>and</I></B> retrieved from a method.
016     */
017    public A f;
018
019    /**
020     * Creates an instance of this class, and initializes the field.
021     * 
022     * @param f Initializes this class' only field, {@code this.f}, with the value provided by
023     * parameter {@code 'f'}
024     */
025    public ByRef(A f) { this.f = f; }
026
027    /**
028     * Creates an instance of this class, and initializes the field {@code this.f} to null.
029     */
030    public ByRef()
031    { this.f = null; }
032
033    /**
034     * Invokes the standard {@code java.lang.Object} method {@code toString()} on the field
035     * {@code this.f}.
036     * 
037     * @return Returns the {@code String} produced by the contents' {@code toString()}
038     * */
039    public String toString()
040    { return f.toString(); }
041
042    /**
043     * Invokes the standard {@code java.lang.Object} method {@code hashCode()} on the field
044     * {@code this.f}
045     * 
046     * @return Returns the hash code produced by the contents' {@code hashCode()}.
047     */
048    public int hashCode()
049    { return f.hashCode(); }
050
051    /**
052     * This creates a clone of the wrapper class.
053     * 
054     * <BR /><BR /><B STYLE='color:red;'>NOTE:</B> The field, itself, is not cloned.  Another
055     * {@code ByRef} wrapper is built, using the same internal field.  Both the clone
056     * and {@code 'this'} will share a pointer-reference to the same field.
057     * 
058     * @return An {@code ByRef<A>} clone.
059     */
060    public ByRef<A> clone()
061    { return new ByRef<>(f); }
062
063    /**
064     * This equality test checks whether both {@code 'this'} and {@code 'other'} share 
065     * identical references.  Equality between the contained / wrapped field {@code 'f'} is not
066     * checked.
067     * 
068     * <BR /><BR />If {@code this.f} and {@code other.f} hold different references, this method
069     * will return {@code FALSE} <I>even if both of these references have Object-Equality</I>.
070     * 
071     * @return Returns {@code TRUE} if and only if {@code 'other'} is an instance of 
072     * {@code 'ByRef'} and {@code this.f == other.f}.  This method checks for pointer-equality,
073     * rather than object-equality.
074     */
075    @SuppressWarnings("rawtypes")
076    public boolean equals(Object other)
077    {
078        if (! (other instanceof ByRef)) return false;
079
080        ByRef o = (ByRef) other;
081
082        return this.f == o.f;
083    }
084}