0001 
0002 /*
0003  *  Descripter 1.0 - Java Script Engines
0004  *  Copyright (C) 2010-2015  Jianjun Liu (J.J.Liu)
0005  *  
0006  *  This program is free software: you can redistribute it and/or modify
0007  *  it under the terms of the GNU Affero General Public License as published by
0008  *  the Free Software Foundation, either version 3 of the License, or
0009  *  (at your option) any later version.
0010  *  
0011  *  This program is distributed in the hope that it will be useful,
0012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0014  *  GNU Affero General Public License for more details.
0015  *  
0016  *  You should have received a copy of the GNU Affero General Public License
0017  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
0018  */
0019 
0020 package org.descripter.js.api;
0021 
0022 import java.util.Set;
0023 
0024 /**
0025  * <p>Emulates JavaScript variables.</p>
0026  * 
0027  * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.descripter.org" target="_blank">http://www.descripter.org</a>
0028  * @since Descripter 1.0
0029  */
0030 public final class Var extends Objective<Objective<?>> implements Value
0031 {
0032     private final Key index;
0033 
0034     /**
0035      * <p>Constructs an {@link Objective} context of this type.</p>
0036      * @param with The containing {@link Objective} context.
0037      * @param index The {@link Key} to the containing {@link Objective} context.
0038      * @since Descripter 1.0
0039      */
0040     public Var(Objective<?> with, Key index) {
0041         super(with);
0042         this.index = index;
0043     }
0044 
0045     /**
0046      * <p>Evaluates the {@link Var} {@link Value}.</p>
0047      * @return The evaluated value
0048      * @since Descripter 1.0
0049      */
0050     @Override
0051     public Object evaluate() {
0052         return with.get(index);
0053     }
0054 
0055     /**
0056      * <p>Deletes the current variable.</p>
0057      * <p>This method hides the associated key from the containing context if it is visible.</p>
0058      * <p>Note that this method does nothing if the current variable is undefined.</p>
0059      * @return <tt>true</tt> if variable was defined; <tt>false</tt>, otherwise.
0060      * @throws RuntimeException if the containing context is read-only.
0061      * @since Descripter 1.0
0062      */
0063     public boolean delete() {
0064         if (has(index)) {
0065             hide(index);
0066         }
0067         return false;
0068     }
0069 
0070     /**
0071      * <p>Returns a string representation of the current value object.</p>
0072      * @return The string representation of the current value object
0073      * @since Descripter 1.0
0074      */
0075     @Override
0076     public String toString() {
0077         return toString(evaluate());
0078     }
0079 
0080     /**
0081      * <p>Tells if the specified key is visible in the current context.</p>
0082      * @param k A key to test
0083      * @return <tt>true</tt> if the <tt>key</tt> is visible in the current context; <tt>false</tt>, otherwise.
0084      * @since Descripter 1.0
0085      */
0086     @Override
0087     public final boolean has(Key k) {
0088         return ((Objective<?>)evaluate()).has(k);
0089     }
0090 
0091     /**
0092      * <p>Tells if the current context owns the specified key.</p>
0093      * @param k A key to test
0094      * @return <tt>true</tt> if the current context owns the <tt>key</tt>; <tt>false</tt>, otherwise.
0095      * @since Descripter 1.0
0096      */
0097     @Override
0098     public final boolean owns(Key k) {
0099         return ((Objective<?>)evaluate()).owns(k);
0100     }
0101 
0102     /**
0103      * <p>Returns the {@link Set} of keys that are visible to the current context.</p>
0104      * @return The {@link Set} of keys that are visible to the current context.
0105      * @since Descripter 1.0
0106      */
0107     @Override
0108     public final Set<Key> keys() {
0109         return ((Objective<?>)evaluate()).keys();
0110     }
0111 
0112     /**
0113      * <p>Returns the value associated with the specified key.</p>
0114      * @param k A key to lookup
0115      * @return The value associated with the specified key or <tt>null</tt> for none.
0116      * @since Descripter 1.0
0117      */
0118     @Override
0119     public final Object get(Key k) {
0120         return ((Objective<?>)evaluate()).get(k);
0121     }
0122 
0123     /**
0124      * <p>Sets the value associated with the specified key.</p>
0125      * @param key A {@link Key} to set the value
0126      * @param val The value to set
0127      * @throws RuntimeException if the current context is read-only.
0128      * @since Descripter 1.0
0129      */
0130     @Override
0131     public void put(Key key, Object val) {
0132         ((Objective<?>)evaluate()).put(key, evaluate(val));
0133     }
0134 
0135     /**
0136      * <p>Assigns value to the current variable.</p>
0137      * @param value The value to assign
0138      * @return The assigned value
0139      * @throws RuntimeException if the current context is read-only.
0140      * @since Descripter 1.0
0141      */
0142     public final <T> T assign(T value) {
0143         with.set(index, evaluate(value));
0144         return value;
0145     }
0146 
0147     /**
0148      * <p>Allocates a new object with this variable of a {@link Function}.</p>
0149      * @param script The script context that invoked this service
0150      * @param args An array of the arguments passed by the invocation
0151      * @return The newly allocated object
0152      * @since Descripter 1.0
0153      */
0154     public final <S extends Script<?>> Object allocate(S script, Object ...args) {
0155         return script.alloc(evaluate(), args);
0156     }
0157 
0158     /**
0159      * <p>Calls this variable of a {@link Function}.</p>
0160      * <p>This method evaluates the current variable. If the value is a function, it calls the function 
0161      * based on the containing context; otherwise, it passes the call to the specified script context.</p>
0162      * @param script The script context that invoked this service
0163      * @param args An array of the arguments passed by the invocation
0164      * @return The return result of the invocation
0165      * @since Descripter 1.0
0166      */
0167     public final <S extends Script<?>> Object call(S script, Object ...args) {
0168         Object o = evaluate();
0169         if (o instanceof Function<?>) {
0170             return ((Function<?>)o).call(script, with, script.array(args));
0171         }
0172         return script.call(o, args);
0173     }
0174 
0175     /**
0176      * <p>Logically evaluates the current variable.</p>
0177      * @return The boolean value of the current variable
0178      * @since Descripter 1.0
0179      */
0180     public final boolean bool() {
0181         return bool(this);
0182     }
0183 
0184     /**
0185      * <p>Increments the current variable.</p>
0186      * @return The incremented number value of the current variable
0187      * @since Descripter 1.0
0188      */
0189     public final double inc() {
0190         return assign(add(doubleValue(this), 1));
0191     }
0192 
0193     /**
0194      * <p>Decrements the current variable.</p>
0195      * @return The decremented number value of the current variable
0196      * @since Descripter 1.0
0197      */
0198     public final double dec() {
0199         return assign(sub(doubleValue(this), 1));
0200     }
0201 
0202     /**
0203      * <p>Returns a {@link Value} that evaluates to this variable and increments it after evaluation.</p>
0204      * @return A post-incrementing {@link Value} of this variable
0205      * @since Descripter 1.0
0206      */
0207     public final Value uninc() {
0208         return new Value() {
0209             @Override
0210             public Object evaluate() {
0211                 Number v = toNumber(Var.this);
0212                 assign(add(v, 1));
0213                 return v;
0214             }
0215         };
0216     }
0217 
0218     /**
0219      * <p>Returns a {@link Value} that evaluates to this variable and decrements it after evaluation.</p>
0220      * @return A post-decrementing {@link Value} of this variable
0221      * @since Descripter 1.0
0222      */
0223     public final Value undec() {
0224         return new Value() {
0225             @Override
0226             public Object evaluate() {
0227                 Number v = toNumber(Var.this);
0228                 assign(sub(v, 1));
0229                 return v;
0230             }
0231         };
0232     }
0233 
0234     /**
0235      * <p>Adds a numeric operand onto the current variable, 
0236      * resembling the assignment-with-addition operator in JavaScript.</p>
0237      * @param o A numeric operand
0238      * @return The numeric operand
0239      * @since Descripter 1.0
0240      */
0241     public final Object aadd(Object o) {
0242         return assign(add(o));
0243     }
0244 
0245     /**
0246      * <p>Subtracts a numeric operand from the current variable, 
0247      * resembling the assignment-with-subtraction operator in JavaScript.</p>
0248      * @param o A numeric operand
0249      * @return The numeric operand
0250      * @since Descripter 1.0
0251      */
0252     public final double asub(Object o) {
0253         return assign(sub(o));
0254     }
0255 
0256     /**
0257      * <p>Multiplies a numeric operand onto the current variable, 
0258      * resembling the assignment-with-multiplication operator in JavaScript.</p>
0259      * @param o A numeric operand
0260      * @return The numeric operand
0261      * @since Descripter 1.0
0262      */
0263     public final double amul(Object o) {
0264         return assign(mul(o));
0265     }
0266 
0267     /**
0268      * <p>Modulo operates a numeric operand onto the current variable, 
0269      * resembling the assignment-with-modulo operator in JavaScript.</p>
0270      * @param o A numeric operand
0271      * @return The numeric operand
0272      * @since Descripter 1.0
0273      */
0274     public final double amod(Object o) {
0275         return assign(mod(o));
0276     }
0277 
0278     /**
0279      * <p>Divides the current variable by a numeric operand, 
0280      * resembling the assignment-with-division operator in JavaScript.</p>
0281      * @param o A numeric operand
0282      * @return The numeric operand
0283      * @since Descripter 1.0
0284      */
0285     public final double adiv(Object o) {
0286         return assign(div(o));
0287     }
0288 
0289     /**
0290      * <p>Assignment-with-bitwise-AND operation, resembling that of JavaScript, performs a boolean AND 
0291      * operation on each bit of the integer arguments. A bit is set in the result only if 
0292      * the corresponding bit is set in both operands.</p>
0293      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0294      * operation requires numeric operands that have integer values. It operate on the integer 
0295      * operands using a 32-bit integer representation instead of the equivalent floating-point 
0296      * representation.</p>
0297      * <p>If this bitwise operation is used with operands that are not integers or are too 
0298      * large to fit in a 32-bit integer representation, it simply coerces the operands to 
0299      * 32-bit integers by dropping any fractional part of the operand or any bits beyond 
0300      * the 32nd.</p>
0301      * @param o A numeric value.
0302      * @return The bitwise-AND of the two operands.
0303      * @since Descripter 1.0
0304      */
0305     public final int aand(Object o) {
0306         return assign(and(o));
0307     }
0308 
0309     /**
0310      * <p>Assignment-with-bitwise-OR operation, resembling that of JavaScript, performs a boolean OR operation 
0311      * on each bit of the integer arguments. A bit is set in the result if the corresponding 
0312      * bit is set in one or both of the operands.</p>
0313      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0314      * operation requires numeric operands that have integer values. It operate on the integer 
0315      * operands using a 32-bit integer representation instead of the equivalent floating-point 
0316      * representation.</p>
0317      * <p>If this bitwise operation is used with operands that are not integers or are too 
0318      * large to fit in a 32-bit integer representation, it simply coerces the operands to 
0319      * 32-bit integers by dropping any fractional part of the operand or any bits beyond 
0320      * the 32nd.</p>
0321      * @param o A numeric value.
0322      * @return The bitwise-OR of the two operands.
0323      * @since Descripter 1.0
0324      */
0325     public final int aor(Object o) {
0326         return assign(or(o));
0327     }
0328 
0329     /**
0330      * <p>Assignment-with-bitwise-XOR operation, resembling that of JavaScript, performs a boolean exclusive 
0331      * OR operation on each bit of the integer arguments. Exclusive OR means that either 
0332      * operand one is <tt>true</tt> or operand two is <tt>true</tt>, but not both. A bit is 
0333      * set in this operation's result if a corresponding bit is set in one (but not both) 
0334      * of the two operands.</p>
0335      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0336      * operation requires numeric operands that have integer values. It operate on the integer 
0337      * operands using a 32-bit integer representation instead of the equivalent floating-point 
0338      * representation.</p>
0339      * <p>If this bitwise operation is used with operands that are not integers or are too 
0340      * large to fit in a 32-bit integer representation, it simply coerces the operands to 
0341      * 32-bit integers by dropping any fractional part of the operand or any bits beyond 
0342      * the 32nd.</p>
0343      * @param o A numeric value.
0344      * @return The bitwise-exclusive-OR of the two operands.
0345      * @since Descripter 1.0
0346      */
0347     public final int axor(Object o) {
0348         return assign(xor(o));
0349     }
0350 
0351     /**
0352      * <p>Assignment-with-shift-left operation, resembling that of JavaScript, moves all bits in the 
0353      * current variable to the left by the number of places specified in the 
0354      * second operand, which should be an integer between 0 and 31.</p>
0355      * <p>A zero is used for the new first bit, and the value of the 32nd bit is lost. 
0356      * Shifting a value left by one position is equivalent to multiplying by 2, shifting 
0357      * two positions is equivalent to multiplying by 4, etc.</p>
0358      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0359      * operation requires numeric operands that have integer values. It operate on the integer 
0360      * operands using a 32-bit integer representation instead of the equivalent floating-point 
0361      * representation.</p>
0362      * <p>If this bitwise operation is used with values that are not integers or are too 
0363      * large to fit in a 32-bit integer representation, it simply coerces the values to 
0364      * 32-bit integers by dropping any fractional part of the value or any bits beyond 
0365      * the 32nd. The shift operation requires a (right-side) operand between 0 and 31. After 
0366      * converting this operand to a 32-bit integer, it drops any bits beyond the 5th, which 
0367      * yields a number in the appropriate range.</p>
0368      * @param o The number of bits to shift.
0369      * @return The shifted primitive instance.
0370      * @since Descripter 1.0
0371      */
0372     public final int ashl(Object o) {
0373         return assign(shl(o));
0374     }
0375 
0376     /**
0377      * <p>Assignment-with-shift-right operation, resembling that of JavaScript, moves all bits in the 
0378      * current variable to the right by the number of places specified in the 
0379      * second operand (an integer between 0 and 31). Bits that are shifted off the right 
0380      * are lost. The bits filled in on the left depend on the sign bit of the original 
0381      * value, in order to preserve the sign of the result. If the current primitive 
0382      * instance is positive, the result has zeros placed in the high bits; if the current 
0383      * variable is negative, the result has ones placed in the high bits.</p>
0384      * <p>Shifting a value right one place is equivalent to dividing by 2 (discarding the 
0385      * remainder), shifting right two places is equivalent to integer division by 4, and 
0386      * so on.</p>
0387      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0388      * operation requires numeric operands that have integer values. It operate on the integer 
0389      * operands using a 32-bit integer representation instead of the equivalent floating-point 
0390      * representation.</p>
0391      * <p>If this bitwise operation is used with values that are not integers or are too 
0392      * large to fit in a 32-bit integer representation, it simply coerces the values to 
0393      * 32-bit integers by dropping any fractional part of the value or any bits beyond 
0394      * the 32nd. The shift operation requires a (right-side) operand between 0 and 31. After 
0395      * converting this operand to a 32-bit integer, it drops any bits beyond the 5th, which 
0396      * yields a number in the appropriate range.</p>
0397      * @param o The number of bits to shift.
0398      * @return The shifted primitive instance.
0399      * @since Descripter 1.0
0400      */
0401     public final int ashr(Object o) {
0402         return assign(shr(o));
0403     }
0404 
0405     /**
0406      * <p>Assignment-with-shift-right-unsigned operation, resembling that of JavaScript, moves all bits in 
0407      * the current variable to the right by the number of places specified in the 
0408      * second operand (an integer between 0 and 31). Bits that are shifted off the right 
0409      * are lost. The result has zeros placed in the high bits.</p>
0410      * <p>This operation is just like {@link #shr(Object)}, except that the bits shifted 
0411      * in on the left are always zero, regardless of the sign of the current variable.</p>
0412      * <p>Shifting a value right one place is equivalent to dividing by 2 (discarding the 
0413      * remainder), shifting right two places is equivalent to integer division by 4, and 
0414      * so on.</p>
0415      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0416      * operation requires numeric operands that have integer values. It operate on the integer 
0417      * operands using a 32-bit integer representation instead of the equivalent floating-point 
0418      * representation.</p>
0419      * <p>If this bitwise operation is used with values that are not integers or are too 
0420      * large to fit in a 32-bit integer representation, it simply coerces the values to 
0421      * 32-bit integers by dropping any fractional part of the value or any bits beyond 
0422      * the 32nd. The shift operation requires a (right-side) operand between 0 and 31. After 
0423      * converting this operand to a 32-bit integer, it drops any bits beyond the 5th, which 
0424      * yields a number in the appropriate range.</p>
0425      * @param o The number of bits to shift.
0426      * @return The shifted primitive instance.
0427      * @since Descripter 1.0
0428      */
0429     public final int ashru(Object o) {
0430         return assign(shru(o));
0431     }
0432 
0433     /**
0434      * <p>Performs unary negation, resembling the unary minus operator in JavaScript.</p>
0435      * <p>This operation converts a positive value to an equivalently negative value, and 
0436      * vice versa. If the operand is not a number, it attempts to convert it to one.</p>
0437      * @return The negation of the current variable.
0438      * @since Descripter 1.0
0439      */
0440     public final double neg() {
0441         return neg(this);
0442     }
0443 
0444     /**
0445      * <p>Adds the current variable to a numeric operand or concatenates it with 
0446      * a string operand, resembling the addition operator in JavaScript.</p>
0447      * <p>If one value is a string, the other is converted to a string, and the two 
0448      * strings are then concatenated. Object operands are converted to numbers or strings 
0449      * that can be added or concatenated.</p>
0450      * @param o A value or object.
0451      * @return The sum or concatenation of the values.
0452      * @since Descripter 1.0
0453      */
0454     public final Object add(Object o) {
0455         return add(this, o);
0456     }
0457 
0458     /**
0459      * <p>Subtracts the operand from the current variable, resembling the 
0460      * subtraction operator in JavaScript.</p>
0461      * <p>If used with non-numeric values, this operation attempts to convert them to 
0462      * numbers.</p>
0463      * @param o numeric value.
0464      * @return The difference between the current variable and the operand.
0465      * @since Descripter 1.0
0466      */
0467     public final double sub(Object o) {
0468         return sub(this, o);
0469     }
0470 
0471     /**
0472      * <p>Multiplies the current variable with the operand, resembling the 
0473      * multiplication operator in JavaScript.</p>
0474      * <p>If used with non-numeric values, this operation attempts to convert them to 
0475      * numbers.</p>
0476      * @param o Any numeric value.
0477      * @return The product of the current variable and the operand.
0478      * @since Descripter 1.0
0479      */
0480     public final double mul(Object o) {
0481         return mul(this, o);
0482     }
0483 
0484     /**
0485      * <p>Computes the current variable modulo the operand, resembling the modulo 
0486      * operator in JavaScript.</p>
0487      * <p>The operation returns the remainder when the current variable is divided 
0488      * by the operand a certain number of times. If used with non-numeric values, the 
0489      * operation attempts to convert them to numbers. The sign of the result is the same 
0490      * as the sign of the current variable.</p>
0491      * <p>This operation is typically used with integer values, it also works for 
0492      * floating-point values.</p>
0493      * @param o Any numeric value.
0494      * @return The remainder.
0495      * @since Descripter 1.0
0496      */
0497     public final double mod(Object o) {
0498         return mod(this, o);
0499     }
0500 
0501     /**
0502      * <p>Divides the current variable by the operand, resembling the division 
0503      * operator in JavaScript.</p>
0504      * <p>Used with non-numeric values, this operation attempts to convert them to 
0505      * numbers. If you are used to programming languages that distinguish between integer 
0506      * and floating-point numbers, you might expect to get an integer result when you 
0507      * divide one integer by another. In JavaScript, however, all numbers are floating-point, 
0508      * so all division operations have floating-point results. Division by zero yields positive 
0509      * or negative infinity, while <tt>0/0</tt> evaluates to <tt>NaN</tt>.</p>
0510      * @param o Any numeric value.
0511      * @return The quotient of the current variable and the operand.
0512      * @since Descripter 1.0
0513      */
0514     public final double div(Object o) {
0515         return div(this, o);
0516     }
0517 
0518     /**
0519      * <p>Bitwise-NOT operation, resembling that of JavaScript, operates by reversing all 
0520      * bits in the current variable.</p>
0521      * <p>Because of the way signed integers are represented in JavaScript, applying this 
0522      * operation to a value is equivalent to changing its sign and subtracting 1.</p>
0523      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0524      * operation requires numeric operands that have integer values. It operate on the integer 
0525      * values using a 32-bit integer representation instead of the equivalent floating-point 
0526      * representation.</p>
0527      * <p>If this bitwise operation is used with the current variable that are 
0528      * not integers or are too large to fit in a 32-bit integer representation, it simply 
0529      * coerces them to 32-bit integers by dropping any fractional part of the value or any 
0530      * bits beyond the 32nd.</p>
0531      * @return The bitwise-NOT of the current variable.
0532      * @since Descripter 1.0
0533      */
0534     public final int not() {
0535         return not(this);
0536     }
0537 
0538     /**
0539      * <p>Bitwise-AND operation, resembling that of JavaScript, performs a boolean AND 
0540      * operation on each bit of the integer arguments. A bit is set in the result only if 
0541      * the corresponding bit is set in both operands.</p>
0542      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0543      * operation requires numeric operands that have integer values. It operate on the integer 
0544      * operands using a 32-bit integer representation instead of the equivalent floating-point 
0545      * representation.</p>
0546      * <p>If this bitwise operation is used with operands that are not integers or are too 
0547      * large to fit in a 32-bit integer representation, it simply coerces the operands to 
0548      * 32-bit integers by dropping any fractional part of the operand or any bits beyond 
0549      * the 32nd.</p>
0550      * @param o A numeric value.
0551      * @return The bitwise-AND of the two operands.
0552      * @since Descripter 1.0
0553      */
0554     public final int and(Object o) {
0555         return and(this, o);
0556     }
0557 
0558     /**
0559      * <p>Bitwise-OR operation, resembling that of JavaScript, performs a boolean OR operation 
0560      * on each bit of the integer arguments. A bit is set in the result if the corresponding 
0561      * bit is set in one or both of the operands.</p>
0562      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0563      * operation requires numeric operands that have integer values. It operate on the integer 
0564      * operands using a 32-bit integer representation instead of the equivalent floating-point 
0565      * representation.</p>
0566      * <p>If this bitwise operation is used with operands that are not integers or are too 
0567      * large to fit in a 32-bit integer representation, it simply coerces the operands to 
0568      * 32-bit integers by dropping any fractional part of the operand or any bits beyond 
0569      * the 32nd.</p>
0570      * @param o A numeric value.
0571      * @return The bitwise-OR of the two operands.
0572      * @since Descripter 1.0
0573      */
0574     public final int or(Object o) {
0575         return or(this, o);
0576     }
0577 
0578     /**
0579      * <p>Bitwise-XOR operation, resembling that of JavaScript, performs a boolean exclusive 
0580      * OR operation on each bit of the integer arguments. Exclusive OR means that either 
0581      * operand one is <tt>true</tt> or operand two is <tt>true</tt>, but not both. A bit is 
0582      * set in this operation's result if a corresponding bit is set in one (but not both) 
0583      * of the two operands.</p>
0584      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0585      * operation requires numeric operands that have integer values. It operate on the integer 
0586      * operands using a 32-bit integer representation instead of the equivalent floating-point 
0587      * representation.</p>
0588      * <p>If this bitwise operation is used with operands that are not integers or are too 
0589      * large to fit in a 32-bit integer representation, it simply coerces the operands to 
0590      * 32-bit integers by dropping any fractional part of the operand or any bits beyond 
0591      * the 32nd.</p>
0592      * @param o A numeric value.
0593      * @return The bitwise-exclusive-OR of the two operands.
0594      * @since Descripter 1.0
0595      */
0596     public final int xor(Object o) {
0597         return xor(this, o);
0598     }
0599 
0600     /**
0601      * <p>Shift-left operation, resembling that of JavaScript, moves all bits in the 
0602      * current primitive instance to the left by the number of places specified in the 
0603      * second operand, which should be an integer between 0 and 31.</p>
0604      * <p>A zero is used for the new first bit, and the value of the 32nd bit is lost. 
0605      * Shifting a value left by one position is equivalent to multiplying by 2, shifting 
0606      * two positions is equivalent to multiplying by 4, etc.</p>
0607      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0608      * operation requires numeric operands that have integer values. It operate on the integer 
0609      * operands using a 32-bit integer representation instead of the equivalent floating-point 
0610      * representation.</p>
0611      * <p>If this bitwise operation is used with values that are not integers or are too 
0612      * large to fit in a 32-bit integer representation, it simply coerces the values to 
0613      * 32-bit integers by dropping any fractional part of the value or any bits beyond 
0614      * the 32nd. The shift operation requires a (right-side) operand between 0 and 31. After 
0615      * converting this operand to a 32-bit integer, it drops any bits beyond the 5th, which 
0616      * yields a number in the appropriate range.</p>
0617      * @param o The number of bits to shift.
0618      * @return The shifted integer number.
0619      * @since Descripter 1.0
0620      */
0621     public final int shl(Object o) {
0622         return shl(this, o);
0623     }
0624 
0625     /**
0626      * <p>Shift-right operation, resembling that of JavaScript, moves all bits in the 
0627      * current primitive instance to the right by the number of places specified in the 
0628      * second operand (an integer between 0 and 31). Bits that are shifted off the right 
0629      * are lost. The bits filled in on the left depend on the sign bit of the original 
0630      * value, in order to preserve the sign of the result. If the current primitive 
0631      * instance is positive, the result has zeros placed in the high bits; if the current 
0632      * primitive instance is negative, the result has ones placed in the high bits.</p>
0633      * <p>Shifting a value right one place is equivalent to dividing by 2 (discarding the 
0634      * remainder), shifting right two places is equivalent to integer division by 4, and 
0635      * so on.</p>
0636      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0637      * operation requires numeric operands that have integer values. It operate on the integer 
0638      * operands using a 32-bit integer representation instead of the equivalent floating-point 
0639      * representation.</p>
0640      * <p>If this bitwise operation is used with values that are not integers or are too 
0641      * large to fit in a 32-bit integer representation, it simply coerces the values to 
0642      * 32-bit integers by dropping any fractional part of the value or any bits beyond 
0643      * the 32nd. The shift operation requires a (right-side) operand between 0 and 31. After 
0644      * converting this operand to a 32-bit integer, it drops any bits beyond the 5th, which 
0645      * yields a number in the appropriate range.</p>
0646      * @param o The number of bits to shift.
0647      * @return The shifted integer number.
0648      * @since Descripter 1.0
0649      */
0650     public final int shr(Object o) {
0651         return shr(this, o);
0652     }
0653 
0654     /**
0655      * <p>Shift-right-unsigned operation, resembling that of JavaScript, moves all bits in 
0656      * the current variable to the right by the number of places specified in the 
0657      * second operand (an integer between 0 and 31). Bits that are shifted off the right 
0658      * are lost. The result has zeros placed in the high bits.</p>
0659      * <p>This operation is just like {@link #shr(Object)}, except that the bits shifted 
0660      * in on the left are always zero, regardless of the sign of the current variable.</p>
0661      * <p>Shifting a value right one place is equivalent to dividing by 2 (discarding the 
0662      * remainder), shifting right two places is equivalent to integer division by 4, and 
0663      * so on.</p>
0664      * <p>Despite the fact that all numbers in JavaScript are floating-point numbers, the bitwise 
0665      * operation requires numeric operands that have integer values. It operate on the integer 
0666      * operands using a 32-bit integer representation instead of the equivalent floating-point 
0667      * representation.</p>
0668      * <p>If this bitwise operation is used with values that are not integers or are too 
0669      * large to fit in a 32-bit integer representation, it simply coerces the values to 
0670      * 32-bit integers by dropping any fractional part of the value or any bits beyond 
0671      * the 32nd. The shift operation requires a (right-side) operand between 0 and 31. After 
0672      * converting this operand to a 32-bit integer, it drops any bits beyond the 5th, which 
0673      * yields a number in the appropriate range.</p>
0674      * @param o The number of bits to shift.
0675      * @return The shifted integer number.
0676      * @since Descripter 1.0
0677      */
0678     public final int shru(Object o) {
0679         return shru(this, o);
0680     }
0681 
0682     /**
0683      * <p>Logical AND operation, resembling that of JavaScript, performs the Boolean AND 
0684      * operation on the two values: it returns <tt>true</tt> if and only if both its first 
0685      * operand and its second operand are <tt>true</tt>. If one or both of these operands 
0686      * is <tt>false</tt>, it returns <tt>false</tt>.</p>
0687      * <p>In JavaScript, depending on the value of the left-side expression, the operator 
0688      * may or may not evaluate the right-side expression. The actual behavior of the operator 
0689      * is somewhat more complicated. It starts by evaluating its first operand, the expression 
0690      * on its left. If the value of this expression can be converted to <tt>false</tt> 
0691      * (for example, if the left operand evaluates to <tt>null</tt>, 0, "", or undefined), 
0692      * the operator returns the value of the left-side expression. Otherwise, it evaluates 
0693      * its second operand, the expression on its right, and returns the value of that 
0694      * expression. In JavaScript 1.0 and JavaScript 1.1, if the left-side expression 
0695      * evaluates to <tt>false</tt>, the && operator returns <tt>false</tt> rather than 
0696      * returning the unconverted value of the left-side expression.</p>
0697      * <p>Sometimes, this operation probably does not do what the programmers intended. 
0698      * To avoid problems, do not use expressions with side effects (assignments, increments, 
0699      * decrements, and function calls) for the second operand unless you are quite sure 
0700      * you know exactly what you are doing.</p>
0701      * <p>Despite the fairly confusing way that this operation actually works, it is 
0702      * easiest, and perfectly safe, to think of it as merely a Boolean algebra operator. 
0703      * Although it does not actually return a boolean value, the value it returns can always 
0704      * be converted to a boolean value.</p>
0705      * @param o A value or object.
0706      * @return The logical AND of the two operands.
0707      * @since Descripter 1.0
0708      */
0709     public final boolean band(Object o) {
0710         return band(this, o);
0711     }
0712 
0713     /**
0714      * <p>Logical OR operation, resembling that of JavaScript, performs the Boolean OR 
0715      * operation on the two values: it returns <tt>true</tt> if either the first operand or 
0716      * the second operand is <tt>true</tt>, or if both are <tt>true</tt>. If both operands 
0717      * are <tt>false</tt>, it returns <tt>false</tt>.</p>
0718      * <p>In JavaScript, although the || operator is most often used simply as a Boolean OR 
0719      * operator, it, like the && operator, has more complex behavior. It starts by evaluating 
0720      * its first operand, the expression on its left. If the value of this expression can 
0721      * be converted to <tt>true</tt>, it returns the unconverted value of the left-side 
0722      * expression. Otherwise, it evaluates its second operand, the expression on its right, 
0723      * and returns the value of that expression. In JavaScript 1.0 and JavaScript 1.1, if the 
0724      * left-side expression can be converted to <tt>true</tt>, the operator returns <tt>true</tt> 
0725      * and doesn't return the unconverted value of the left-side expression.</p>
0726      * <p>As with the {@link #and(Object)} operation, you should avoid right-side 
0727      * operands that include side effects, unless you purposely want to use the fact that 
0728      * the right-side expression may not be evaluated in JavaScript.</p>
0729      * <p>Even when this operation is used with operands that are not boolean values, it 
0730      * can still be considered a Boolean OR operator because its return value, whatever the 
0731      * type, can be converted to a boolean value.</p>
0732      * @param o A value or object.
0733      * @return The logical OR of the two operands.
0734      * @since Descripter 1.0
0735      */
0736     public final boolean bor(Object o) {
0737         return bor(this, o);
0738     }
0739 
0740     /**
0741      * <p>Inverts the boolean value of the current variable, resembling the 
0742      * logical NOT operator in JavaScript.</p>
0743      * <p>This operation converts the current variable to a boolean value using 
0744      * the following rules if necessary before inverting the converted value.</p>
0745      * <ul>
0746      * <li>If a number is used where a boolean value is expected, the number is converted 
0747      * to <tt>true</tt> unless the number is 0 or NaN, which are converted to <tt>false</tt>.</li>
0748      * <li>If a string is used where a boolean value is expected, it is converted to <tt>true</tt> 
0749      * except for the empty string, which is converted to <tt>false</tt>.</li>
0750      * <li><tt>null</tt> and the undefined value convert to <tt>false</tt>, and any 
0751      * non-null object, array, or function converts to <tt>true</tt>.
0752      * </ul>
0753      * <p>You can convert any value <tt>x</tt> to its equivalent boolean value by applying 
0754      * this operation twice: <tt>bnot(bnot(x))</tt></p>
0755      * @return The inverted boolean value.
0756      * @since Descripter 1.0
0757      */
0758     public final boolean bnot() {
0759         return bnot(this);
0760     }
0761 
0762     /**
0763      * <p>Less-than operation, resembling that of JavaScript, evaluates to <tt>true</tt> if 
0764      * the current variable is less than the second operand; otherwise it 
0765      * evaluates to <tt>false</tt>.</p>
0766      * <p>The operands of this operation may be of any type. Comparison can be performed 
0767      * only on numbers and strings, however, so operands that are not numbers or strings 
0768      * are converted. Comparison and conversion occur as follows:</p>
0769      * <ul>
0770      * <li>If both operands are numbers, or if both convert to numbers, they are compared 
0771      * numerically.</li>
0772      * <li>If both operands are strings or convert to strings, they are compared as 
0773      * strings.</li>
0774      * <li>If one operand is or converts to a string, and one is or converts to a number, 
0775      * the operation attempts to convert the string to a number and performs a numerical 
0776      * comparison. If the string does not represent a number, it converts to <tt>NaN</tt>, 
0777      * and the comparison is <tt>false</tt>. In JavaScript 1.1, the string-to-number 
0778      * conversion causes an error instead of yielding <tt>NaN</tt>.</li>
0779      * <li>If an object can be converted to either a number or a string, JavaScript performs 
0780      * the numerical conversion. This means, for example, that Date objects are compared 
0781      * numerically, and it is meaningful to compare two dates to see whether one is earlier 
0782      * than the other.</li>
0783      * <li>If the operands of the comparison operations cannot both be successfully converted 
0784      * to numbers or to strings, these operations always return <tt>false</tt>.</li>
0785      * <li>If either operand is or converts to <tt>NaN</tt>, the comparison operation always 
0786      * yields <tt>false</tt>.</li>
0787      * </ul>
0788      * <p>Keep in mind that string comparison is done on a strict character-by-character 
0789      * basis using the numerical value of each character from the Unicode encoding. Although 
0790      * in some cases the Unicode standard allows equivalent strings to be encoded using 
0791      * different sequences of characters, the JavaScript comparison operations do not 
0792      * detect these encoding differences; they assume that all strings are expressed in 
0793      * normalized form. Note in particular that string comparison is case-sensitive, and 
0794      * in the Unicode encoding (at least for the ASCII subset), all capital letters are 
0795      * "less than" all lowercase letters. This rule can cause confusing results if you do 
0796      * not expect it.</p>
0797      * <p>The less-than-or-equal and greater-than-or-equal operations do not rely on the 
0798      * equality or identity operations for determining whether two values are "equal." 
0799      * Instead, the less-than-or-equal operator is simply defined as "not greater than", 
0800      * and the greater-than-or-equal operator is defined as "not less than". The one 
0801      * exception occurs when either operand is (or converts to) <tt>NaN</tt>, in which case 
0802      * all comparison operations return <tt>false</tt>.</p>
0803      * @param o A value or object.
0804      * @return <tt>true</tt> if the current variable is less than the second 
0805      * operand; otherwise <tt>false</tt>.
0806      * @since Descripter 1.0
0807      */
0808     public final boolean lt(Object o) {
0809         return lt(this, o);
0810     }
0811 
0812     /**
0813      * <p>Less-than-or-equal operation, resembling that of JavaScript, evaluates to 
0814      * <tt>true</tt> if the current variable is less than or equal to the second 
0815      * operand; otherwise it evaluates to <tt>false</tt>.</p>
0816      * <p>The operands of this operation may be of any type. Comparison can be performed 
0817      * only on numbers and strings, however, so operands that are not numbers or strings 
0818      * are converted. Comparison and conversion occur as follows:</p>
0819      * <ul>
0820      * <li>If both operands are numbers, or if both convert to numbers, they are compared 
0821      * numerically.</li>
0822      * <li>If both operands are strings or convert to strings, they are compared as 
0823      * strings.</li>
0824      * <li>If one operand is or converts to a string, and one is or converts to a number, 
0825      * the operation attempts to convert the string to a number and performs a numerical 
0826      * comparison. If the string does not represent a number, it converts to <tt>NaN</tt>, 
0827      * and the comparison is <tt>false</tt>. In JavaScript 1.1, the string-to-number 
0828      * conversion causes an error instead of yielding <tt>NaN</tt>.</li>
0829      * <li>If an object can be converted to either a number or a string, JavaScript performs 
0830      * the numerical conversion. This means, for example, that Date objects are compared 
0831      * numerically, and it is meaningful to compare two dates to see whether one is earlier 
0832      * than the other.</li>
0833      * <li>If the operands of the comparison operations cannot both be successfully converted 
0834      * to numbers or to strings, these operations always return <tt>false</tt>.</li>
0835      * <li>If either operand is or converts to <tt>NaN</tt>, the comparison operation always 
0836      * yields <tt>false</tt>.</li>
0837      * </ul>
0838      * <p>Keep in mind that string comparison is done on a strict character-by-character 
0839      * basis using the numerical value of each character from the Unicode encoding. Although 
0840      * in some cases the Unicode standard allows equivalent strings to be encoded using 
0841      * different sequences of characters, the JavaScript comparison operations do not 
0842      * detect these encoding differences; they assume that all strings are expressed in 
0843      * normalized form. Note in particular that string comparison is case-sensitive, and 
0844      * in the Unicode encoding (at least for the ASCII subset), all capital letters are 
0845      * "less than" all lowercase letters. This rule can cause confusing results if you do 
0846      * not expect it.</p>
0847      * <p>The less-than-or-equal and greater-than-or-equal operations do not rely on the 
0848      * equality or identity operations for determining whether two values are "equal." 
0849      * Instead, the less-than-or-equal operator is simply defined as "not greater than", 
0850      * and the greater-than-or-equal operator is defined as "not less than". The one 
0851      * exception occurs when either operand is (or converts to) <tt>NaN</tt>, in which case 
0852      * all comparison operations return <tt>false</tt>.</p>
0853      * @param o A value or object.
0854      * @return <tt>true</tt> if the current variable is less than or equal to 
0855      * the second operand; otherwise <tt>false</tt>.
0856      * @since Descripter 1.0
0857      */
0858     public final boolean lte(Object o) {
0859         return lte(this, o);
0860     }
0861 
0862     /**
0863      * <p>Greater-than operation, resembling that of JavaScript, evaluates to <tt>true</tt> if 
0864      * the current variable is greater than the second operand; otherwise it 
0865      * evaluates to <tt>false</tt>.</p>
0866      * <p>The operands of this operation may be of any type. Comparison can be performed 
0867      * only on numbers and strings, however, so operands that are not numbers or strings 
0868      * are converted. Comparison and conversion occur as follows:</p>
0869      * <ul>
0870      * <li>If both operands are numbers, or if both convert to numbers, they are compared 
0871      * numerically.</li>
0872      * <li>If both operands are strings or convert to strings, they are compared as 
0873      * strings.</li>
0874      * <li>If one operand is or converts to a string, and one is or converts to a number, 
0875      * the operation attempts to convert the string to a number and performs a numerical 
0876      * comparison. If the string does not represent a number, it converts to <tt>NaN</tt>, 
0877      * and the comparison is <tt>false</tt>. In JavaScript 1.1, the string-to-number 
0878      * conversion causes an error instead of yielding <tt>NaN</tt>.</li>
0879      * <li>If an object can be converted to either a number or a string, JavaScript performs 
0880      * the numerical conversion. This means, for example, that Date objects are compared 
0881      * numerically, and it is meaningful to compare two dates to see whether one is earlier 
0882      * than the other.</li>
0883      * <li>If the operands of the comparison operations cannot both be successfully converted 
0884      * to numbers or to strings, these operations always return <tt>false</tt>.</li>
0885      * <li>If either operand is or converts to <tt>NaN</tt>, the comparison operation always 
0886      * yields <tt>false</tt>.</li>
0887      * </ul>
0888      * <p>Keep in mind that string comparison is done on a strict character-by-character 
0889      * basis using the numerical value of each character from the Unicode encoding. Although 
0890      * in some cases the Unicode standard allows equivalent strings to be encoded using 
0891      * different sequences of characters, the JavaScript comparison operations do not 
0892      * detect these encoding differences; they assume that all strings are expressed in 
0893      * normalized form. Note in particular that string comparison is case-sensitive, and 
0894      * in the Unicode encoding (at least for the ASCII subset), all capital letters are 
0895      * "less than" all lowercase letters. This rule can cause confusing results if you do 
0896      * not expect it.</p>
0897      * <p>The less-than-or-equal and greater-than-or-equal operations do not rely on the 
0898      * equality or identity operations for determining whether two values are "equal." 
0899      * Instead, the less-than-or-equal operator is simply defined as "not greater than", 
0900      * and the greater-than-or-equal operator is defined as "not less than". The one 
0901      * exception occurs when either operand is (or converts to) <tt>NaN</tt>, in which case 
0902      * all comparison operations return <tt>false</tt>.</p>
0903      * @param o A value or object.
0904      * @return <tt>true</tt> if the current variable is greater than the second 
0905      * operand; otherwise <tt>false</tt>.
0906      * @since Descripter 1.0
0907      */
0908     public final boolean gt(Object o) {
0909         return gt(this, o);
0910     }
0911 
0912     /**
0913      * <p>Greater-than-or-equal operation, resembling that of JavaScript, evaluates to 
0914      * <tt>true</tt> if the current variable is greater than or equal to the 
0915      * second operand; otherwise it evaluates to <tt>false</tt>.</p>
0916      * <p>The operands of this operation may be of any type. Comparison can be performed 
0917      * only on numbers and strings, however, so operands that are not numbers or strings 
0918      * are converted. Comparison and conversion occur as follows:</p>
0919      * <ul>
0920      * <li>If both operands are numbers, or if both convert to numbers, they are compared 
0921      * numerically.</li>
0922      * <li>If both operands are strings or convert to strings, they are compared as 
0923      * strings.</li>
0924      * <li>If one operand is or converts to a string, and one is or converts to a number, 
0925      * the operation attempts to convert the string to a number and performs a numerical 
0926      * comparison. If the string does not represent a number, it converts to <tt>NaN</tt>, 
0927      * and the comparison is <tt>false</tt>. In JavaScript 1.1, the string-to-number 
0928      * conversion causes an error instead of yielding <tt>NaN</tt>.</li>
0929      * <li>If an object can be converted to either a number or a string, JavaScript performs 
0930      * the numerical conversion. This means, for example, that Date objects are compared 
0931      * numerically, and it is meaningful to compare two dates to see whether one is earlier 
0932      * than the other.</li>
0933      * <li>If the operands of the comparison operations cannot both be successfully converted 
0934      * to numbers or to strings, these operations always return <tt>false</tt>.</li>
0935      * <li>If either operand is or converts to <tt>NaN</tt>, the comparison operation always 
0936      * yields <tt>false</tt>.</li>
0937      * </ul>
0938      * <p>Keep in mind that string comparison is done on a strict character-by-character 
0939      * basis using the numerical value of each character from the Unicode encoding. Although 
0940      * in some cases the Unicode standard allows equivalent strings to be encoded using 
0941      * different sequences of characters, the JavaScript comparison operations do not 
0942      * detect these encoding differences; they assume that all strings are expressed in 
0943      * normalized form. Note in particular that string comparison is case-sensitive, and 
0944      * in the Unicode encoding (at least for the ASCII subset), all capital letters are 
0945      * "less than" all lowercase letters. This rule can cause confusing results if you do 
0946      * not expect it.</p>
0947      * <p>The less-than-or-equal and greater-than-or-equal operations do not rely on the 
0948      * equality or identity operations for determining whether two values are "equal." 
0949      * Instead, the less-than-or-equal operator is simply defined as "not greater than", 
0950      * and the greater-than-or-equal operator is defined as "not less than". The one 
0951      * exception occurs when either operand is (or converts to) <tt>NaN</tt>, in which case 
0952      * all comparison operations return <tt>false</tt>.</p>
0953      * @param o A value or object.
0954      * @return <tt>true</tt> if the current variable is greater than or equal to 
0955      * the second operand; otherwise <tt>false</tt>.
0956      * @since Descripter 1.0
0957      */
0958     public final boolean gte(Object o) {
0959         return gte(this, o);
0960     }
0961 
0962     /**
0963      * <p>Checks whether the two operands are "equal" using a more relaxed definition of 
0964      * sameness that allows type conversions, resembling the equality operator in 
0965      * JavaScript.</p>
0966      * <p>The equality and identity operations check whether two values are the same, using 
0967      * two different definitions of sameness. Both operations accept operands of any type, 
0968      * and both return <tt>true</tt> if their operands are the same and <tt>false</tt> 
0969      * if they are different. The identity operation checks whether its two operands are 
0970      * "identical" using a strict definition of sameness. The equality operation checks 
0971      * whether its two operands are "equal" using a more relaxed definition of sameness 
0972      * that allows type conversions.</p>
0973      * <p>The identity operation is standardized by ECMAScript v3 and implemented in 
0974      * JavaScript 1.3 and later. Be sure you understand the differences between the 
0975      * assignment, equality, and identity operations, and be careful to use the correct one 
0976      * when coding! Although it is tempting to call all three operations "equals," it may 
0977      * help to reduce confusion if you read "gets or is assigned" for assignment operation, 
0978      * "is equal to" for equality operation, and "is identical to" for identity operation.</p>
0979      * <p>In JavaScript, numbers, strings, and boolean values are compared by value. In this 
0980      * case, two separate values are involved, and the equality and identity operations 
0981      * check that these two values are identical. This means that two variables are equal 
0982      * or identical only if they contain the same value. For example, two strings are equal 
0983      * only if they each contain exactly the same characters.</p>
0984      * <p>On the other hand, objects, arrays, and functions are compared by reference. This 
0985      * means that two variables are equal only if they refer to the same object. Two 
0986      * separate arrays are never equal or identical, even if they contain equal or identical 
0987      * elements. Two variables that contain references to objects, arrays, or functions are 
0988      * equal only if they refer to the same object, array, or function. If you want to test 
0989      * that two distinct objects contain the same properties or that two distinct arrays 
0990      * contain the same elements, you'll have to check the properties or elements individually 
0991      * for equality or identity. And, if any of the properties or elements are themselves 
0992      * objects or arrays, you'll have to decide how deep you want the comparison to go.</p>
0993      * <p>The following rules determine whether two values are equal according to the 
0994      * equality operation:
0995      * <ul>
0996      * <li>If the two values have the same type, test them for identity. If the values are 
0997      * identical, they are equal; if they are not identical, they are not equal.</li>
0998      * <li>If the two values do not have the same type, they may still be equal. Use the 
0999      * following rules and type conversions to check for equality:</li>
1000      * <ul>
1001      * <li>If one value is null and the other is undefined, they are equal.</li>
1002      * <li>If one value is a number and the other is a string, convert the string to a 
1003      * number and try the comparison again, using the converted value.</li>
1004      * <li>If either value is <tt>true</tt>, convert it to 1 and try the comparison 
1005      * again. If either value is <tt>false</tt>, convert it to 0 and try the comparison 
1006      * again.</li>
1007      * <li>If one value is an object and the other is a number or string, convert the 
1008      * object to a primitive and try the comparison again. An object is converted to a 
1009      * primitive value by either its <tt>toString()</tt> method or its <tt>valueOf()</tt> 
1010      * method. The built-in classes of core JavaScript attempt <tt>valueOf()</tt> 
1011      * conversion before <tt>toString()</tt> conversion, except for the Date class, 
1012      * which performs <tt>toString()</tt> conversion. Objects that are not part of core 
1013      * JavaScript may convert themselves to primitive values in an implementation-defined 
1014      * way.</li>
1015      * <li>Any other combinations of values are not equal.</li>
1016      * </ul>
1017      * </ul>
1018      * @param o Any value or object.
1019      * @return <tt>true</tt> if the first operand equals the second; <tt>false</tt>, 
1020      * otherwise;
1021      * @since Descripter 1.0
1022      */
1023     public final boolean eq(Object o) {
1024         return eq(this, o);
1025     }
1026 
1027     /**
1028      * <p>Checks whether the two operands are "identical" using a strict definition of 
1029      * sameness, resembling the identity operator in JavaScript.</p>
1030      * <p>The equality and identity operations check whether two values are the same, using 
1031      * two different definitions of sameness. Both operations accept operands of any type, 
1032      * and both return <tt>true</tt> if their operands are the same and <tt>false</tt> 
1033      * if they are different. The identity operation checks whether its two operands are 
1034      * "identical" using a strict definition of sameness. The equality operation checks 
1035      * whether its two operands are "equal" using a more relaxed definition of sameness 
1036      * that allows type conversions.</p>
1037      * <p>The identity operation is standardized by ECMAScript v3 and implemented in 
1038      * JavaScript 1.3 and later. Be sure you understand the differences between the 
1039      * assignment, equality, and identity operations, and be careful to use the correct one 
1040      * when coding! Although it is tempting to call all three operations "equals," it may 
1041      * help to reduce confusion if you read "gets or is assigned" for assignment operation, 
1042      * "is equal to" for equality operation, and "is identical to" for identity operation.</p>
1043      * <p>In JavaScript, numbers, strings, and boolean values are compared by value. In this 
1044      * case, two separate values are involved, and the equality and identity operations 
1045      * check that these two values are identical. This means that two variables are equal 
1046      * or identical only if they contain the same value. For example, two strings are equal 
1047      * only if they each contain exactly the same characters.</p>
1048      * <p>On the other hand, objects, arrays, and functions are compared by reference. This 
1049      * means that two variables are equal only if they refer to the same object. Two 
1050      * separate arrays are never equal or identical, even if they contain equal or identical 
1051      * elements. Two variables that contain references to objects, arrays, or functions are 
1052      * equal only if they refer to the same object, array, or function. If you want to test 
1053      * that two distinct objects contain the same properties or that two distinct arrays 
1054      * contain the same elements, you'll have to check the properties or elements individually 
1055      * for equality or identity. And, if any of the properties or elements are themselves 
1056      * objects or arrays, you'll have to decide how deep you want the comparison to go.</p>
1057      * <p>The following rules determine whether two values are identical according to the identity operation:
1058      * <ul>
1059      * <li>If the two values have different types, they are not identical.</li>
1060      * <li>If both values are numbers and have the same value, they are identical, unless 
1061      * either or both values are <tt>NaN</tt>, in which case they are not identical. 
1062      * The <tt>NaN</tt> value is never identical to any other value, including itself! 
1063      * To check whether a value is <tt>NaN</tt>, use the global <tt>isNaN</tt> service.</li>
1064      * <li>If both values are strings and contain exactly the same characters in the same 
1065      * positions, they are identical. If the strings differ in length or content, they are 
1066      * not identical. Note that in some cases, the Unicode standard allows more than one 
1067      * way to encode the same string. For efficiency, however, JavaScript's string 
1068      * comparison compares strictly on a character-by-character basis, and it assumes that 
1069      * all strings have been converted to a "normalized form" before they are compared.</li>
1070      * <li>If both values are the boolean value <tt>true</tt> or both are the boolean 
1071      * value <tt>false</tt>, they are identical.</li>
1072      * <li>If both values refer to the same object, array, or function, they are identical. 
1073      * If they refer to different objects (or arrays or functions) they are not identical, 
1074      * even if both objects have identical properties or both arrays have identical elements.</li>
1075      * <li>If both values are null or both values are undefined, they are identical.</li>
1076      * </ul>
1077      * @param o Any value or object.
1078      * @return <tt>true</tt> if the first operand is identical to the second; 
1079      * <tt>false</tt>, otherwise;
1080      * @since Descripter 1.0
1081      */
1082     public final boolean eqs(Object o) {
1083         return eqs(this, o);
1084     }
1085 }