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}