Merge pull request #5475 from Marcono1234/marcono1234/minus-literal

Java: Improve documentation regarding minus in front of numeric literals

Author: aschackmull

java/ql/src/semmle/code/java/Expr.qll

@@ -638,20 +638,54 @@ class BooleanLiteral extends Literal, @booleanliteral {
   override string getAPrimaryQlClass() { result = "BooleanLiteral" }
 }
 
-/** An integer literal. For example, `23`. */
+/**
+ * An integer literal. For example, `23`.
+ *
+ * An integer literal can never be negative except when:
+ * - It is written in binary, octal or hexadecimal notation
+ * - It is written in decimal notation, has the value `2147483648` and is preceded
+ *   by a minus; in this case the value of the IntegerLiteral is -2147483648 and
+ *   the preceding minus will *not* be modeled as `MinusExpr`.
+ *
+ * In all other cases the preceding minus, if any, will be modeled as a separate
+ * `MinusExpr`.
+ *
+ * The last exception is necessary because `2147483648` on its own would not be
+ * a valid integer literal (and could also not be parsed as CodeQL `int`).
+ */
 class IntegerLiteral extends Literal, @integerliteral {
   /** Gets the int representation of this literal. */
   int getIntValue() { result = getValue().toInt() }
 
   override string getAPrimaryQlClass() { result = "IntegerLiteral" }
 }
 
-/** A long literal. For example, `23l`. */
+/**
+ * A long literal. For example, `23L`.
+ *
+ * A long literal can never be negative except when:
+ * - It is written in binary, octal or hexadecimal notation
+ * - It is written in decimal notation, has the value `9223372036854775808` and
+ *   is preceded by a minus; in this case the value of the LongLiteral is
+ *   -9223372036854775808 and the preceding minus will *not* be modeled as
+ *   `MinusExpr`.
+ *
+ * In all other cases the preceding minus, if any, will be modeled as a separate
+ * `MinusExpr`.
+ *
+ * The last exception is necessary because `9223372036854775808` on its own
+ * would not be a valid long literal.
+ */
 class LongLiteral extends Literal, @longliteral {
   override string getAPrimaryQlClass() { result = "LongLiteral" }
 }
 
-/** A floating point literal. For example, `4.2f`. */
+/**
+ * A float literal. For example, `4.2f`.
+ *
+ * A float literal is never negative; a preceding minus, if any, will always
+ * be modeled as separate `MinusExpr`.
+ */
 class FloatingPointLiteral extends Literal, @floatingpointliteral {
   /**
    * Gets the value of this literal as CodeQL 64-bit `float`. The value will
@@ -662,7 +696,12 @@ class FloatingPointLiteral extends Literal, @floatingpointliteral {
   override string getAPrimaryQlClass() { result = "FloatingPointLiteral" }
 }
 
-/** A double literal. For example, `4.2`. */
+/**
+ * A double literal. For example, `4.2`.
+ *
+ * A double literal is never negative; a preceding minus, if any, will always
+ * be modeled as separate `MinusExpr`.
+ */
 class DoubleLiteral extends Literal, @doubleliteral {
   /**
    * Gets the value of this literal as CodeQL 64-bit `float`. The result will

java/ql/test/library-tests/literals-numeric/NumericLiterals.java

@@ -0,0 +1,16 @@
+class NumericLiterals {    
+	void negativeLiterals() {
+		float f = -1f;
+		double d = -1d;
+		int i1 = -2147483647;
+		int i2 = -2147483648; // CodeQL models minus as part of literal
+		int i3 = -0b10000000000000000000000000000000; // binary
+		int i4 = -020000000000; // octal
+		int i5 = -0x80000000; // hex
+		long l1 = -9223372036854775807L;
+		long l2 = -9223372036854775808L; // CodeQL models minus as part of literal
+		long l3 = -0b1000000000000000000000000000000000000000000000000000000000000000L; // binary
+		long l4 = -01000000000000000000000L; // octal
+		long l5 = -0x8000000000000000L; // hex
+	}
+}

java/ql/test/library-tests/literals-numeric/negativeNumericLiteral.expected

@@ -0,0 +1,12 @@
+| NumericLiterals.java:3:14:3:15 | 1f | 1.0 | NumericLiterals.java:3:13:3:15 | -... |
+| NumericLiterals.java:4:15:4:16 | 1d | 1.0 | NumericLiterals.java:4:14:4:16 | -... |
+| NumericLiterals.java:5:13:5:22 | 2147483647 | 2147483647 | NumericLiterals.java:5:12:5:22 | -... |
+| NumericLiterals.java:6:12:6:22 | -2147483648 | -2147483648 | NumericLiterals.java:6:7:6:22 | i2 |
+| NumericLiterals.java:7:13:7:46 | 0b10000000000000000000000000000000 | -2147483648 | NumericLiterals.java:7:12:7:46 | -... |
+| NumericLiterals.java:8:13:8:24 | 020000000000 | -2147483648 | NumericLiterals.java:8:12:8:24 | -... |
+| NumericLiterals.java:9:13:9:22 | 0x80000000 | -2147483648 | NumericLiterals.java:9:12:9:22 | -... |
+| NumericLiterals.java:10:14:10:33 | 9223372036854775807L | 9223372036854775807 | NumericLiterals.java:10:13:10:33 | -... |
+| NumericLiterals.java:11:13:11:33 | -9223372036854775808L | -9223372036854775808 | NumericLiterals.java:11:8:11:33 | l2 |
+| NumericLiterals.java:12:14:12:80 | 0b1000000000000000000000000000000000000000000000000000000000000000L | -9223372036854775808 | NumericLiterals.java:12:13:12:80 | -... |
+| NumericLiterals.java:13:14:13:37 | 01000000000000000000000L | -9223372036854775808 | NumericLiterals.java:13:13:13:37 | -... |
+| NumericLiterals.java:14:14:14:32 | 0x8000000000000000L | -9223372036854775808 | NumericLiterals.java:14:13:14:32 | -... |

java/ql/test/library-tests/literals-numeric/negativeNumericLiteral.ql

@@ -0,0 +1,9 @@
+import java
+
+from Literal l
+where
+  l instanceof IntegerLiteral or
+  l instanceof LongLiteral or
+  l instanceof FloatingPointLiteral or
+  l instanceof DoubleLiteral
+select l, l.getValue(), l.getParent()