A JSONObject is an unordered collection of name/value pairs. Its external form is a string wrapped in curly braces with colons between the names and values, and commas between the values and names. The internal form is an object having {@code}get{/code} and {@code}opt{/code} methods for accessing the values by name, and {@code}put{/code} methods for adding or replacing values by name. The values can be any of these types: {@code}Boolean{/code}, {@code}JSONArray{/code}, {@code}JSONObject{/code}, {@code}Number{/code}, {@code}String{/code}, or the {@code}JSONObject.NULL{/code} object. A JSONObject constructor can be used to convert an external form JSON text into an internal form whose values can be retrieved with the {@code}get{/code} and {@code}opt{/code} methods, or to convert values into a JSON text using the {@code}put{/code} and {@code}toString{/code} methods. A {@code}get{/code} method returns a value if one can be found, and throws an exception if one cannot be found. An {@code}opt{/code} method returns a default value instead of throwing an exception, and so is useful for obtaining optional values.
The generic {@code}get(){/code} and {@code}opt(){/code} methods return an object, which you can cast or query for type. There are also typed {@code}get{/code} and {@code}opt{/code} methods that do type checking and type coercion for you. The opt methods differ from the get methods in that they do not throw. Instead, they return a specified value, such as null.
The {@code}put{/code} methods add or replace values in an object. For example,
myString = new JSONObject().put("JSON", "Hello, World!").toString();
produces the string {@code}{"JSON": "Hello, World"}{/code}.
The texts produced by the {@code}toString{/code} methods strictly conform to the JSON syntax rules. The constructors are more forgiving in the texts they will accept:
- An extra {@code},{/code} (comma) may appear just before the closing brace.
- Strings may be quoted with {@code}'{/code} (single quote).
- Strings do not need to be quoted at all if they do not begin with a quote or single quote, and if they do not contain leading or trailing spaces, and if they do not contain any of these characters: {@code}{ } [ ] / \ : , = ; #{/code} and if they do not look like numbers and if they are not the reserved words {@code}true{/code}, {@code}false{/code}, or {@code}null{/code}.
- Keys can be followed by {@code}={/code} or {@code}=>{/code} as well as by {@code}:{/code}.
- Values can be followed by {@code};{/code} (semicolon) as well as by {@code},{/code} (comma).
- Numbers may have the {@code}0x-{/code} (hex) prefix.
@author JSON.org
@version 2010-12-28