JSONTokener

public class JSONTokener extends Object

Parses a JSON (RFC 4627) encoded string into the corresponding object. Most clients of this class will use only need the constructor and nextValue() method. Example usage:

 String json = "{"
         + "  \"query\": \"Pizza\", "
         + "  \"locations\": [ 94043, 90210 ] "
         + "}";

 JSONObject object = (JSONObject) new JSONTokener(json).nextValue();
 String query = object.getString("query");
 JSONArray locations = object.getJSONArray("locations");

For best interoperability and performance use JSON that complies with RFC 4627, such as that generated by JSONStringer. For legacy reasons this parser is lenient, so a successful parse does not indicate that the input string was valid JSON. All of the following syntax errors will be ignored:

End of line comments starting with // or # and ending with a newline character.
C-style comments starting with /* and ending with */. Such comments may not be nested.
Strings that are unquoted or 'single quoted'.
Hexadecimal integers prefixed with 0x or 0X.
Octal integers prefixed with 0.
Array elements separated by ;.
Unnecessary array separators. These are interpreted as if null was the omitted value.
Key-value pairs separated by = or =>.
Key-value pairs separated by ;.

Each tokener may be used to parse a single JSON string. Instances of this class are not thread safe. Although this class is nonfinal, it was not designed for inheritance and should not be subclassed. In particular, self-use by overrideable methods is not specified. See Effective Java Item 17, "Design and Document or inheritance or else prohibit it" for further information.

Public Constructor Summary

JSONTokener(String in)

Public Method Summary

void	back() Unreads the most recent character of input.
static int	dehexchar(char hex) Returns the integer [0..15] value for the given hex character, or -1 for non-hex input.
boolean	more() Returns true until the input has been exhausted.
char	next() Returns the next available character, or the null character '\0' if all input has been exhausted.
char	next(char c) Returns the next available character if it equals `c`.
String	next(int length) Returns the next `length` characters of the input.
char	nextClean() Returns the next character that is not whitespace and does not belong to a comment.
String	nextString(char quote) Returns the string up to but not including `quote`, unescaping any character escape sequences encountered along the way.
String	nextTo(String excluded) Returns the `trimmed` string holding the characters up to but not including the first of: any character in `excluded` a newline character '\n' a carriage return '\r' The returned string shares its backing character array with this tokener's input string.
String	nextTo(char excluded) Equivalent to `nextTo(String.valueOf(excluded))`.
Object	nextValue() Returns the next value from the input.
void	skipPast(String thru) Advances past all input up to and including the next occurrence of `thru`.
char	skipTo(char to) Advances past all input up to but not including the next occurrence of `to`.
JSONException	syntaxError(String message) Returns an exception containing the given message plus the current position and the entire input string.
String	toString() Returns the current position and the entire input string.

Inherited Method Summary

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

Public Constructors

public JSONTokener (String in)

Parameters

in	JSON encoded string. Null is not permitted and will yield a tokener that throws `NullPointerExceptions` when methods are called.

Public Methods

public void back ()

Unreads the most recent character of input. If no input characters have been read, the input is unchanged.

public static int dehexchar (char hex)

Returns the integer [0..15] value for the given hex character, or -1 for non-hex input.

Parameters

hex	a character in the ranges [0-9], [A-F] or [a-f]. Any other character will yield a -1 result.

public boolean more ()

Returns true until the input has been exhausted.

public char next ()

Returns the next available character, or the null character '\0' if all input has been exhausted. The return value of this method is ambiguous for JSON strings that contain the character '\0'.

public char next (char c)

Returns the next available character if it equals c. Otherwise an exception is thrown.

Parameters

c

Throws

JSONException

public String next (int length)

Returns the next length characters of the input.

The returned string shares its backing character array with this tokener's input string. If a reference to the returned string may be held indefinitely, you should use new String(result) to copy it first to avoid memory leaks.

Parameters

length

Throws

JSONException	if the remaining input is not long enough to satisfy this request.

public char nextClean ()

Returns the next character that is not whitespace and does not belong to a comment. If the input is exhausted before such a character can be found, the null character '\0' is returned. The return value of this method is ambiguous for JSON strings that contain the character '\0'.

Throws

JSONException

public String nextString (char quote)

Returns the string up to but not including quote, unescaping any character escape sequences encountered along the way. The opening quote should have already been read. This consumes the closing quote, but does not include it in the returned string.

Parameters

quote	either ' or ".

Throws

JSONException

public String nextTo (String excluded)

Returns the trimmed string holding the characters up to but not including the first of:

any character in excluded
a newline character '\n'
a carriage return '\r'

Parameters

excluded

Returns

a possibly-empty string

public String nextTo (char excluded)

Equivalent to nextTo(String.valueOf(excluded)).

Parameters

excluded

public Object nextValue ()

Returns the next value from the input.

Returns

a JSONObject, JSONArray, String, Boolean, Integer, Long, Double or JSONObject.NULL.

Throws

JSONException	if the input is malformed.

public void skipPast (String thru)

Advances past all input up to and including the next occurrence of thru. If the remaining input doesn't contain thru, the input is exhausted.

Parameters

thru

public char skipTo (char to)

Advances past all input up to but not including the next occurrence of to. If the remaining input doesn't contain to, the input is unchanged.

Parameters

to

public JSONException syntaxError (String message)

Returns an exception containing the given message plus the current position and the entire input string.

Parameters

message

public String toString ()

Returns the current position and the entire input string.