beginFlatten

Cancels immediately-nested calls to beginArray or beginObject and their matching calls to endArray or endObject. Use this to compose JSON adapters without nesting.

For example, the following creates JSON with nested arrays: [1,[2,3,4],5].

JsonAdapter<List<Integer>> integersAdapter = ...

public void writeNumbers(JsonWriter writer) {
  writer.beginArray();
  writer.value(1);
  integersAdapter.toJson(writer, Arrays.asList(2, 3, 4));
  writer.value(5);
  writer.endArray();
}

With flattening we can create JSON with a single array [1,2,3,4,5]:

JsonAdapter<List<Integer>> integersAdapter = ...

public void writeNumbers(JsonWriter writer) {
  writer.beginArray();
  int token = writer.beginFlatten();
  writer.value(1);
  integersAdapter.toJson(writer, Arrays.asList(2, 3, 4));
  writer.value(5);
  writer.endFlatten(token);
  writer.endArray();
}

This method flattens arrays within arrays:

Emit:       [1, [2, 3, 4], 5]
To produce: [1, 2, 3, 4, 5]

It also flattens objects within objects. Do not call name before writing a flattened object.

Emit:       {"a": 1, {"b": 2}, "c": 3}
To Produce: {"a": 1, "b": 2, "c": 3}

Other combinations are permitted but do not perform flattening. For example, objects inside of arrays are not flattened:

Emit:       [1, {"b": 2}, 3, [4, 5], 6]
To Produce: [1, {"b": 2}, 3, 4, 5, 6]

This method returns an opaque token. Callers must match all calls to this method with a call to endFlatten with the matching token.