Merge pull request #621 from cushon/typos

Fix some typos

Examples.md

@@ -0,0 +1,433 @@
+<h1>Examples</h1>
+<p>Imports used in the examples: </p>
+
+```
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Properties;
+```
+
+<p>This document's intention is to explain to new-comers the basics of this project</p>
+
+	
+<h2>Part 1: Creating a JSON document</h2>
+
+<h3>Using JSONArray</h3>
+
+```
+	private static void JSONExampleArray1() {
+		//We create a JSONObject from a String containing an array using JSONArray
+		//Firstly, we declare an Array in a String
+
+		 String arrayStr = 
+		            "["+"true,"+"false,"+ "\"true\","+ "\"false\","+"\"hello\","+"23.45e-4,"+
+		                "\"23.45\","+"42,"+"\"43\","+"["+"\"world\""+"],"+
+		            		"{"+
+		                    "\"key1\":\"value1\","+
+		                    "\"key2\":\"value2\","+
+		                    "\"key3\":\"value3\","+
+		                    "\"key4\":\"value4\""+
+		                "},"+
+		                "0,"+"\"-1\""+
+		            "]";
+
+		 //Then, we initializate the JSONArray thanks to its constructor
+
+		  JSONArray array = new JSONArray(arrayStr);
+		  System.out.println("Values array: "+ array);
+
+		  //We convert that array into a JSONObject, but first, we need the labels, so we need another JSONArray with the labels.
+		  //Here we will use an auxiliary function to get one for the example.
+
+		  JSONArray list = listNumberArray(array.length());
+		  System.out.println("Label Array: "+ list.toString());
+		  //Now, we construct the JSONObject using both the  value array and the label array.
+		  JSONObject object = array.toJSONObject(list);
+		  System.out.println("Final JSONOBject: " + object);
+	}
+
+	//This method creates an JSONArray of labels in which those are generated by their positions
+
+	private static JSONArray listNumberArray(int max){
+		 JSONArray res = new JSONArray();
+		for (int i=0; i<max;i++) {
+			//The value of the labels must be an String in order to make it work
+			res.put(String.valueOf(i));
+		}
+		return res;
+	}
+```
+```
+	private static void JSONExampleArray2() {
+
+		//We can also create an Array without a String by creating an empty array and adding elements to it
+
+		  JSONArray array = new JSONArray();
+
+		//Adding elements with .put()
+
+		array.put("value");
+		array.put(5);
+		array.put(-23.45e67);
+		array.put(true);
+		
+		//We convert it to JSONObject providing a label arrray like last time
+
+		 JSONArray list = listNumberArray(array.length());
+		 JSONObject object = array.toJSONObject(list);
+		 System.out.println("Final JSONOBject: " + object);
+	}
+```
+
+<h3>Using JSONStringer</h3>
+
+```
+	private static void JSONExampleStringer() {
+
+		//We initializate the JSONStringer
+
+		JSONStringer jsonStringer = new JSONStringer();
+
+		//Now we start the process of adding elements with .object()
+
+        jsonStringer.object();
+
+        //We can now add elements as keys and values with .values () and .key()
+
+        jsonStringer.key("trueValue").value(true);
+        jsonStringer.key("falseValue").value(false);
+        jsonStringer.key("nullValue").value(null);
+        jsonStringer.key("stringValue").value("hello world!");
+        jsonStringer.key("complexStringValue").value("h\be\tllo w\u1234orld!");
+        jsonStringer.key("intValue").value(42);
+        jsonStringer.key("doubleValue").value(-23.45e67);
+
+        //We end this prcedure with .ednObject
+
+        jsonStringer.endObject();
+
+       //Once we have a JSONStringer, we convert it to JSONObject generating a String and using JSONObject's contructor.
+
+        String str = jsonStringer.toString();
+        JSONObject jsonObject = new JSONObject(str);
+        
+       System.out.println("Final JSONOBject: " + jsonObject);
+	}
+```
+<h3>Using JSONObject</h3>
+
+```
+	private static void JSONExampleObject1() {
+
+		//We can create a JSONObject from a String with the class builder
+
+		String string = "{\"0\":\"value\",\"1\":5,\"2\":-2.345E68,\"3\":true}";
+		JSONObject example = new JSONObject(string);
+		System.out.println("Final JSONObject: " + example);
+		
+	}
+```
+```
+	private static void JSONExampleObject2() {
+
+		//We can also create a JSONObject directly without messing around with any of the other functions.
+
+		JSONObject example = new JSONObject();
+
+
+		//Now we add the keys and values in a similar way as the Stringer method
+		example.put("key", "value");
+
+		//As you can see, the first entry is the key and the second would be its associeted value.
+
+		example.put("key2", 5);
+		example.put("key3", -23.45e67);
+		example.put("trueValue", true);
+
+		//We can't add null values thougth
+
+		//example.put("nullValue", null); //This is not possible
+		
+		 System.out.println("Final JSONOBject: " + example);
+	}
+```
+```
+	private static void JSONExampleObject3() {
+
+		//We can also create a JSONObject with a Java Map
+		//YoU will need a Map whose keys are Strings. The values can be whatever you want
+
+		Map<String,Double> map = new HashMap<String, Double>();
+		
+		map.put("key1", 1.0);
+		map.put("key2", -23.45e67);
+		
+		//We create the JSONObject with the map with its class builder
+
+		JSONObject example = new JSONObject(map);
+		 System.out.println("Final JSONOBject: " + example);
+	}
+```
+<h3>Using JSONWriter</h3>
+
+```	
+	private static void JSONExamplWriter() {
+
+		//This method works in a very similar way to Object  and Stringer in the construction of the JSON.
+		//The difference is that it needs a Java object called "Appendable" like StringBuilder
+
+		StringBuilder write = new StringBuilder();
+		JSONWriter jsonWriter = new JSONWriter(write);
+
+		//We behave now the same way as Stringer
+
+		jsonWriter.object();
+		
+		jsonWriter.key("trueValue").value(true);
+		jsonWriter.key("falseValue").value(false);
+		jsonWriter.key("nullValue").value(null);
+		jsonWriter.key("stringValue").value("hello world!");
+		jsonWriter.key("complexStringValue").value("h\be\tllo w\u1234orld!");
+		jsonWriter.key("intValue").value(42);
+		jsonWriter.key("doubleValue").value(-23.45e67);
+		
+		jsonWriter.endObject();
+		
+		//The resoult should be in the "write" object
+		
+		System.out.println("JSON: " + write.toString());
+		
+		//The difference is that we don't get a JSONObject in this one.
+		
+		
+	}
+```
+```	
+	private static void JSONExampleTokener() {
+
+		//A partir de una String podemos crear un JSONTokener, que lo podemos usar alternativamente para JSONArray,JSONObject
+
+		String string = "this is not a valid JSON string";
+		JSONTokener token = new JSONTokener(string);
+		
+		//Now you can use the token in JSONObject and Array the same way as a String
+
+		JSONObject object = new JSONObject(token);
+		JSONArray array = new JSONArray(token);
+		
+	}
+```	
+<h2>Part 2: Conversion methods</h2>
+<p>We don't need to have a JSON docuemnt to work. This project also admits conversions from other type of files.</p>
+<p>Secondly, we can also convert from JSON to those type of files.</p>
+	
+<h3>Extra: Conversion to JSONArray</h3>
+
+```
+	private static void JSONObjectToArray() {
+		//We start with a JSONObject
+
+		String string = "{\"0\":\"value\",\"1\":5,\"2\":-2.345E68,\"3\":true}";
+
+		JSONObject example = new JSONObject(string);
+		
+		//We need a list of key strings like the reverse operation
+		
+		JSONArray keyStrings = listNumberArray(example.length());
+		
+		//Then we convert to the Array using both elelements
+		
+		JSONArray array = example.toJSONArray(keyStrings);
+		
+		System.out.println("Final JSONArray: " + array);
+	}
+```
+<h3>XML Conversions</h3>
+
+```		
+	private static void XMLToExampleConversion() {
+
+		//We start with a JSONObject
+		
+		String string = "{\"0\":\"value\",\"1\":5,\"2\":-2.345E68,\"3\":true}";
+		JSONObject example = new JSONObject(string);
+
+		//We obtain a String with XML format with toString()
+
+		String output = XML.toString(example);
+		System.out.println("Final XML: " + output);
+	}
+```
+```	
+	private static void XMLFromExampleConversion() {
+
+		//We start with a string with  the XML format
+
+		String string = "<0>value</0><1>5</1><2>-2.345E+68</2><3>true</3>";
+
+		//We obtain a JSONObject with toJSONOBject()
+
+		JSONObject output = XML.toJSONObject(string);
+		
+		System.out.println("Final JSONObject: " + output);
+	}
+```
+<h3>Cookie Conversions</h3>
+
+```
+	private static void CookieToExampleConversion() {
+
+		//We start with a JSONObject
+		//The JSONOBject needs to entries that gives the cookie a name and gives the field "name" a name too.
+		//The Cokkie format doesn't support booleans
+
+		String string = "{\"name\":\"Cookie-Name\",\"value\":\"name\",\"1\":5,\"2\":-2.345E68,\"3\":'true'}";
+		JSONObject example = new JSONObject(string);
+		
+		//We obtain a String with Cookie format with toString()
+
+		String output = Cookie.toString(example);
+		System.out.println("Final Cookie: " + output);
+	}
+```
+```
+	private static void CookieFromExampleConversion() {
+
+		//We start with a string with  the Cookie format
+
+		String string = "Cookie-Name=name;1=5;2=-2.345E%2b68;3=true";
+
+		//We obtain a JSONObject with toJSONOBject()
+
+		JSONObject output = Cookie.toJSONObject(string);
+		System.out.println("Final JSONObject: " + output);
+	}
+```
+
+<h3>HTTP Conversions</h3>
+
+```
+	private static void HTTPToExampleConversion() {
+
+		//We start with a JSONObject
+		//The JSONObject must have the minimun header for a HTTP request or header
+
+		String string = "{\"Method\":\"POST\",\"Request-URI\":'/',\"HTTP-Version\":'HTTP/1.1',\"Value1\":true,\"Value2\":2,\"Value3\":-2.345E68}";
+
+		JSONObject example = new JSONObject(string);
+
+		//We obtain a String with HTTP format with toString()
+
+		String output = HTTP.toString(example);
+		System.out.println("Final HTTP: " + output);
+	}
+```
+```	
+	private static void HTTPFromExampleConversion() {
+
+		//We start with a string with  the HTTP format
+
+		String string = "Final HTTP: POST '/' HTTP/1.1 Value3: -2.345E+68 Value1: true Value2: 2";
+
+		//We obtain a JSONObject with toJSONOBject()
+
+		JSONObject output = HTTP.toJSONObject(string);
+		System.out.println("Final JSONObject: " + output);
+	}
+```
+<h3>CDL Conversions</h3>
+
+```	
+private static void CDLToExampleConversion() {
+
+		//We start with some JSONObjects with the same values in the keys but different values in the "values"
+
+		String string = "{\"0\":\"value\",\"1\":5,\"2\":-2.345E68,\"3\":true}";
+		JSONObject example = new JSONObject(string);
+		
+		String string2 = "{\"0\":\"value2\",\"1\":6,\"2\":-8.345E68,\"3\":false}";
+		JSONObject example2 = new JSONObject(string2);
+		
+		//We need now a JSONArray with those JSONObjects
+
+		JSONArray array = new JSONArray();
+		array.put(example);
+		array.put(example2);
+
+		//We obtain a String with XML format with toString()
+
+		String output = CDL.toString(array);
+		System.out.println("Final CDL: \r\n" + output);
+	}
+```	
+```	
+private static void CDLFromExampleConversion() {
+
+	//We start wtih a String with the CDL format
+
+	String string = "0,1,2,3\n"
+			+ "value,5,-2.345E+68,true\n"
+			+ "value2,6,-8.345E+68,false";
+	
+	//We obtain a JSONArray with toJSONOBject()
+
+	JSONArray output = CDL.toJSONArray(string);
+	System.out.println("Final JSONArray: " + output);
+}
+```
+<h3>Properties Conversions</h3>
+
+```
+	private static Properties PropertyToExampleConversion() {
+
+	//We start with a JSONObject
+
+	String string = "{\"0\":\"value\",\"1\":5,\"2\":-2.345E68,\"3\":true}";
+	JSONObject example = new JSONObject(string);
+
+	//We obtain a String with Properties format with toString()
+
+	Properties output = Property.toProperties(example);
+	System.out.println("Final Properties: " + output);
+
+	return output;
+	}
+```
+```	
+	private static void PropertyFromExampleConversion() {
+
+		//We start with a Properties object
+
+		Properties input = PropertyToExampleConversion();
+
+		//We obtain a JSONObject with toJSONOBject()
+
+		JSONObject output = Property.toJSONObject(input);
+		System.out.println("Final JSONObject: " + output);
+	}
+```
+<h2>List of all examples methods</h2>
+
+```
+	public static void main(String[] args) {
+		//JSONObjectToArray();
+		//JSONExampleArray1();
+		//JSONExampleArray2();
+		//JSONExampleStringer();
+		//JSONExampleObject1();
+		//JSONExampleObject2();
+		//JSONExampleObject3();
+		//JSONExamplWriter();
+		//XMLToExampleConversion();
+		//XMLFromExampleConversion();
+		//CookieToExampleConversion();
+		//CookieFromExampleConversion(); 
+		//HTTPToExampleConversion();
+		//HTTPFromExampleConversion();
+		//CDLToExampleConversion();
+		//CDLFromExampleConversion();
+		//PropertyToExampleConversion();
+		//PropertyFromExampleConversion();
+	}
+```
+

