get and
* opt methods for accessing the values by index, and
* put methods for adding or replacing values. The values can be
* any of these types:
* Boolean,
* JSONArray,
* JSONObject,
* Number,
* String, or the
* JSONObject.NULL object.
*
* The constructor can convert a JSON text into a Java object. The
* toString method converts to JSON text.
*
* A
* get method returns a value if one can be found, and throws an
* exception if one cannot be found. An
* opt method returns a default value instead of throwing an
* exception, and so is useful for obtaining optional values.
*
* The generic
* get() and
* opt() methods return an object which you can cast or query for
* type. There are also typed
* get and
* opt methods that do type checking and type coercion for you.
*
* The texts produced by the
* toString methods strictly conform to JSON syntax rules. The
* constructors are more forgiving in the texts they will accept:
*
, (comma) may appear just before the closing
* bracket.null value will be inserted when there is
* , (comma) elision.' (single quote).{ } [ ] / \ : , # and if they do not look like numbers and if
* they are not the reserved words
* true,
* false, or
* null.[ (left
* bracket) and ends with ] (right
* bracket).
* @throws JSONException If there is a syntax error.
*/
public JSONArray( String source ) throws JSONException
{
this( new JSONTokener( source ) );
}
/**
* Construct a JSONArray from a Collection.
*
* @param collection A Collection.
*/
public JSONArray( Collection collection )
{
this.myArrayList = new ArrayList();
if ( collection != null )
{
Iterator iter = collection.iterator();
while ( iter.hasNext() )
{
this.myArrayList.add( JSONObject.wrap( iter.next() ) );
}
}
}
/**
* Construct a JSONArray from an array
*
* @param array
* @throws JSONException If not an array.
*/
public JSONArray( Object array ) throws JSONException
{
this();
if ( array.getClass().isArray() )
{
int length = Array.getLength( array );
for ( int i = 0 ; i < length ; i += 1 )
{
this.put( JSONObject.wrap( Array.get( array, i ) ) );
}
} else
{
throw new JSONException(
"JSONArray initial value should be a string or collection or array." );
}
}
/**
* Get the object value associated with an index.
*
* @param index The index must be between 0 and length() - 1.
* @return An object value.
* @throws JSONException If there is no value for the index.
*/
public Object get( int index ) throws JSONException
{
Object object = this.opt( index );
if ( object == null )
{
throw new JSONException( "JSONArray[" + index + "] not found." );
}
return object;
}
/**
* Get the boolean value associated with an index. The string values "true"
* and "false" are converted to boolean.
*
* @param index The index must be between 0 and length() - 1.
* @return The truth.
* @throws JSONException If there is no value for the index or if the value
* is not convertible to boolean.
*/
public boolean getBoolean( int index ) throws JSONException
{
Object object = this.get( index );
if ( object.equals( Boolean.FALSE )
|| ( object instanceof String && ( (String) object )
.equalsIgnoreCase( "false" ) ) )
{
return false;
} else if ( object.equals( Boolean.TRUE )
|| ( object instanceof String && ( (String) object )
.equalsIgnoreCase( "true" ) ) )
{
return true;
}
throw new JSONException( "JSONArray[" + index + "] is not a boolean." );
}
/**
* Get the double value associated with an index.
*
* @param index The index must be between 0 and length() - 1.
* @return The value.
* @throws JSONException If the key is not found or if the value cannot be
* converted to a number.
*/
public double getDouble( int index ) throws JSONException
{
Object object = this.get( index );
try
{
return object instanceof Number ? ( (Number) object ).doubleValue()
: Double.parseDouble( (String) object );
} catch ( Exception e )
{
throw new JSONException( "JSONArray[" + index + "] is not a number." );
}
}
/**
* Get the int value associated with an index.
*
* @param index The index must be between 0 and length() - 1.
* @return The value.
* @throws JSONException If the key is not found or if the value is not a
* number.
*/
public int getInt( int index ) throws JSONException
{
Object object = this.get( index );
try
{
return object instanceof Number ? ( (Number) object ).intValue()
: Integer.parseInt( (String) object );
} catch ( Exception e )
{
throw new JSONException( "JSONArray[" + index + "] is not a number." );
}
}
/**
* Get the JSONArray associated with an index.
*
* @param index The index must be between 0 and length() - 1.
* @return A JSONArray value.
* @throws JSONException If there is no value for the index. or if the value
* is not a JSONArray
*/
public JSONArray getJSONArray( int index ) throws JSONException
{
Object object = this.get( index );
if ( object instanceof JSONArray )
{
return (JSONArray) object;
}
throw new JSONException( "JSONArray[" + index + "] is not a JSONArray." );
}
/**
* Get the JSONObject associated with an index.
*
* @param index subscript
* @return A JSONObject value.
* @throws JSONException If there is no value for the index or if the value
* is not a JSONObject
*/
public JSONObject getJSONObject( int index ) throws JSONException
{
Object object = this.get( index );
if ( object instanceof JSONObject )
{
return (JSONObject) object;
}
throw new JSONException( "JSONArray[" + index + "] is not a JSONObject." );
}
/**
* Get the long value associated with an index.
*
* @param index The index must be between 0 and length() - 1.
* @return The value.
* @throws JSONException If the key is not found or if the value cannot be
* converted to a number.
*/
public long getLong( int index ) throws JSONException
{
Object object = this.get( index );
try
{
return object instanceof Number ? ( (Number) object ).longValue()
: Long.parseLong( (String) object );
} catch ( Exception e )
{
throw new JSONException( "JSONArray[" + index + "] is not a number." );
}
}
/**
* Get the string associated with an index.
*
* @param index The index must be between 0 and length() - 1.
* @return A string value.
* @throws JSONException If there is no string value for the index.
*/
public String getString( int index ) throws JSONException
{
Object object = this.get( index );
if ( object instanceof String )
{
return (String) object;
}
throw new JSONException( "JSONArray[" + index + "] not a string." );
}
/**
* Determine if the value is null.
*
* @param index The index must be between 0 and length() - 1.
* @return true if the value at the index is null, or if there is no value.
*/
public boolean isNull( int index )
{
return JSONObject.NULL.equals( this.opt( index ) );
}
/**
* Make a string from the contents of this JSONArray. The
* separator string is inserted between each element. Warning:
* This method assumes that the data structure is acyclical.
*
* @param separator A string that will be inserted between the elements.
* @return a string.
* @throws JSONException If the array contains an invalid number.
*/
public String join( String separator ) throws JSONException
{
int len = this.length();
StringBuilder sb = new StringBuilder();
for ( int i = 0 ; i < len ; i += 1 )
{
if ( i > 0 )
{
sb.append( separator );
}
sb.append( JSONObject.valueToString( this.myArrayList.get( i ) ) );
}
return sb.toString();
}
/**
* Get the number of elements in the JSONArray, included nulls.
*
* @return The length (or size).
*/
public int length()
{
return this.myArrayList.size();
}
/**
* Get the optional object value associated with an index.
*
* @param index The index must be between 0 and length() - 1.
* @return An object value, or null if there is no object at that index.
*/
public Object opt( int index )
{
return ( index < 0 || index >= this.length() ) ? null : this.myArrayList
.get( index );
}
/**
* Get the optional boolean value associated with an index. It returns false
* if there is no value at that index, or if the value is not Boolean.TRUE
* or the String "true".
*
* @param index The index must be between 0 and length() - 1.
* @return The truth.
*/
public boolean optBoolean( int index )
{
return this.optBoolean( index, false );
}
/**
* Get the optional boolean value associated with an index. It returns the
* defaultValue if there is no value at that index or if it is not a Boolean
* or the String "true" or "false" (case insensitive).
*
* @param index The index must be between 0 and length() - 1.
* @param defaultValue A boolean default.
* @return The truth.
*/
public boolean optBoolean( int index, boolean defaultValue )
{
try
{
return this.getBoolean( index );
} catch ( Exception e )
{
return defaultValue;
}
}
/**
* Get the optional double value associated with an index. NaN 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.
*
* @param index The index must be between 0 and length() - 1.
* @return The value.
*/
public double optDouble( int index )
{
return this.optDouble( index, Double.NaN );
}
/**
* Get the optional double 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.
*
* @param index subscript
* @param defaultValue The default value.
* @return The value.
*/
public double optDouble( int index, double defaultValue )
{
try
{
return this.getDouble( index );
} catch ( Exception e )
{
return defaultValue;
}
}
/**
* Get the optional int value associated with an index. Zero 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.
*
* @param index The index must be between 0 and length() - 1.
* @return The value.
*/
public int optInt( int index )
{
return this.optInt( index, 0 );
}
/**
* Get the optional int 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.
*
* @param index The index must be between 0 and length() - 1.
* @param defaultValue The default value.
* @return The value.
*/
public int optInt( int index, int defaultValue )
{
try
{
return this.getInt( index );
} catch ( Exception e )
{
return defaultValue;
}
}
/**
* Get the optional JSONArray associated with an index.
*
* @param index subscript
* @return A JSONArray value, or null if the index has no value, or if the
* value is not a JSONArray.
*/
public JSONArray optJSONArray( int index )
{
Object o = this.opt( index );
return o instanceof JSONArray ? (JSONArray) o : null;
}
/**
* Get the optional JSONObject associated with an index. Null is returned if
* the key is not found, or null if the index has no value, or if the value
* is not a JSONObject.
*
* @param index The index must be between 0 and length() - 1.
* @return A JSONObject value.
*/
public JSONObject optJSONObject( int index )
{
Object o = this.opt( index );
return o instanceof JSONObject ? (JSONObject) o : null;
}
/**
* Get the optional long value associated with an index. Zero 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.
*
* @param index The index must be between 0 and length() - 1.
* @return The value.
*/
public long optLong( int index )
{
return this.optLong( index, 0 );
}
/**
* Get the optional long 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.
*
* @param index The index must be between 0 and length() - 1.
* @param defaultValue The default value.
* @return The value.
*/
public long optLong( int index, long defaultValue )
{
try
{
return this.getLong( index );
} catch ( Exception e )
{
return defaultValue;
}
}
/**
* Get the optional string value associated with an index. It returns an
* empty string if there is no value at that index. If the value is not a
* string and is not null, then it is coverted to a string.
*
* @param index The index must be between 0 and length() - 1.
* @return A String value.
*/
public String optString( int index )
{
return this.optString( index, "" );
}
/**
* Get the optional string associated with an index. The defaultValue is
* returned if the key is not found.
*
* @param index The index must be between 0 and length() - 1.
* @param defaultValue The default value.
* @return A String value.
*/
public String optString( int index, String defaultValue )
{
Object object = this.opt( index );
return JSONObject.NULL.equals( object ) ? defaultValue : object
.toString();
}
/**
* Append a boolean value. This increases the array's length by one.
*
* @param value A boolean value.
* @return this.
*/
public JSONArray put( boolean value )
{
this.put( value ? Boolean.TRUE : Boolean.FALSE );
return this;
}
/**
* Put a value in the JSONArray, where the value will be a JSONArray which
* is produced from a Collection.
*
* @param value A Collection value.
* @return this.
*/
public JSONArray put( Collection value )
{
this.put( new JSONArray( value ) );
return this;
}
/**
* Append a double value. This increases the array's length by one.
*
* @param value A double value.
* @throws JSONException if the value is not finite.
* @return this.
*/
public JSONArray put( double value ) throws JSONException
{
Double d = new Double( value );
JSONObject.testValidity( d );
this.put( d );
return this;
}
/**
* Append an int value. This increases the array's length by one.
*
* @param value An int value.
* @return this.
*/
public JSONArray put( int value )
{
this.put( new Integer( value ) );
return this;
}
/**
* Append an long value. This increases the array's length by one.
*
* @param value A long value.
* @return this.
*/
public JSONArray put( long value )
{
this.put( new Long( value ) );
return this;
}
/**
* Put a value in the JSONArray, where the value will be a JSONObject which
* is produced from a Map.
*
* @param value A Map value.
* @return this.
*/
public JSONArray put( Map value )
{
this.put( new JSONObject( value ) );
return this;
}
/**
* Append an object value. This increases the array's length by one.
*
* @param value An object value. The value should be a Boolean, Double,
* Integer, JSONArray, JSONObject, Long, or String, or the JSONObject.NULL
* object.
* @return this.
*/
public JSONArray put( Object value )
{
this.myArrayList.add( value );
return this;
}
/**
* Put or replace a boolean value in the JSONArray. If the index is greater
* than the length of the JSONArray, then null elements will be added as
* necessary to pad it out.
*
* @param index The subscript.
* @param value A boolean value.
* @return this.
* @throws JSONException If the index is negative.
*/
public JSONArray put( int index, boolean value ) throws JSONException
{
this.put( index, value ? Boolean.TRUE : Boolean.FALSE );
return this;
}
/**
* Put a value in the JSONArray, where the value will be a JSONArray which
* is produced from a Collection.
*
* @param index The subscript.
* @param value A Collection value.
* @return this.
* @throws JSONException If the index is negative or if the value is not
* finite.
*/
public JSONArray put( int index, Collection value ) throws JSONException
{
this.put( index, new JSONArray( value ) );
return this;
}
/**
* Put or replace a double value. If the index is greater than the length of
* the JSONArray, then null elements will be added as necessary to pad it
* out.
*
* @param index The subscript.
* @param value A double value.
* @return this.
* @throws JSONException If the index is negative or if the value is not
* finite.
*/
public JSONArray put( int index, double value ) throws JSONException
{
this.put( index, new Double( value ) );
return this;
}
/**
* Put or replace an int value. If the index is greater than the length of
* the JSONArray, then null elements will be added as necessary to pad it
* out.
*
* @param index The subscript.
* @param value An int value.
* @return this.
* @throws JSONException If the index is negative.
*/
public JSONArray put( int index, int value ) throws JSONException
{
this.put( index, new Integer( value ) );
return this;
}
/**
* Put or replace a long value. If the index is greater than the length of
* the JSONArray, then null elements will be added as necessary to pad it
* out.
*
* @param index The subscript.
* @param value A long value.
* @return this.
* @throws JSONException If the index is negative.
*/
public JSONArray put( int index, long value ) throws JSONException
{
this.put( index, new Long( value ) );
return this;
}
/**
* Put a value in the JSONArray, where the value will be a JSONObject that
* is produced from a Map.
*
* @param index The subscript.
* @param value The Map value.
* @return this.
* @throws JSONException If the index is negative or if the the value is an
* invalid number.
*/
public JSONArray put( int index, Map value ) throws JSONException
{
this.put( index, new JSONObject( value ) );
return this;
}
/**
* Put or replace an object value in the JSONArray. If the index is greater
* than the length of the JSONArray, then null elements will be added as
* necessary to pad it out.
*
* @param index The subscript.
* @param value The value to put into the array. The value should be a
* Boolean, Double, Integer, JSONArray, JSONObject, Long, or String, or the
* JSONObject.NULL object.
* @return this.
* @throws JSONException If the index is negative or if the the value is an
* invalid number.
*/
public JSONArray put( int index, Object value ) throws JSONException
{
JSONObject.testValidity( value );
if ( index < 0 )
{
throw new JSONException( "JSONArray[" + index + "] not found." );
}
if ( index < this.length() )
{
this.myArrayList.set( index, value );
} else
{
while ( index != this.length() )
{
this.put( JSONObject.NULL );
}
this.put( value );
}
return this;
}
/**
* Remove an index and close the hole.
*
* @param index The index of the element to be removed.
* @return The value that was associated with the index, or null if there
* was no value.
*/
public Object remove( int index )
{
Object o = this.opt( index );
this.myArrayList.remove( index );
return o;
}
/**
* Produce a JSONObject by combining a JSONArray of names with the values of
* this JSONArray.
*
* @param names A JSONArray containing a list of key strings. These will be
* paired with the values.
* @return A JSONObject, or null if there are no names or if this JSONArray
* has no values.
* @throws JSONException If any of the names are null.
*/
public JSONObject toJSONObject( JSONArray names ) throws JSONException
{
if ( names == null || names.length() == 0 || this.length() == 0 )
{
return null;
}
JSONObject jo = new JSONObject();
for ( int i = 0 ; i < names.length() ; i += 1 )
{
jo.put( names.getString( i ), this.opt( i ) );
}
return jo;
}
/**
* Make a JSON text of this JSONArray. For compactness, no unnecessary
* whitespace is added. If it is not possible to produce a syntactically
* correct JSON text then null will be returned instead. This could occur if
* the array contains an invalid number.
*
* Warning: This method assumes that the data structure is acyclical.
*
* @return a printable, displayable, transmittable representation of the
* array.
*/
@Override
public String toString()
{
try
{
return this.toString( 0 );
} catch ( Exception e )
{
return null;
}
}
/**
* Make a prettyprinted JSON text of this JSONArray. Warning: This method
* assumes that the data structure is acyclical.
*
* @param indentFactor The number of spaces to add to each level of
* indentation.
* @return a printable, displayable, transmittable representation of the
* object, beginning with [ (left bracket)
* and ending with ] (right bracket).
* @throws JSONException
*/
public String toString( int indentFactor ) throws JSONException
{
StringWriter sw = new StringWriter();
synchronized ( sw.getBuffer() )
{
return this.write( sw, indentFactor, 0 ).toString();
}
}
/**
* Write the contents of the JSONArray as JSON text to a writer. For
* compactness, no whitespace is added.
*
* Warning: This method assumes that the data structure is acyclical. * * @param writer * @return The writer. * @throws JSONException */ public Writer write( Writer writer ) throws JSONException { return this.write( writer, 0, 0 ); } /** * Write the contents of the JSONArray as JSON text to a writer. For * compactness, no whitespace is added. *
* Warning: This method assumes that the data structure is acyclical. * * @param indentFactor The number of spaces to add to each level of * indentation. * @param indent The indention of the top level. * @return The writer. * @throws JSONException */ Writer write( Writer writer, int indentFactor, int indent ) throws JSONException { try { boolean commanate = false; int length = this.length(); writer.write( '[' ); if ( length == 1 ) { JSONObject.writeValue( writer, this.myArrayList.get( 0 ), indentFactor, indent ); } else if ( length != 0 ) { final int newindent = indent + indentFactor; for ( int i = 0 ; i < length ; i += 1 ) { if ( commanate ) { writer.write( ',' ); } if ( indentFactor > 0 ) { writer.write( '\n' ); } JSONObject.indent( writer, newindent ); JSONObject.writeValue( writer, this.myArrayList.get( i ), indentFactor, newindent ); commanate = true; } if ( indentFactor > 0 ) { writer.write( '\n' ); } JSONObject.indent( writer, indent ); } writer.write( ']' ); return writer; } catch ( IOException e ) { throw new JSONException( e ); } } }