8. Data Structures

Level: beginner · Reading time: 13 min · Prerequisite: book/chapters/07-controle.html · Track: essential · Maturity: reviewed · Last review: 2026-05-09

Prerequisites: book/chapters/07-controle.html. See also: book/chapters/07-controle.html, book/chapters/27-grammar.html, book/chapters/31-build-errors.html.

Concrete Problem

Readers often see containers as names only, not as data-shape decisions embedded in a complete flow.

Red Thread (Single Project)

One report-building flow stores values, aggregates them, and returns a grouped result.

For what

This chapter helps the reader choose structures based on access pattern and meaning.

What you are going to do

You will read one grouped-data scenario, identify why the container exists, then inspect a broken variant.

Coherent example

space demo/collections

form Metrics {
  count: int
  total: int
}

proc absorb(values: list[int]) -> Metrics {
  let count: int = 0
  let total: int = 0
  for value in values {
    set count = count + 1
    set total = total + value
  }
  give Metrics(count, total)
}

Global explanation

Collections pages are useful only when they explain why a shape exists. The example shows aggregation as a real need for a container-like surface instead of presenting structures as vocabulary alone.

Invalid case

proc bad_metrics() -> int {
  let values: int = [1, 2, 3]
  give values
}

This invalid case is intentionally small. It exists to isolate the contract failure that the chapter is trying to teach.

Common pitfalls

• Listing containers without an access pattern or use case.
• Treating structure choice as style instead of behavior.
• Hiding where grouped data enters and leaves the block.

Short exercise

Replace the single summary form with two grouped buckets and explain why the new shape is justified.

Summary in 5 points

1. Data structures are architectural choices.
2. Use cases matter more than names.
3. Aggregation flows are better teaching units than isolated declarations.
4. Broken examples should show a mismatched shape.
5. Container choice should remain visible in the code story.