README.md

@@ -1,9 +1,15 @@
+![Json-Java logo](https://github.com/stleary/JSON-java/blob/master/images/JsonJava.png?raw=true)
+
+<sub><sup>image credit: Ismael Pérez Ortiz</sup></sub>
+
+
 JSON in Java [package org.json]
 ===============================
 
 [![Maven Central](https://img.shields.io/maven-central/v/org.json/json.svg)](https://mvnrepository.com/artifact/org.json/json)
 
-**[Click here if you just want the latest release jar file.](https://repo1.maven.org/maven2/org/json/json/20200518/json-20200518.jar)**
+**[Click here if you just want the latest release jar file.](https://search.maven.org/remotecontent?filepath=org/json/json/20210307/json-20210307.jar)**
+
 
 # Overview
 
@@ -246,6 +252,8 @@ and artifactId "json". For example:
 [https://search.maven.org/search?q=g:org.json%20AND%20a:json&core=gav](https://search.maven.org/search?q=g:org.json%20AND%20a:json&core=gav)
 
 ~~~
+20210307    Recent commits and potentially breaking fix to JSONPointer
+
 20201115    Recent commits and first release after project structure change
 
 20200518    Recent commits and snapshot before project structure change

SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please follow the instructions in the ["How are vulnerabilities and exploits handled?"](https://github.com/stleary/JSON-java/wiki/FAQ#how-are-vulnerabilities-and-exploits-handled) section in the FAQ.

build.gradle

@@ -13,17 +13,14 @@ apply plugin: 'maven-publish'
 
 repositories {
     mavenLocal()
+    mavenCentral()
     maven {
         url = uri('https://oss.sonatype.org/content/repositories/snapshots')
     }
-
-    maven {
-        url = uri('http://repo.maven.apache.org/maven2')
-    }
 }
 
 dependencies {
-    testImplementation 'junit:junit:4.12'
+    testImplementation 'junit:junit:4.13.1'
     testImplementation 'com.jayway.jsonpath:json-path:2.1.0'
     testImplementation 'org.mockito:mockito-core:1.9.5'
 }

pom.xml

@@ -3,7 +3,7 @@
 
     <groupId>org.json</groupId>
     <artifactId>json</artifactId>
-    <version>v20200429-SNAPSHOT</version>
+    <version>20210307</version>
     <packaging>bundle</packaging>
 
     <name>JSON in Java</name>
@@ -80,7 +80,7 @@
         <dependency>
             <groupId>junit</groupId>
             <artifactId>junit</artifactId>
-            <version>4.12</version>
+            <version>4.13.1</version>
             <scope>test</scope>
         </dependency>
         <dependency>

src/main/java/org/json/Cookie.java

@@ -109,7 +109,7 @@ public class Cookie {
         // parse the remaining cookie attributes
         while (x.more()) {
             name = unescape(x.nextTo("=;")).trim().toLowerCase(Locale.ROOT);
-            // don't allow a cookies attributes to overwrite it's name or value.
+            // don't allow a cookies attributes to overwrite its name or value.
             if("name".equalsIgnoreCase(name)) {
                 throw new JSONException("Illegal attribute name: 'name'");
             }

src/main/java/org/json/JSONArray.java

@@ -326,7 +326,7 @@ public class JSONArray implements Iterable<Object> {
     public float getFloat(int index) throws JSONException {
         final Object object = this.get(index);
         if(object instanceof Number) {
-            return ((Float)object).floatValue();
+            return ((Number)object).floatValue();
         }
         try {
             return Float.parseFloat(object.toString());
@@ -385,7 +385,7 @@ public class JSONArray implements Iterable<Object> {
 
     /**
      * Get the BigDecimal value associated with an index. If the value is float
-     * or double, the the {@link BigDecimal#BigDecimal(double)} constructor
+     * or double, the {@link BigDecimal#BigDecimal(double)} constructor
      * will be used. See notes on the constructor for conversion issues that
      * may arise.
      *
@@ -567,6 +567,14 @@ public class JSONArray implements Iterable<Object> {
         return this.myArrayList.size();
     }
 
+    /**
+     * Removes all of the elements from this JSONArray.
+     * The JSONArray will be empty after this call returns.
+     */
+    public void clear() {
+        this.myArrayList.clear();
+    }
+
     /**
      * Get the optional object value associated with an index.
      *
@@ -784,7 +792,7 @@ public class JSONArray implements Iterable<Object> {
      * Get the optional BigDecimal value associated with an index. The 
      * defaultValue is returned if there is no value for the index, or if the 
      * value is not a number and cannot be converted to a number. If the value
-     * is float or double, the the {@link BigDecimal#BigDecimal(double)}
+     * is float or double, the {@link BigDecimal#BigDecimal(double)}
      * constructor will be used. See notes on the constructor for conversion
      * issues that may arise.
      *
@@ -1149,7 +1157,7 @@ public class JSONArray implements Iterable<Object> {
      *            The Map value.
      * @return this.
      * @throws JSONException
-     *             If the index is negative or if the the value is an invalid
+     *             If the index is negative or if the value is an invalid
      *             number.
      * @throws NullPointerException
      *             If a key in the map is <code>null</code>
@@ -1172,7 +1180,7 @@ public class JSONArray implements Iterable<Object> {
      *            String, or the JSONObject.NULL object.
      * @return this.
      * @throws JSONException
-     *             If the index is negative or if the the value is an invalid
+     *             If the index is negative or if the value is an invalid
      *             number.
      */
     public JSONArray put(int index, Object value) throws JSONException {
@@ -1374,6 +1382,10 @@ public class JSONArray implements Iterable<Object> {
                 if (!((JSONArray)valueThis).similar(valueOther)) {
                     return false;
                 }
+            } else if (valueThis instanceof Number && valueOther instanceof Number) {
+                if (!JSONObject.isNumberSimilar((Number)valueThis, (Number)valueOther)) {
+                	return false;
+                }
             } else if (!valueThis.equals(valueOther)) {
                 return false;
             }

src/main/java/org/json/JSONObject.java

@@ -128,6 +128,7 @@ public class JSONObject {
          *         null.
          */
         @Override
+        @SuppressWarnings("lgtm[java/unchecked-cast-in-equals]")
         public boolean equals(Object object) {
             return object == null || object == this;
         }
@@ -151,10 +152,10 @@ public class JSONObject {
             return "null";
         }
     }
-    
+
     /**
      *  Regular Expression Pattern that matches JSON Numbers. This is primarily used for
-     *  output to guarantee that we are always writing valid JSON. 
+     *  output to guarantee that we are always writing valid JSON.
      */
     static final Pattern NUMBER_PATTERN = Pattern.compile("-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?");
 
@@ -175,10 +176,10 @@ public class JSONObject {
      * Construct an empty JSONObject.
      */
     public JSONObject() {
-        // HashMap is used on purpose to ensure that elements are unordered by 
+        // HashMap is used on purpose to ensure that elements are unordered by
         // the specification.
-        // JSON tends to be a portable transfer format to allows the container 
-        // implementations to rearrange their items for a faster element 
+        // JSON tends to be a portable transfer format to allows the container
+        // implementations to rearrange their items for a faster element
         // retrieval based on associative access.
         // Therefore, an implementation mustn't rely on the order of the item.
         this.map = new HashMap<String, Object>();
@@ -239,9 +240,9 @@ public class JSONObject {
             if (c != ':') {
                 throw x.syntaxError("Expected a ':' after a key");
             }
-            
+
             // Use syntaxError(..) to include error location
-            
+
             if (key != null) {
                 // Check if key exists
                 if (this.opt(key) != null) {
@@ -350,11 +351,11 @@ public class JSONObject {
      * method from being serialized:
      * <pre>
      * &#64;JSONPropertyName("FullName")
-     * &#64;JSONPropertyIgnore 
+     * &#64;JSONPropertyIgnore
      * public String getName() { return this.name; }
      * </pre>
      * <p>
-     * 
+     *
      * @param bean
      *            An object that has getter methods that should be used to make
      *            a JSONObject.
@@ -448,12 +449,12 @@ public class JSONObject {
             }
         }
     }
-    
+
     /**
-     * Constructor to specify an initial capacity of the internal map. Useful for library 
+     * Constructor to specify an initial capacity of the internal map. Useful for library
      * internal calls where we know, or at least can best guess, how big this JSONObject
      * will be.
-     * 
+     *
      * @param initialCapacity initial capacity of the internal map.
      */
     protected JSONObject(int initialCapacity){
@@ -576,7 +577,7 @@ public class JSONObject {
 
     /**
      * Get the enum value associated with a key.
-     * 
+     *
      * @param <E>
      *            Enum Type
      * @param clazz
@@ -630,7 +631,7 @@ public class JSONObject {
      *            A key string.
      * @return The numeric value.
      * @throws JSONException
-     *             if the key is not found or if the value cannot 
+     *             if the key is not found or if the value cannot
      *             be converted to BigInteger.
      */
     public BigInteger getBigInteger(String key) throws JSONException {
@@ -644,7 +645,7 @@ public class JSONObject {
 
     /**
      * Get the BigDecimal value associated with a key. If the value is float or
-     * double, the the {@link BigDecimal#BigDecimal(double)} constructor will
+     * double, the {@link BigDecimal#BigDecimal(double)} constructor will
      * be used. See notes on the constructor for conversion issues that may
      * arise.
      *
@@ -929,7 +930,7 @@ public class JSONObject {
      * modify the JSONObject. Use with caution.
      *
      * @see Set#iterator()
-     * 
+     *
      * @return An iterator of the keys.
      */
     public Iterator<String> keys() {
@@ -950,10 +951,10 @@ public class JSONObject {
 
     /**
      * Get a set of entries of the JSONObject. These are raw values and may not
-     * match what is returned by the JSONObject get* and opt* functions. Modifying 
+     * match what is returned by the JSONObject get* and opt* functions. Modifying
      * the returned EntrySet or the Entry objects contained therein will modify the
      * backing JSONObject. This does not return a clone or a read-only view.
-     * 
+     *
      * Use with caution.
      *
      * @see Map#entrySet()
@@ -973,6 +974,14 @@ public class JSONObject {
         return this.map.size();
     }
 
+    /**
+     * Removes all of the elements from this JSONObject.
+     * The JSONObject will be empty after this call returns.
+     */
+    public void clear() {
+        this.map.clear();
+    }
+
     /**
      * Check if JSONObject is empty.
      *
@@ -1039,7 +1048,7 @@ public class JSONObject {
 
     /**
      * Get the enum value associated with a key.
-     * 
+     *
      * @param <E>
      *            Enum Type
      * @param clazz
@@ -1054,7 +1063,7 @@ public class JSONObject {
 
     /**
      * Get the enum value associated with a key.
-     * 
+     *
      * @param <E>
      *            Enum Type
      * @param clazz
@@ -1148,9 +1157,21 @@ public class JSONObject {
      * @param val value to convert
      * @param defaultValue default value to return is the conversion doesn't work or is null.
      * @return BigDecimal conversion of the original value, or the defaultValue if unable
-     *          to convert. 
+     *          to convert.
      */
     static BigDecimal objectToBigDecimal(Object val, BigDecimal defaultValue) {
+        return objectToBigDecimal(val, defaultValue, true);
+    }
+    
+    /**
+     * @param val value to convert
+     * @param defaultValue default value to return is the conversion doesn't work or is null.
+     * @param exact When <code>true</code>, then {@link Double} and {@link Float} values will be converted exactly.
+     *      When <code>false</code>, they will be converted to {@link String} values before converting to {@link BigDecimal}.
+     * @return BigDecimal conversion of the original value, or the defaultValue if unable
+     *          to convert.
+     */
+    static BigDecimal objectToBigDecimal(Object val, BigDecimal defaultValue, boolean exact) {
         if (NULL.equals(val)) {
             return defaultValue;
         }
@@ -1161,11 +1182,17 @@ public class JSONObject {
             return new BigDecimal((BigInteger) val);
         }
         if (val instanceof Double || val instanceof Float){
-            final double d = ((Number) val).doubleValue();
-            if(Double.isNaN(d)) {
+            if (!numberIsFinite((Number)val)) {
                 return defaultValue;
             }
-            return new BigDecimal(((Number) val).doubleValue());
+            if (exact) {
+                return new BigDecimal(((Number)val).doubleValue());
+            }else {
+                // use the string constructor so that we maintain "nice" values for doubles and floats
+                // the double constructor will translate doubles to "exact" values instead of the likely
+                // intended representation
+                return new BigDecimal(val.toString());
+            }
         }
         if (val instanceof Long || val instanceof Integer
                 || val instanceof Short || val instanceof Byte){
@@ -1199,7 +1226,7 @@ public class JSONObject {
      * @param val value to convert
      * @param defaultValue default value to return is the conversion doesn't work or is null.
      * @return BigInteger conversion of the original value, or the defaultValue if unable
-     *          to convert. 
+     *          to convert.
      */
     static BigInteger objectToBigInteger(Object val, BigInteger defaultValue) {
         if (NULL.equals(val)) {
@@ -1212,11 +1239,10 @@ public class JSONObject {
             return ((BigDecimal) val).toBigInteger();
         }
         if (val instanceof Double || val instanceof Float){
-            final double d = ((Number) val).doubleValue();
-            if(Double.isNaN(d)) {
+            if (!numberIsFinite((Number)val)) {
                 return defaultValue;
             }
-            return new BigDecimal(d).toBigInteger();
+            return new BigDecimal(((Number) val).doubleValue()).toBigInteger();
         }
         if (val instanceof Long || val instanceof Integer
                 || val instanceof Short || val instanceof Byte){
@@ -1224,7 +1250,7 @@ public class JSONObject {
         }
         // don't check if it's a string in case of unchecked Number subclasses
         try {
-            // the other opt functions handle implicit conversions, i.e. 
+            // the other opt functions handle implicit conversions, i.e.
             // jo.put("double",1.1d);
             // jo.optInt("double"); -- will return 1, not an error
             // this conversion to BigDecimal then to BigInteger is to maintain
@@ -1364,9 +1390,21 @@ public class JSONObject {
      *            A key string.
      * @return A JSONObject which is the value.
      */
-    public JSONObject optJSONObject(String key) {
+    public JSONObject optJSONObject(String key) { return this.optJSONObject(key, null); }
+
+    /**
+     * Get an optional JSONObject associated with a key, or the default if there
+     * is no such key or if the value is not a JSONObject.
+     *
+     * @param key
+     *            A key string.
+     * @param defaultValue
+     *            The default.
+     * @return An JSONObject which is the value.
+     */
+    public JSONObject optJSONObject(String key, JSONObject defaultValue) {
         Object object = this.opt(key);
-        return object instanceof JSONObject ? (JSONObject) object : null;
+        return object instanceof JSONObject ? (JSONObject) object : defaultValue;
     }
 
     /**
@@ -1398,10 +1436,10 @@ public class JSONObject {
         if (val == null) {
             return defaultValue;
         }
-        
+
         return val.longValue();
     }
-    
+
     /**
      * Get an optional {@link Number} value associated with a key, or <code>null</code>
      * if there is no such key or if the value is not a number. If the value is a string,
@@ -1436,14 +1474,14 @@ public class JSONObject {
         if (val instanceof Number){
             return (Number) val;
         }
-        
+
         try {
             return stringToNumber(val.toString());
         } catch (Exception e) {
             return defaultValue;
         }
     }
-    
+
     /**
      * Get an optional string associated with a key. It returns an empty string
      * if there is no such key. If the value is not a string and is not null,
@@ -1552,7 +1590,7 @@ public class JSONObject {
         // if the first letter in the key is not uppercase, then skip.
         // This is to maintain backwards compatibility before PR406
         // (https://github.com/stleary/JSON-java/pull/406/)
-        if (Character.isLowerCase(key.charAt(0))) {
+        if (key.length() == 0 || Character.isLowerCase(key.charAt(0))) {
             return null;
         }
         if (key.length() == 1) {
@@ -1575,7 +1613,7 @@ public class JSONObject {
      * @param annotationClass
      *            annotation to look for
      * @return the {@link Annotation} if the annotation exists on the current method
-     *         or one of it's super class definitions
+     *         or one of its super class definitions
      */
     private static <A extends Annotation> A getAnnotation(final Method m, final Class<A> annotationClass) {
         // if we have invalid data the result is null
@@ -1621,9 +1659,6 @@ public class JSONObject {
      * implementations and interfaces has the annotation. Returns the depth of the
      * annotation in the hierarchy.
      *
-     * @param <A>
-     *            type of the annotation
-     *
      * @param m
      *            method to check
      * @param annotationClass
@@ -1729,7 +1764,7 @@ public class JSONObject {
     public JSONObject put(String key, double value) throws JSONException {
         return this.put(key, Double.valueOf(value));
     }
-    
+
     /**
      * Put a key/float pair in the JSONObject.
      *
@@ -1873,7 +1908,7 @@ public class JSONObject {
     }
 
     /**
-     * Creates a JSONPointer using an initialization string and tries to 
+     * Creates a JSONPointer using an initialization string and tries to
      * match it to an item within this JSONObject. For example, given a
      * JSONObject initialized with this document:
      * <pre>
@@ -1881,13 +1916,13 @@ public class JSONObject {
      *     "a":{"b":"c"}
      * }
      * </pre>
-     * and this JSONPointer string: 
+     * and this JSONPointer string:
      * <pre>
      * "/a/b"
      * </pre>
      * Then this method will return the String "c".
      * A JSONPointerException may be thrown from code called by this method.
-     *   
+     *
      * @param jsonPointer string that can be used to create a JSONPointer
      * @return the item matched by the JSONPointer, otherwise null
      */
@@ -1895,7 +1930,7 @@ public class JSONObject {
         return query(new JSONPointer(jsonPointer));
     }
     /**
-     * Uses a user initialized JSONPointer  and tries to 
+     * Uses a user initialized JSONPointer  and tries to
      * match it to an item within this JSONObject. For example, given a
      * JSONObject initialized with this document:
      * <pre>
@@ -1903,24 +1938,24 @@ public class JSONObject {
      *     "a":{"b":"c"}
      * }
      * </pre>
-     * and this JSONPointer: 
+     * and this JSONPointer:
      * <pre>
      * "/a/b"
      * </pre>
      * Then this method will return the String "c".
      * A JSONPointerException may be thrown from code called by this method.
-     *   
+     *
      * @param jsonPointer string that can be used to create a JSONPointer
      * @return the item matched by the JSONPointer, otherwise null
      */
     public Object query(JSONPointer jsonPointer) {
         return jsonPointer.queryFrom(this);
     }
-    
+
     /**
      * Queries and returns a value from this object using {@code jsonPointer}, or
      * returns null if the query fails due to a missing key.
-     * 
+     *
      * @param jsonPointer the string representation of the JSON pointer
      * @return the queried value or {@code null}
      * @throws IllegalArgumentException if {@code jsonPointer} has invalid syntax
@@ -1928,11 +1963,11 @@ public class JSONObject {
     public Object optQuery(String jsonPointer) {
     	return optQuery(new JSONPointer(jsonPointer));
     }
-    
+
     /**
      * Queries and returns a value from this object using {@code jsonPointer}, or
      * returns null if the query fails due to a missing key.
-     * 
+     *
      * @param jsonPointer The JSON pointer
      * @return the queried value or {@code null}
      * @throws IllegalArgumentException if {@code jsonPointer} has invalid syntax
@@ -2073,6 +2108,10 @@ public class JSONObject {
                     if (!((JSONArray)valueThis).similar(valueOther)) {
                         return false;
                     }
+                } else if (valueThis instanceof Number && valueOther instanceof Number) {
+                    if (!isNumberSimilar((Number)valueThis, (Number)valueOther)) {
+                    	return false;
+                    };
                 } else if (!valueThis.equals(valueOther)) {
                     return false;
                 }
@@ -2082,10 +2121,59 @@ public class JSONObject {
             return false;
         }
     }
-    
+
+    /**
+     * Compares two numbers to see if they are similar.
+     *
+     * If either of the numbers are Double or Float instances, then they are checked to have
+     * a finite value. If either value is not finite (NaN or &#177;infinity), then this
+     * function will always return false. If both numbers are finite, they are first checked
+     * to be the same type and implement {@link Comparable}. If they do, then the actual
+     * {@link Comparable#compareTo(Object)} is called. If they are not the same type, or don't
+     * implement Comparable, then they are converted to {@link BigDecimal}s. Finally the
+     * BigDecimal values are compared using {@link BigDecimal#compareTo(BigDecimal)}.
+     *
+     * @param l the Left value to compare. Can not be <code>null</code>.
+     * @param r the right value to compare. Can not be <code>null</code>.
+     * @return true if the numbers are similar, false otherwise.
+     */
+    static boolean isNumberSimilar(Number l, Number r) {
+        if (!numberIsFinite(l) || !numberIsFinite(r)) {
+            // non-finite numbers are never similar
+            return false;
+        }
+
+        // if the classes are the same and implement Comparable
+        // then use the built in compare first.
+        if(l.getClass().equals(r.getClass()) && l instanceof Comparable) {
+            @SuppressWarnings({ "rawtypes", "unchecked" })
+            int compareTo = ((Comparable)l).compareTo(r);
+            return compareTo==0;
+        }
+
+        // BigDecimal should be able to handle all of our number types that we support through
+        // documentation. Convert to BigDecimal first, then use the Compare method to
+        // decide equality.
+        final BigDecimal lBigDecimal = objectToBigDecimal(l, null, false);
+        final BigDecimal rBigDecimal = objectToBigDecimal(r, null, false);
+        if (lBigDecimal == null || rBigDecimal == null) {
+            return false;
+        }
+        return lBigDecimal.compareTo(rBigDecimal) == 0;
+    }
+
+    private static boolean numberIsFinite(Number n) {
+        if (n instanceof Double && (((Double) n).isInfinite() || ((Double) n).isNaN())) {
+            return false;
+        } else if (n instanceof Float && (((Float) n).isInfinite() || ((Float) n).isNaN())) {
+            return false;
+        }
+        return true;
+    }
+
     /**
      * Tests if the value should be tried as a decimal. It makes no test if there are actual digits.
-     * 
+     *
      * @param val value to test
      * @return true if the string is "-0" or if it contains '.', 'e', or 'E', false otherwise.
      */
@@ -2093,12 +2181,12 @@ public class JSONObject {
         return val.indexOf('.') > -1 || val.indexOf('e') > -1
                 || val.indexOf('E') > -1 || "-0".equals(val);
     }
-    
+
     /**
-     * Converts a string to a number using the narrowest possible type. Possible 
+     * Converts a string to a number using the narrowest possible type. Possible
      * returns for this function are BigDecimal, Double, BigInteger, Long, and Integer.
      * When a Double is returned, it should always be a valid Double and not NaN or +-infinity.
-     * 
+     *
      * @param val value to convert
      * @return Number representation of the value.
      * @throws NumberFormatException thrown if the value is not a valid number. A public
@@ -2147,8 +2235,8 @@ public class JSONObject {
             // integer representation.
             // This will narrow any values to the smallest reasonable Object representation
             // (Integer, Long, or BigInteger)
-            
-            // BigInteger down conversion: We use a similar bitLenth compare as
+
+            // BigInteger down conversion: We use a similar bitLength compare as
             // BigInteger#intValueExact uses. Increases GC, but objects hold
             // only what they need. i.e. Less runtime overhead if the value is
             // long lived.
@@ -2216,18 +2304,8 @@ public class JSONObject {
      *             If o is a non-finite number.
      */
     public static void testValidity(Object o) throws JSONException {
-        if (o != null) {
-            if (o instanceof Double) {
-                if (((Double) o).isInfinite() || ((Double) o).isNaN()) {
-                    throw new JSONException(
-                            "JSON does not allow non-finite numbers.");
-                }
-            } else if (o instanceof Float) {
-                if (((Float) o).isInfinite() || ((Float) o).isNaN()) {
-                    throw new JSONException(
-                            "JSON does not allow non-finite numbers.");
-                }
-            }
+        if (o instanceof Number && !numberIsFinite((Number) o)) {
+            throw new JSONException("JSON does not allow non-finite numbers.");
         }
     }
 
@@ -2260,7 +2338,7 @@ public class JSONObject {
      * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
      * </b>
-     * 
+     *
      * @return a printable, displayable, portable, transmittable representation
      *         of the object, beginning with <code>{</code>&nbsp;<small>(left
      *         brace)</small> and ending with <code>}</code>&nbsp;<small>(right
@@ -2277,11 +2355,11 @@ public class JSONObject {
 
     /**
      * Make a pretty-printed JSON text of this JSONObject.
-     * 
+     *
      * <p>If <pre>{@code indentFactor > 0}</pre> and the {@link JSONObject}
      * has only one key, then the object will be output on a single line:
      * <pre>{@code {"key": 1}}</pre>
-     * 
+     *
      * <p>If an object has 2 or more keys, then it will be output across
      * multiple lines: <pre>{@code {
      *  "key1": 1,
@@ -2354,7 +2432,7 @@ public class JSONObject {
      */
     public static Object wrap(Object object) {
         try {
-            if (object == null) {
+            if (NULL.equals(object)) {
                 return NULL;
             }
             if (object instanceof JSONObject || object instanceof JSONArray
@@ -2459,11 +2537,11 @@ public class JSONObject {
 
     /**
      * Write the contents of the JSONObject as JSON text to a writer.
-     * 
+     *
      * <p>If <pre>{@code indentFactor > 0}</pre> and the {@link JSONObject}
      * has only one key, then the object will be output on a single line:
      * <pre>{@code {"key": 1}}</pre>
-     * 
+     *
      * <p>If an object has 2 or more keys, then it will be output across
      * multiple lines: <pre>{@code {
      *  "key1": 1,
@@ -2565,7 +2643,7 @@ public class JSONObject {
         }
         return results;
     }
-    
+
     /**
      * Create a new JSONException in a common format for incorrect conversions.
      * @param key name of the key
@@ -2581,7 +2659,7 @@ public class JSONObject {
                 "JSONObject[" + quote(key) + "] is not a " + valueType + "."
                 , cause);
     }
-    
+
     /**
      * Create a new JSONException in a common format for incorrect conversions.
      * @param key name of the key

src/main/java/org/json/JSONPointer.java

@@ -187,10 +187,11 @@ public class JSONPointer {
         this.refTokens = new ArrayList<String>(refTokens);
     }
 
+    /**
+     * @see <a href="https://tools.ietf.org/html/rfc6901#section-3">rfc6901 section 3</a>
+     */
     private static String unescape(String token) {
-        return token.replace("~1", "/").replace("~0", "~")
-                .replace("\\\"", "\"")
-                .replace("\\\\", "\\");
+        return token.replace("~1", "/").replace("~0", "~");
     }
 
     /**
@@ -263,16 +264,15 @@ public class JSONPointer {
     /**
      * Escapes path segment values to an unambiguous form.
      * The escape char to be inserted is '~'. The chars to be escaped 
-     * are ~, which maps to ~0, and /, which maps to ~1. Backslashes
-     * and double quote chars are also escaped.
+     * are ~, which maps to ~0, and /, which maps to ~1.
      * @param token the JSONPointer segment value to be escaped
      * @return the escaped value for the token
+     * 
+     * @see <a href="https://tools.ietf.org/html/rfc6901#section-3">rfc6901 section 3</a>
      */
     private static String escape(String token) {
         return token.replace("~", "~0")
-                .replace("/", "~1")
-                .replace("\\", "\\\\")
-                .replace("\"", "\\\"");
+                .replace("/", "~1");
     }
 
     /**

src/main/java/org/json/JSONStringer.java

@@ -50,7 +50,7 @@ import java.io.StringWriter;
  * <p>
  * The first method called must be <code>array</code> or <code>object</code>.
  * There are no methods for adding commas or colons. JSONStringer adds them for
- * you. Objects and arrays can be nested up to 20 levels deep.
+ * you. Objects and arrays can be nested up to 200 levels deep.
  * <p>
  * This can sometimes be easier than using a JSONObject to build a string.
  * @author JSON.org

src/main/java/org/json/XML.java

@@ -532,7 +532,7 @@ public class XML {
             // This will narrow any values to the smallest reasonable Object representation
             // (Integer, Long, or BigInteger)
             
-            // BigInteger down conversion: We use a similar bitLenth compare as
+            // BigInteger down conversion: We use a similar bitLength compare as
             // BigInteger#intValueExact uses. Increases GC, but objects hold
             // only what they need. i.e. Less runtime overhead if the value is
             // long lived.

src/main/java/org/json/XMLParserConfiguration.java

@@ -94,7 +94,7 @@ public class XMLParserConfiguration {
      * Configure the parser string processing to try and convert XML values to JSON values and
      * use the passed CDATA Tag Name the processing value. Pass <code>null</code> to
      * disable CDATA processing
-     * @param cDataTagName<code>null</code> to disable CDATA processing. Any other value
+     * @param cDataTagName <code>null</code> to disable CDATA processing. Any other value
      *      to use that value as the JSONObject key name to process as CDATA.
      * @deprecated This constructor has been deprecated in favor of using the new builder
      *      pattern for the configuration.
@@ -109,7 +109,7 @@ public class XMLParserConfiguration {
      * Configure the parser to use custom settings.
      * @param keepStrings <code>true</code> to parse all values as string.
      *      <code>false</code> to try and convert XML string values into a JSON value.
-     * @param cDataTagName<code>null</code> to disable CDATA processing. Any other value
+     * @param cDataTagName <code>null</code> to disable CDATA processing. Any other value
      *      to use that value as the JSONObject key name to process as CDATA.
      * @deprecated This constructor has been deprecated in favor of using the new builder
      *      pattern for the configuration.
@@ -182,7 +182,7 @@ public class XMLParserConfiguration {
      * When parsing the XML into JSON, specifies if values should be kept as strings (<code>true</code>), or if
      * they should try to be guessed into JSON values (numeric, boolean, string)
      * 
-     * @return The {@link #keepStrings} configuration value.
+     * @return The <code>keepStrings</code> configuration value.
      */
     public boolean isKeepStrings() {
         return this.keepStrings;
@@ -193,7 +193,7 @@ public class XMLParserConfiguration {
      * they should try to be guessed into JSON values (numeric, boolean, string)
      * 
      * @param newVal
-     *      new value to use for the {@link #keepStrings} configuration option.
+     *      new value to use for the <code>keepStrings</code> configuration option.
      * 
      * @return The existing configuration will not be modified. A new configuration is returned.
      */
@@ -208,7 +208,7 @@ public class XMLParserConfiguration {
      * been the value "content" but can be changed. Use <code>null</code> to indicate no CDATA
      * processing.
      * 
-     * @return The {@link #cDataTagName} configuration value.
+     * @return The <code>cDataTagName</code> configuration value.
      */
     public String getcDataTagName() {
         return this.cDataTagName;
@@ -220,7 +220,7 @@ public class XMLParserConfiguration {
      * processing.
      * 
      * @param newVal
-     *      new value to use for the {@link #cDataTagName} configuration option.
+     *      new value to use for the <code>cDataTagName</code> configuration option.
      * 
      * @return The existing configuration will not be modified. A new configuration is returned.
      */
@@ -235,7 +235,7 @@ public class XMLParserConfiguration {
      * should be kept as attribute(<code>false</code>), or they should be converted to
      * <code>null</code>(<code>true</code>)
      * 
-     * @return The {@link #convertNilAttributeToNull} configuration value.
+     * @return The <code>convertNilAttributeToNull</code> configuration value.
      */
     public boolean isConvertNilAttributeToNull() {
         return this.convertNilAttributeToNull;
@@ -247,7 +247,7 @@ public class XMLParserConfiguration {
      * <code>null</code>(<code>true</code>)
      * 
      * @param newVal
-     *      new value to use for the {@link #convertNilAttributeToNull} configuration option.
+     *      new value to use for the <code>convertNilAttributeToNull</code> configuration option.
      * 
      * @return The existing configuration will not be modified. A new configuration is returned.
      */
@@ -262,7 +262,7 @@ public class XMLParserConfiguration {
      * will be converted to target type defined to client in this configuration
      * {@code Map<String, XMLXsiTypeConverter<?>>} to parse values with attribute
      * xsi:type="integer" as integer,  xsi:type="string" as string
-     * @return {@link #xsiTypeMap} unmodifiable configuration map.
+     * @return <code>xsiTypeMap</code> unmodifiable configuration map.
      */
     public Map<String, XMLXsiTypeConverter<?>> getXsiTypeMap() {
         return this.xsiTypeMap;

src/test/java/org/json/junit/EnumTest.java

@@ -93,7 +93,7 @@ public class EnumTest {
 
     /**
      * To serialize an enum by its set of allowed values, use getNames()
-     * and the the JSONObject Object with names constructor. 
+     * and the JSONObject Object with names constructor.
      */
     @Test
     public void jsonObjectFromEnumWithNames() {

src/test/java/org/json/junit/JSONArrayTest.java

@@ -87,6 +87,7 @@ public class JSONArrayTest {
     @Test
     public void verifySimilar() {
         final String string1 = "HasSameRef";
+        final String string2 = "HasDifferentRef";
         JSONArray obj1 = new JSONArray()
                 .put("abc")
                 .put(string1)
@@ -101,10 +102,20 @@ public class JSONArrayTest {
                 .put("abc")
                 .put(new String(string1))
                 .put(2);
+
+        JSONArray obj4 = new JSONArray()
+                .put("abc")
+                .put(2.0)
+        		.put(new String(string1));
+
+        JSONArray obj5 = new JSONArray()
+                .put("abc")
+                .put(2.0)
+        		.put(new String(string2));
         
-        assertFalse("Should eval to false", obj1.similar(obj2));
-        
-        assertTrue("Should eval to true", obj1.similar(obj3));
+        assertFalse("obj1-obj2 Should eval to false", obj1.similar(obj2));
+        assertTrue("obj1-obj3 Should eval to true", obj1.similar(obj3));
+        assertFalse("obj4-obj5 Should eval to false", obj4.similar(obj5));
     }
         
     /**
@@ -364,6 +375,8 @@ public class JSONArrayTest {
                 new Double(23.45e-4).equals(jsonArray.getDouble(5)));
         assertTrue("Array string double",
                 new Double(23.45).equals(jsonArray.getDouble(6)));
+        assertTrue("Array double can be float",
+                new Float(23.45e-4f).equals(jsonArray.getFloat(5)));
         // ints
         assertTrue("Array value int",
                 new Integer(42).equals(jsonArray.getInt(7)));
@@ -1254,4 +1267,19 @@ public class JSONArrayTest {
             assertEquals("index " + i + " are equal", a1.get(i), a2.get(i));
         }
     }
+
+    /**
+	 * Tests if calling JSONArray clear() method actually makes the JSONArray empty
+	 */
+	@Test(expected = JSONException.class)
+	public void jsonArrayClearMethodTest() {
+		//Adds random stuff to the JSONArray
+		JSONArray jsonArray = new JSONArray();
+		jsonArray.put(123);
+		jsonArray.put("456");
+		jsonArray.put(new JSONArray());
+		jsonArray.clear(); //Clears the JSONArray
+		assertTrue("expected jsonArray.length() == 0", jsonArray.length() == 0); //Check if its length is 0
+		jsonArray.getInt(0); //Should throws org.json.JSONException: JSONArray[0] not found
+	}
 }

src/test/java/org/json/junit/JSONObjectTest.java

@@ -100,6 +100,7 @@ public class JSONObjectTest {
     @Test
     public void verifySimilar() {
         final String string1 = "HasSameRef";
+        final String string2 = "HasDifferentRef";
         JSONObject obj1 = new JSONObject()
                 .put("key1", "abc")
                 .put("key2", 2)
@@ -115,10 +116,27 @@ public class JSONObjectTest {
                 .put("key2", 2)
                 .put("key3", new String(string1));
         
-        assertFalse("Should eval to false", obj1.similar(obj2));
-        
-        assertTrue("Should eval to true", obj1.similar(obj3));
+        JSONObject obj4 = new JSONObject()
+                .put("key1", "abc")
+                .put("key2", 2.0)
+                .put("key3", new String(string1));
+
+        JSONObject obj5 = new JSONObject()
+                .put("key1", "abc")
+                .put("key2", 2.0)
+                .put("key3", new String(string2));
         
+        assertFalse("obj1-obj2 Should eval to false", obj1.similar(obj2));
+        assertTrue("obj1-obj3 Should eval to true", obj1.similar(obj3));
+        assertTrue("obj1-obj4 Should eval to true", obj1.similar(obj4));
+        assertFalse("obj1-obj5 Should eval to false", obj1.similar(obj5));
+        // verify that a double and big decimal are "similar"
+        assertTrue("should eval to true",new JSONObject().put("a",1.1d).similar(new JSONObject("{\"a\":1.1}")));
+        // Confirm #618 is fixed (compare should not exit early if similar numbers are found)
+        // Note that this test may not work if the JSONObject map entry order changes
+        JSONObject first = new JSONObject("{\"a\": 1, \"b\": 2, \"c\": 3}");
+        JSONObject second = new JSONObject("{\"a\": 1, \"b\": 2.0, \"c\": 4}");
+        assertFalse("first-second should eval to false", first.similar(second));
     }
     
     @Test
@@ -933,7 +951,7 @@ public class JSONObjectTest {
         assertTrue("-0 Should be a Double!",JSONObject.stringToValue("-0")  instanceof Double);
         assertTrue("-0.0 Should be a Double!",JSONObject.stringToValue("-0.0") instanceof Double);
         assertTrue("'-' Should be a String!",JSONObject.stringToValue("-") instanceof String);
-        assertTrue( "0.2 should be a Double!",
+        assertTrue( "0.2 should be a BigDecimal!",
                 JSONObject.stringToValue( "0.2" ) instanceof BigDecimal );
         assertTrue( "Doubles should be BigDecimal, even when incorrectly converting floats!",
                 JSONObject.stringToValue( new Double( "0.2f" ).toString() ) instanceof BigDecimal );
@@ -1660,7 +1678,7 @@ public class JSONObjectTest {
         // correct implementation (with change of behavior) would be:
         // this.put(key, new Float((Float) value + 1)); 
         // Probably it would be better to deprecate the method and remove some day, while convenient processing the "payload" is not
-        // really in the the scope of a JSON-library (IMHO.)
+        // really in the scope of a JSON-library (IMHO.)
 
     }
 
@@ -2397,8 +2415,8 @@ public class JSONObjectTest {
                 MyEnum.VAL1.equals(jsonObject.optEnum(MyEnum.class, "myKey", MyEnum.VAL1)));
         assertTrue("optJSONArray() should return null ",
                 null==jsonObject.optJSONArray("myKey"));
-        assertTrue("optJSONObject() should return null ",
-                null==jsonObject.optJSONObject("myKey"));
+        assertTrue("optJSONObject() should return default JSONObject ",
+                jsonObject.optJSONObject("myKey", new JSONObject("{\"testKey\":\"testValue\"}")).getString("testKey").equals("testValue"));
         assertTrue("optLong() should return default long",
                 42l == jsonObject.optLong("myKey", 42l));
         assertTrue("optDouble() should return default double",
@@ -2433,8 +2451,8 @@ public class JSONObjectTest {
                  MyEnum.VAL1.equals(jsonObject.optEnum(MyEnum.class, "myKey", MyEnum.VAL1)));
          assertTrue("optJSONArray() should return null ",
                  null==jsonObject.optJSONArray("myKey"));
-         assertTrue("optJSONObject() should return null ",
-                 null==jsonObject.optJSONObject("myKey"));
+         assertTrue("optJSONObject() should return default JSONObject ",
+                jsonObject.optJSONObject("myKey", new JSONObject("{\"testKey\":\"testValue\"}")).getString("testKey").equals("testValue"));
          assertTrue("optLong() should return default long",
                  42l == jsonObject.optLong("myKey", 42l));
          assertTrue("optDouble() should return default double",
@@ -3208,4 +3226,19 @@ public class JSONObjectTest {
         assertNotNull("'empty_json_array' should be an array", jsonObject.getJSONArray("empty_json_array"));
         assertEquals("'empty_json_array' should have a length of 0", 0, jsonObject.getJSONArray("empty_json_array").length());
     }
+
+    /**
+    * Tests if calling JSONObject clear() method actually makes the JSONObject empty
+    */
+    @Test(expected = JSONException.class)
+    public void jsonObjectClearMethodTest() {
+        //Adds random stuff to the JSONObject
+        JSONObject jsonObject = new JSONObject();
+        jsonObject.put("key1", 123);
+        jsonObject.put("key2", "456");
+        jsonObject.put("key3", new JSONObject());
+        jsonObject.clear(); //Clears the JSONObject
+        assertTrue("expected jsonObject.length() == 0", jsonObject.length() == 0); //Check if its length is 0
+        jsonObject.getInt("key1"); //Should throws org.json.JSONException: JSONObject["asd"] not found
+    }
 }

src/test/java/org/json/junit/JSONPointerTest.java

@@ -117,14 +117,24 @@ public class JSONPointerTest {
         assertSame(document.get("m~n"), query("/m~0n"));
     }
 
+    /**
+     * We pass backslashes as-is
+     * 
+     * @see <a href="https://tools.ietf.org/html/rfc6901#section-3">rfc6901 section 3</a>
+     */
     @Test
-    public void backslashEscaping() {
-        assertSame(document.get("i\\j"), query("/i\\\\j"));
+    public void backslashHandling() {
+        assertSame(document.get("i\\j"), query("/i\\j"));
     }
 
+    /**
+     * We pass quotations as-is
+     * 
+     * @see <a href="https://tools.ietf.org/html/rfc6901#section-3">rfc6901 section 3</a>
+     */
     @Test
-    public void quotationEscaping() {
-        assertSame(document.get("k\"l"), query("/k\\\\\\\"l"));
+    public void quotationHandling() {
+        assertSame(document.get("k\"l"), query("/k\"l"));
     }
 
     @Test
@@ -189,7 +199,7 @@ public class JSONPointerTest {
                 .append("\"")
                 .append(0)
                 .build();
-        assertEquals("/obj/other~0key/another~1key/\\\"/0", pointer.toString());
+        assertEquals("/obj/other~0key/another~1key/\"/0", pointer.toString());
     }
     
     @Test

src/test/java/org/json/junit/XMLTest.java

@@ -65,6 +65,7 @@ public class XMLTest {
     @Rule
     public TemporaryFolder testFolder = new TemporaryFolder();
 
+    
     /**
      * JSONObject from a null XML string.
      * Expects a NullPointerException

src/test/java/org/json/junit/data/ExceptionalBean.java

@@ -8,7 +8,7 @@ import java.io.IOException;
 import java.lang.reflect.InvocationTargetException;
 
 /**
- * Object for testing the exception handling in {@link JSONObject#populateMap}.
+ * Object for testing the exception handling in {@link org.json.JSONObject#populateMap}.
  * 
  * @author John Aylward
  */