JavaDoq: Var.java |

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 }

JavaDoq: Var.java |