Codebase list libandroid-json-org-java / ec0eae6
Javadoc for JSONArray. Change-Id: I3aced2607b48210f76887e0d42b591c098ce5db7 Jesse Wilson authored 14 years ago Thomas Koch committed 11 years ago
2 changed file(s) with 291 addition(s) and 25 deletion(s). Raw diff Collapse all Expand all
+264
-1
src/main/java/org/json/JSONArray.java less more
2222 // Note: this class was written without inspecting the non-free org.json sourcecode.
2323
2424 /**
25 * An indexed sequence of JSON-safe values.
25 * A dense indexed sequence of values. Values may be any mix of
26 * {@link JSONObject JSONObjects}, other {@link JSONArray JSONArrays}, Strings,
27 * Booleans, Integers, Longs, Doubles, {@code null} or {@link JSONObject#NULL}.
28 * Values may not be {@link Double#isNaN() NaNs}, {@link Double#isInfinite()
29 * infinities}, or of any type not listed here.
30 *
31 * <p>{@code JSONArray} has the same type coercion behavior and
32 * optional/mandatory accessors as {@link JSONObject}. See that class'
33 * documentation for details.
34 *
35 * <p><strong>Warning:</strong> this class represents null in two incompatible
36 * ways: the standard Java {@code null} reference, and the sentinel value {@link
37 * JSONObject#NULL}. In particular, {@code get()} fails if the requested index
38 * holds the null reference, but succeeds if it holds {@code JSONObject.NULL}.
39 *
40 * <p>Instances of this class are not thread safe. Although this class is
41 * nonfinal, it was not designed for inheritance and should not be subclassed.
42 * In particular, self-use by overridable methods is not specified. See
43 * <i>Effective Java</i> Item 17, "Design and Document or inheritance or else
44 * prohibit it" for further information.
2645 */
2746 public class JSONArray {
2847
2948 private final List<Object> values;
3049
50 /**
51 * Creates a {@code JSONArray} with no values.
52 */
3153 public JSONArray() {
3254 values = new ArrayList<Object>();
3355 }
3456
57 /**
58 * Creates a new {@code JSONArray} by copying all values from the given
59 * collection.
60 *
61 * @param copyFrom a collection whose values are of supported types.
62 * Unsupported values are not permitted and will yield an array in an
63 * inconsistent state.
64 */
3565 /* Accept a raw type for API compatibility */
3666 public JSONArray(Collection copyFrom) {
3767 this();
3969 values.addAll(copyFromTyped);
4070 }
4171
72 /**
73 * Creates a new {@code JSONArray} with values from the next array in the
74 * tokener.
75 *
76 * @param readFrom a tokener whose nextValue() method will yield a
77 * {@code JSONArray}.
78 * @throws JSONException if the parse fails or doesn't yield a
79 * {@code JSONArray}.
80 */
4281 public JSONArray(JSONTokener readFrom) throws JSONException {
4382 /*
4483 * Getting the parser to populate this could get tricky. Instead, just
5291 }
5392 }
5493
94 /**
95 * Creates a new {@code JSONArray} with values from the JSON string.
96 *
97 * @param json a JSON-encoded string containing an array.
98 * @throws JSONException if the parse fails or doesn't yield a {@code
99 * JSONArray}.
100 */
55101 public JSONArray(String json) throws JSONException {
56102 this(new JSONTokener(json));
57103 }
58104
105 /**
106 * Returns the number of values in this array.
107 */
59108 public int length() {
60109 return values.size();
61110 }
62111
112 /**
113 * Appends {@code value} to the end of this array.
114 *
115 * @return this array.
116 */
63117 public JSONArray put(boolean value) {
64118 values.add(value);
65119 return this;
66120 }
67121
122 /**
123 * Appends {@code value} to the end of this array.
124 *
125 * @param value a finite value. May not be {@link Double#isNaN() NaNs} or
126 * {@link Double#isInfinite() infinities}.
127 * @return this array.
128 */
68129 public JSONArray put(double value) throws JSONException {
69130 values.add(JSON.checkDouble(value));
70131 return this;
71132 }
72133
134 /**
135 * Appends {@code value} to the end of this array.
136 *
137 * @return this array.
138 */
73139 public JSONArray put(int value) {
74140 values.add(value);
75141 return this;
76142 }
77143
144 /**
145 * Appends {@code value} to the end of this array.
146 *
147 * @return this array.
148 */
78149 public JSONArray put(long value) {
79150 values.add(value);
80151 return this;
81152 }
82153
154 /**
155 * Appends {@code value} to the end of this array.
156 *
157 * @param value a {@link JSONObject}, {@link JSONArray}, String, Boolean,
158 * Integer, Long, Double, {@link JSONObject#NULL}, or {@code null}. May
159 * not be {@link Double#isNaN() NaNs} or {@link Double#isInfinite()
160 * infinities}. Unsupported values are not permitted and will cause the
161 * array to be in an inconsistent state.
162 * @return this array.
163 */
83164 public JSONArray put(Object value) {
84165 values.add(value);
85166 return this;
86167 }
87168
169 /**
170 * Sets the value at {@code index} to {@code value}, null padding this array
171 * to the required length if necessary. If a value already exists at {@code
172 * index}, it will be replaced.
173 *
174 * @return this array.
175 */
88176 public JSONArray put(int index, boolean value) throws JSONException {
89177 return put(index, (Boolean) value);
90178 }
91179
180 /**
181 * Sets the value at {@code index} to {@code value}, null padding this array
182 * to the required length if necessary. If a value already exists at {@code
183 * index}, it will be replaced.
184 *
185 * @param value a finite value. May not be {@link Double#isNaN() NaNs} or
186 * {@link Double#isInfinite() infinities}.
187 * @return this array.
188 */
92189 public JSONArray put(int index, double value) throws JSONException {
93190 return put(index, (Double) value);
94191 }
95192
193 /**
194 * Sets the value at {@code index} to {@code value}, null padding this array
195 * to the required length if necessary. If a value already exists at {@code
196 * index}, it will be replaced.
197 *
198 * @return this array.
199 */
96200 public JSONArray put(int index, int value) throws JSONException {
97201 return put(index, (Integer) value);
98202 }
99203
204 /**
205 * Sets the value at {@code index} to {@code value}, null padding this array
206 * to the required length if necessary. If a value already exists at {@code
207 * index}, it will be replaced.
208 *
209 * @return this array.
210 */
100211 public JSONArray put(int index, long value) throws JSONException {
101212 return put(index, (Long) value);
102213 }
103214
215 /**
216 * Sets the value at {@code index} to {@code value}, null padding this array
217 * to the required length if necessary. If a value already exists at {@code
218 * index}, it will be replaced.
219 *
220 * @param value a {@link JSONObject}, {@link JSONArray}, String, Boolean,
221 * Integer, Long, Double, {@link JSONObject#NULL}, or {@code null}. May
222 * not be {@link Double#isNaN() NaNs} or {@link Double#isInfinite()
223 * infinities}.
224 * @return this array.
225 */
104226 public JSONArray put(int index, Object value) throws JSONException {
105227 if (value instanceof Number) {
106228 // deviate from the original by checking all Numbers, not just floats & doubles
113235 return this;
114236 }
115237
238 /**
239 * Returns true if this array has no value at {@code index}, or if its value
240 * is the {@code null} reference or {@link JSONObject#NULL}.
241 */
116242 public boolean isNull(int index) {
117243 Object value = opt(index);
118244 return value == null || value == JSONObject.NULL;
119245 }
120246
247 /**
248 * Returns the value at {@code index}.
249 *
250 * @throws JSONException if this array has no value at {@code index}, or if
251 * that value is the {@code null} reference. This method returns
252 * normally if the value is {@code JSONObject#NULL}.
253 */
121254 public Object get(int index) throws JSONException {
122255 try {
123256 Object value = values.get(index);
130263 }
131264 }
132265
266 /**
267 * Returns the value at {@code index}, or null if the array has no value
268 * at {@code index}.
269 */
133270 public Object opt(int index) {
134271 if (index < 0 || index >= values.size()) {
135272 return null;
137274 return values.get(index);
138275 }
139276
277 /**
278 * Returns the value at {@code index} if it exists and is a boolean or can
279 * be coerced to a boolean.
280 *
281 * @throws JSONException if the value at {@code index} doesn't exist or
282 * cannot be coerced to a boolean.
283 */
140284 public boolean getBoolean(int index) throws JSONException {
141285 Object object = get(index);
142286 Boolean result = JSON.toBoolean(object);
146290 return result;
147291 }
148292
293 /**
294 * Returns the value at {@code index} if it exists and is a boolean or can
295 * be coerced to a boolean. Returns false otherwise.
296 */
149297 public boolean optBoolean(int index) {
150298 return optBoolean(index, false);
151299 }
152300
301 /**
302 * Returns the value at {@code index} if it exists and is a boolean or can
303 * be coerced to a boolean. Returns {@code fallback} otherwise.
304 */
153305 public boolean optBoolean(int index, boolean fallback) {
154306 Object object = opt(index);
155307 Boolean result = JSON.toBoolean(object);
156308 return result != null ? result : fallback;
157309 }
158310
311 /**
312 * Returns the value at {@code index} if it exists and is a double or can
313 * be coerced to a double.
314 *
315 * @throws JSONException if the value at {@code index} doesn't exist or
316 * cannot be coerced to a double.
317 */
159318 public double getDouble(int index) throws JSONException {
160319 Object object = get(index);
161320 Double result = JSON.toDouble(object);
165324 return result;
166325 }
167326
327 /**
328 * Returns the value at {@code index} if it exists and is a double or can
329 * be coerced to a double. Returns {@code NaN} otherwise.
330 */
168331 public double optDouble(int index) {
169332 return optDouble(index, Double.NaN);
170333 }
171334
335 /**
336 * Returns the value at {@code index} if it exists and is a double or can
337 * be coerced to a double. Returns {@code fallback} otherwise.
338 */
172339 public double optDouble(int index, double fallback) {
173340 Object object = opt(index);
174341 Double result = JSON.toDouble(object);
175342 return result != null ? result : fallback;
176343 }
177344
345 /**
346 * Returns the value at {@code index} if it exists and is an int or
347 * can be coerced to an int.
348 *
349 * @throws JSONException if the value at {@code index} doesn't exist or
350 * cannot be coerced to a int.
351 */
178352 public int getInt(int index) throws JSONException {
179353 Object object = get(index);
180354 Integer result = JSON.toInteger(object);
184358 return result;
185359 }
186360
361 /**
362 * Returns the value at {@code index} if it exists and is an int or
363 * can be coerced to an int. Returns 0 otherwise.
364 */
187365 public int optInt(int index) {
188366 return optInt(index, 0);
189367 }
190368
369 /**
370 * Returns the value at {@code index} if it exists and is an int or
371 * can be coerced to an int. Returns {@code fallback} otherwise.
372 */
191373 public int optInt(int index, int fallback) {
192374 Object object = opt(index);
193375 Integer result = JSON.toInteger(object);
194376 return result != null ? result : fallback;
195377 }
196378
379 /**
380 * Returns the value at {@code index} if it exists and is a long or
381 * can be coerced to a long.
382 *
383 * @throws JSONException if the value at {@code index} doesn't exist or
384 * cannot be coerced to a long.
385 */
197386 public long getLong(int index) throws JSONException {
198387 Object object = get(index);
199388 Long result = JSON.toLong(object);
203392 return result;
204393 }
205394
395 /**
396 * Returns the value at {@code index} if it exists and is a long or
397 * can be coerced to a long. Returns 0 otherwise.
398 */
206399 public long optLong(int index) {
207400 return optLong(index, 0L);
208401 }
209402
403 /**
404 * Returns the value at {@code index} if it exists and is a long or
405 * can be coerced to a long. Returns {@code fallback} otherwise.
406 */
210407 public long optLong(int index, long fallback) {
211408 Object object = opt(index);
212409 Long result = JSON.toLong(object);
213410 return result != null ? result : fallback;
214411 }
215412
413 /**
414 * Returns the value at {@code index} if it exists, coercing it if
415 * necessary.
416 *
417 * @throws JSONException if no such value exists.
418 */
216419 public String getString(int index) throws JSONException {
217420 Object object = get(index);
218421 String result = JSON.toString(object);
222425 return result;
223426 }
224427
428 /**
429 * Returns the value at {@code index} if it exists, coercing it if
430 * necessary. Returns the empty string if no such value exists.
431 */
225432 public String optString(int index) {
226433 return optString(index, "");
227434 }
228435
436 /**
437 * Returns the value at {@code index} if it exists, coercing it if
438 * necessary. Returns {@code fallback} if no such value exists.
439 */
229440 public String optString(int index, String fallback) {
230441 Object object = opt(index);
231442 String result = JSON.toString(object);
232443 return result != null ? result : fallback;
233444 }
234445
446 /**
447 * Returns the value at {@code index} if it exists and is a {@code
448 * JSONArray}.
449 *
450 * @throws JSONException if the value doesn't exist or is not a {@code
451 * JSONArray}.
452 */
235453 public JSONArray getJSONArray(int index) throws JSONException {
236454 Object object = get(index);
237455 if (object instanceof JSONArray) {
241459 }
242460 }
243461
462 /**
463 * Returns the value at {@code index} if it exists and is a {@code
464 * JSONArray}. Returns null otherwise.
465 */
244466 public JSONArray optJSONArray(int index) {
245467 Object object = opt(index);
246468 return object instanceof JSONArray ? (JSONArray) object : null;
247469 }
248470
471 /**
472 * Returns the value at {@code index} if it exists and is a {@code
473 * JSONObject}.
474 *
475 * @throws JSONException if the value doesn't exist or is not a {@code
476 * JSONObject}.
477 */
249478 public JSONObject getJSONObject(int index) throws JSONException {
250479 Object object = get(index);
251480 if (object instanceof JSONObject) {
255484 }
256485 }
257486
487 /**
488 * Returns the value at {@code index} if it exists and is a {@code
489 * JSONObject}. Returns null otherwise.
490 */
258491 public JSONObject optJSONObject(int index) {
259492 Object object = opt(index);
260493 return object instanceof JSONObject ? (JSONObject) object : null;
261494 }
262495
496 /**
497 * Returns a new object whose values are the values in this array, and whose
498 * names are the values in {@code names}. Names and values are paired up by
499 * index from 0 through to the shorter array's length. Names that are not
500 * strings will be coerced to strings. This method returns null if either
501 * array is empty.
502 */
263503 public JSONObject toJSONObject(JSONArray names) throws JSONException {
264504 JSONObject result = new JSONObject();
265505 int length = Math.min(names.length(), values.size());
273513 return result;
274514 }
275515
516 /**
517 * Returns a new string by alternating this array's values with {@code
518 * separator}. This array's string values are quoted and have their special
519 * characters escaped. For example, the array containing the strings '12"
520 * pizza', 'taco' and 'soda' joined on '+' returns this:
521 * <pre>"12\" pizza"+"taco"+"soda"</pre>
522 */
276523 public String join(String separator) throws JSONException {
277524 JSONStringer stringer = new JSONStringer();
278525 stringer.open(JSONStringer.Scope.NULL, "");
286533 return stringer.out.toString();
287534 }
288535
536 /**
537 * Encodes this array as a compact JSON string, such as:
538 * <pre>[94043,90210]</pre>
539 */
289540 @Override public String toString() {
290541 try {
291542 JSONStringer stringer = new JSONStringer();
296547 }
297548 }
298549
550 /**
551 * Encodes this array as a human readable JSON string for debugging, such
552 * as:
553 * <pre>
554 * [
555 * 94043,
556 * 90210
557 * ]</pre>
558 *
559 * @param indentSpaces the number of spaces to indent for each level of
560 * nesting.
561 */
299562 public String toString(int indentSpaces) throws JSONException {
300563 JSONStringer stringer = new JSONStringer(indentSpaces);
301564 writeTo(stringer);
+27
-24
src/main/java/org/json/JSONObject.java less more
2424
2525 /**
2626 * A modifiable set of name/value mappings. Names are unique, non-null strings.
27 * Values may be other {@link JSONObject JSONObjects}, {@link JSONArray
27 * Values may be any mix of {@link JSONObject JSONObjects}, {@link JSONArray
2828 * JSONArrays}, Strings, Booleans, Integers, Longs, Doubles or {@link #NULL}.
29 * Values may not be {@code null}, {@link Double#isNaN() NaNs} or {@link
30 * Double#isInfinite() infinities}.
29 * Values may not be {@code null}, {@link Double#isNaN() NaNs}, {@link
30 * Double#isInfinite() infinities}, or of any type not listed here.
3131 *
3232 * <p>This class can coerce values to another type when requested.
3333 * <ul>
6161 * </ul>
6262 *
6363 * <p><strong>Warning:</strong> this class represents null in two incompatible
64 * ways: the standard Java {@code null} literal, and the sentinel value {@link
65 * JSONObject#NULL JSONObject.NULL}. In particular, calling {@code
66 * put(name, null)} removes the named entry from the object but {@code
67 * put(name, JSONObject.NULL)} stores an entry whose value is {@code
68 * JSONObject.NULL}.
64 * ways: the standard Java {@code null} reference, and the sentinel value {@link
65 * JSONObject#NULL}. In particular, calling {@code put(name, null)} removes the
66 * named entry from the object but {@code put(name, JSONObject.NULL)} stores an
67 * entry whose value is {@code JSONObject.NULL}.
6968 *
7069 * <p>Instances of this class are not thread safe. Although this class is
7170 * nonfinal, it was not designed for inheritance and should not be subclassed.
104103 private final Map<String, Object> nameValuePairs;
105104
106105 /**
107 * Creates a JSONObject with no name/value mappings.
106 * Creates a {@code JSONObject} with no name/value mappings.
108107 */
109108 public JSONObject() {
110109 nameValuePairs = new HashMap<String, Object>();
111110 }
112111
113112 /**
114 * Creates a new JSONObject by copying all name/value mappings from the
115 * given map.
113 * Creates a new {@code JSONObject} by copying all name/value mappings from
114 * the given map.
116115 *
117116 * @param copyFrom a map whose keys are of type {@link String} and whose
118 * values are of supported types. Values do not need to be homogeneous.
117 * values are of supported types.
119118 * @throws NullPointerException if any of the map's keys are null.
120119 */
121120 /* (accept a raw type for API compatibility) */
136135 }
137136
138137 /**
139 * Creates a new JSONObject with name/value mappings from the next value in
140 * the tokenizer.
141 *
142 * @param readFrom a tokenizer whose nextValue() method will yield a JSONObject.
143 * @throws JSONException if the parse fails or doesn't yield a JSONObject.
138 * Creates a new {@code JSONObject} with name/value mappings from the next
139 * object in the tokener.
140 *
141 * @param readFrom a tokener whose nextValue() method will yield a
142 * {@code JSONObject}.
143 * @throws JSONException if the parse fails or doesn't yield a
144 * {@code JSONObject}.
144145 */
145146 public JSONObject(JSONTokener readFrom) throws JSONException {
146147 /*
156157 }
157158
158159 /**
159 * Creates a new JSONObject with name/value mappings from the JSON string.
160 * Creates a new {@code JSONObject} with name/value mappings from the JSON
161 * string.
160162 *
161163 * @param json a JSON-encoded string containing an object.
162 * @throws JSONException if the parse fails or doesn't yield a JSONObject.
164 * @throws JSONException if the parse fails or doesn't yield a {@code
165 * JSONObject}.
163166 */
164167 public JSONObject(String json) throws JSONException {
165168 this(new JSONTokener(json));
166169 }
167170
168171 /**
169 * Creates a new JSONObject by copying mappings for the listed names from
170 * the given object. Names that aren't present in {@code copyFrom} will be
171 * skipped.
172 * Creates a new {@code JSONObject} by copying mappings for the listed names
173 * from the given object. Names that aren't present in {@code copyFrom} will
174 * be skipped.
172175 */
173176 public JSONObject(JSONObject copyFrom, String[] names) throws JSONException {
174177 this();
621624 }
622625
623626 /**
624 * Encodes this object as a compact JSON string, such as
627 * Encodes this object as a compact JSON string, such as:
625628 * <pre>{"query":"Pizza","locations":[94043,90210]}</pre>
626629 */
627630 @Override public String toString() {
636639
637640 /**
638641 * Encodes this object as a human readable JSON string for debugging, such
639 * as
642 * as:
640643 * <pre>
641644 * {
642645 * "query": "Pizza",