Home > Data > Flatten

< Previous: Collect | Next: Item at Index >

Drop the list structure, and leave the geometry alone. The inverse of Collect.

Category: Data | Add menu: Data > Lists > Flatten

A Collect wraps what you give it into a list. Flatten takes that wrapping back off. Nothing about the geometry changes: the same contours, the same curves, the same styles and the same groups come out the other side. Only the list goes.

• Geometry (any): the collection to flatten.
• Levels (number, editable): how many wraps to peel. -1 is the default and peels every level, however deeply they nested. 0 peels none. 1 peels the outermost and promotes what was under it, 2 peels two, and so on.

• Geometry (any): the same contents, with that many wraps fewer.

The diagram above is one row per value, in order.

Levels -1 is the default and goes all the way down: in the diagram, all nine items end up loose.

Levels 0 peels nothing, so that row is also what arrived. This looks like a wasted setting, and it is deliberate: a Flatten wired in by accident is then a visible pass-through rather than a silent no-op you have to go hunting for. It also means 0 cannot be confused with "all", which is what a plain count would have implied, and why -1 carries that job instead.

Levels 1 peels from the outside in. The three outer groups go, their contents join the list, and the inner group of items 4 and 5 is still a group, sitting there as one item.

A value larger than the collection is deep is harmless: it runs out of wraps and stops.

This is the distinction worth holding on to, because the two look alike and are not.

A group in the collection sense is the wrapping a Collect builds, and that is what Levels peels. A copy's own group is something else: it is what makes that copy one region rather than part of a merged blob, and Mirror, Rotate and Array already stamp every copy they make as its own. Flatten does not touch that. Items come out the same objects they went in as.

So flattening never welds anything together or pulls anything apart. It changes only how the list is nested.

Any time a data stream arrives grouped and the next node needs it loose.

A node that reads a list item by item sees a group as one item, so everything inside that group gets handled as a single thing. Put a Flatten in front of it and each item arrives on its own.

That is the whole job, and it costs nothing to try. The geometry is untouched either way, so when a node downstream is not seeing the items you expect, a Flatten is the first thing to reach for.

• Collect: builds the list Flatten takes apart. They are inverses.
• List Length: the quickest way to see what a Flatten did to the count.
• Item at Index: reads the same nesting Flatten changes.
• Lists & collections: what nesting is, and how deep it goes.

< Previous: Collect | Next: Item at Index >