1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

package Torello.Java.Additional;

/**
 * A simple wrapper class for passing variables by-reference to methods calls.
 * 
 * <BR /><BR />Note that this class is substantively identical to the class 
 * {@link EffectivelyFinal}, but has a more apropos name.
 * 
 * @param <A> Any type.  Class {@code ByRef} serves as a wrapper for this type.
 */
public class ByRef<A> implements Cloneable
{
    /**
     * The actual variable being <B STYLE='color: red;'><I>both</I></B> passed,
     * <B STYLE='color: red;'><I>and</I></B> retrieved from a method.
     */
    public A f;

    /**
     * Creates an instance of this class, and initializes the field.
     * 
     * @param f Initializes this class' only field, {@code this.f}, with the value provided by
     * parameter {@code 'f'}
     */
    public ByRef(A f) { this.f = f; }

    /**
     * Creates an instance of this class, and initializes the field {@code this.f} to null.
     */
    public ByRef()
    { this.f = null; }

    /**
     * Invokes the standard {@code java.lang.Object} method {@code toString()} on the field
     * {@code this.f}.
     * 
     * @return Returns the {@code String} produced by the contents' {@code toString()}
     * */
    public String toString()
    { return f.toString(); }

    /**
     * Invokes the standard {@code java.lang.Object} method {@code hashCode()} on the field
     * {@code this.f}
     * 
     * @return Returns the hash code produced by the contents' {@code hashCode()}.
     */
    public int hashCode()
    { return f.hashCode(); }

    /**
     * This creates a clone of the wrapper class.
     * 
     * <BR /><BR /><B STYLE='color:red;'>NOTE:</B> The field, itself, is not cloned.  Another
     * {@code ByRef} wrapper is built, using the same internal field.  Both the clone
     * and {@code 'this'} will share a pointer-reference to the same field.
     * 
     * @return An {@code ByRef<A>} clone.
     */
    public ByRef<A> clone()
    { return new ByRef<>(f); }

    /**
     * This equality test checks whether both {@code 'this'} and {@code 'other'} share 
     * identical references.  Equality between the contained / wrapped field {@code 'f'} is not
     * checked.
     * 
     * <BR /><BR />If {@code this.f} and {@code other.f} hold different references, this method
     * will return {@code FALSE} <I>even if both of these references have Object-Equality</I>.
     * 
     * @return Returns {@code TRUE} if and only if {@code 'other'} is an instance of 
     * {@code 'ByRef'} and {@code this.f == other.f}.  This method checks for pointer-equality,
     * rather than object-equality.
     */
    @SuppressWarnings("rawtypes")
    public boolean equals(Object other)
    {
        if (! (other instanceof ByRef)) return false;

        ByRef o = (ByRef) other;

        return this.f == o.f;
    }
}