title: JSONObject's put method confusion
body: <p>I read the menu of the put method of JSONObject's Map field.</p>
  <p>Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for the key, the old value is replaced by the specified value. (A map m is said to contain a mapping for a key k if and only if m.containsKey(k) would return true.)
  Params:
  key – key with which the specified value is to be associated
  value – value to be associated with the specified key
  Returns:
  <strong>the previous value associated with key</strong>, or null if there was no mapping for key. (A null return can also indicate that the map previously associated null with key, if the implementation supports null values.)</p>
  <p>I am just wondering what does the put method exactly do when it is called with a JSONObject?, I know that it acts on the particular JSONObject's MAP field right?</p>
  <p>Because when I looked at the definition of this method, it is this:</p>
  <pre><code>public JSONObject put(String key, Object value) throws JSONException {
      if (key == null) {
          throw new NullPointerException(&quot;Null key.&quot;);
      } else {
          if (value != null) {
              testValidity(value);
              this.map.put(key, value);  ///// so it is the Map field that use the put method
          } else {
              this.remove(key);
          }
  
          return this;
      }
  }
  </code></pre>
  <p>but it says up there that if we do the following:</p>
  <p>this.map(key, value)</p>
  <p>then it will return the previous associated with key?</p>
  <p>why is it returning something?  I thought the function put should actually put a pair of (key, value) into a JSONObject's MAP field?</p>
  <p>Also another question is if the key is not null, but value is null, does it mean in that case the key actually got removed from the map? because in the line right below the this.map.out(key, value) block of code, it says this.remove(key) if value is null.</p>
  <p>So does it mean if we do: abc.put(&quot;key12&quot;, NULL) where abc is assumed to be an JSONObject, then the key key12 will now get removed from the this abc JSONObject's MAP?</p>