twitter4j

## Class JSONTokener

- java.lang.Object
- - twitter4j.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.

### Constructor Summary

Constructors
Constructor and Description
`JSONTokener(InputStream is)`
`JSONTokener(Reader input)`
`JSONTokener(String in)`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`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(char excluded)` Equivalent to `nextTo(String.valueOf(excluded))`.
`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'
`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.

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Constructor Detail

#### JSONTokener

    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.

#### JSONTokener

    public JSONTokener(Reader input)

#### JSONTokener

    public JSONTokener(InputStream is)

### Method Detail

#### nextValue

    public Object nextValue()
                     throws JSONException

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.

#### nextString

    public String nextString(char quote)
                      throws JSONException

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 ".
Returns:
  The unescaped string.
Throws:
  `JSONException` - if the string isn't terminated by a closing quote correctly.

#### syntaxError

    public JSONException syntaxError(String message)

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

Parameters:
  `message` - The message we want to include.
Returns:
  An exception that we can throw.

#### toString

    public String toString()

Returns the current position and the entire input string.

Overrides:
  `toString` in class `Object`

#### more

    public boolean more()

Returns true until the input has been exhausted.

Returns:
  true if more input exists.

#### next

    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'.

Returns:
  the next character.

#### next

    public char next(char c)
              throws JSONException

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

Parameters:
  `c` - The character we are looking for.
Returns:
  the next character.
Throws:
  `JSONException` - If the next character isn't `c`

#### nextClean

    public char nextClean()
                   throws JSONException

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'.

Returns:
  The next non-whitespace character.
Throws:
  `JSONException` - Should not be possible.

#### next

    public String next(int length)
                throws JSONException

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` - The desired number of characters to return.
Returns:
  The next few characters.
Throws:
  `JSONException` - if the remaining input is not long enough to satisfy this request.

#### nextTo

    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'

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:
  `excluded` - The limiting string where the search should stop.
Returns:
  a possibly-empty string

#### nextTo

    public String nextTo(char excluded)

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

Parameters:
  `excluded` - The limiting character.
Returns:
  a possibly-empty string

#### skipPast

    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` - The string to skip over.

#### skipTo

    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` - The character we want to skip to.
Returns:
  The value of `to` or null.

#### back

    public void back()

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

#### dehexchar

    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.
Returns:
  The decoded integer.