46. Performance: adapted data structures
TL;DR (5 lines)
- Data structures are architectural choices.
- Use cases matter more than names.
- Aggregation flows are better teaching units than isolated declarations.
- Broken examples should show a mismatched shape.
- Container choice should remain visible in the code story.
Frequent mistakes
- 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.
Prerequisites: book/chapters/45-performance-allocations-copies.html. See also: book/chapters/45-performance-allocations-copies.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.
Work in this chapter
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)
}
export *Complete examples
Each block below is a complete reading unit with its own boundary, data shape, and observable result.
Primary coherent example
This is the compact chapter anchor used by the surrounding explanation.
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)
}
export *Aggregate values into a form
This program shows why grouped output deserves its own shape.
space examples/collections/aggregate
form Totals {
count: int
sum: int
}
proc totals(values: list[int]) -> Totals {
let count: int = 0
let sum: int = 0
for value in values {
set count = count + 1
set sum = sum + value
}
give Totals { count: count, sum: sum }
}
proc main(args: list[string]) -> int {
let result: Totals = totals([1, 2, 3])
give result.count
}
export *Filter before counting
This variant uses the collection because the access pattern requires iteration.
space examples/collections/filter
proc accepted(values: list[int]) -> int {
let count: int = 0
for value in values {
if value < 10 { continue }
set count = count + 1
}
give count
}
proc main(args: list[string]) -> int {
give accepted([3, 10, 12])
}
export *Immediate work for this chapter
- Show the access pattern that justifies the collection.
- Return a grouped result when aggregation creates a new domain shape.
- Avoid listing containers without a flow that uses them.
- Keep the first code block complete and aligned with current Vitte docs syntax.
- Keep the invalid block focused on one broken contract only.
- Replace generic prose with one concrete rule visible in the code.
- Keep every example small enough to review from top to bottom.
Chapter override: 46-adapted-data-structures.html
Dedicated problem
46. Performance: adapted data structures needs a concrete production-grade anchor around single value, grouped values, and aggregate result. The page should keep the examples, diagnostics, and review rules tied to that exact boundary instead of drifting back to generic tutorial prose.
Specific complete examples
46. Performance: adapted data structures chapter anchor
The primary example is promoted here as the first chapter-specific production reading unit.
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)
}
export *Aggregate values into a form
This program shows why grouped output deserves its own shape.
space examples/collections/aggregate
form Totals {
count: int
sum: int
}
proc totals(values: list[int]) -> Totals {
let count: int = 0
let sum: int = 0
for value in values {
set count = count + 1
set sum = sum + value
}
give Totals { count: count, sum: sum }
}
proc main(args: list[string]) -> int {
let result: Totals = totals([1, 2, 3])
give result.count
}
export *Filter before counting
This variant uses the collection because the access pattern requires iteration.
space examples/collections/filter
proc accepted(values: list[int]) -> int {
let count: int = 0
for value in values {
if value < 10 { continue }
set count = count + 1
}
give count
}
proc main(args: list[string]) -> int {
give accepted([3, 10, 12])
}
export *Risks and diagnostics
| Risk | Diagnostic signal | Action |
|---|---|---|
| Boundary drift | The chapter loses sight of single value, grouped values, and aggregate result. | Restate the boundary beside the first code block and every invalid case. |
| Generic prose | A paragraph would still be true in another chapter. | Replace it with a code-specific rule from this page. |
| Weak diagnostic | The failure does not point back to the chapter contract. | Reduce the invalid case until one failure explains the rule. |
Review checklist
- The first example is complete and aligned with Vitte docs syntax.
- The production section names where this construct belongs in real code.
- The risk table connects each failure to a diagnostic or review action.
- The avoid list rejects broad misuse without adding quiz-like prompts.
Production use
- Use this chapter when a code review needs to preserve single value, grouped values, and aggregate result.
- Keep examples small enough to copy into fixtures or docs smoke tests.
- Treat the invalid case as regression material for future docs checks.
What to avoid
- Do not add a second topic that hides the chapter's main contract.
- Do not expand examples by adding unrelated subsystems.
- Do not rely on prose when a small Vitte block can show the rule.
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
- Data structures are architectural choices.
- Use cases matter more than names.
- Aggregation flows are better teaching units than isolated declarations.
- Broken examples should show a mismatched shape.
- Container choice should remain visible in the code story.
See also
Next best action
Extend the coherent example by one small, justified step and keep the same contract visible from input to output.
Chapter deep dive
46. Performance: adapted data structures teaches data shape as an engineering choice. The chapter is written for a reader choosing a container because the domain requires one.
The practical boundary is: single value, grouped values, and aggregate result. Keep that boundary in view while reading the example, the invalid case, and the exercise.
Role in the learning path
Readers often see containers as names only, not as data-shape decisions embedded in a complete flow.
One report-building flow stores values, aggregates them, and returns a grouped result.
This chapter helps the reader choose structures based on access pattern and meaning.
Profile-specific deep dive
Access pattern
- Choose a collection because the code needs grouping, iteration, lookup, or aggregation.
- The example should show where values enter and leave the container.
- A collection without an access pattern is vocabulary, not design.
Aggregation result
- Use a result form when a loop produces more than one fact.
- Keep counters and totals visible while the aggregation runs.
- Return the grouped result rather than scattering related values across locals.
Reading the valid example
space demo/collections: names the ownership boundary before any behavior appears.form Metrics {: introduces a data contract that later branches can rely on.count: int: supports the chapter contract without adding hidden behavior.total: int: supports the chapter contract without adding hidden behavior.}: supports the chapter contract without adding hidden behavior.proc absorb(values: list[int]) -> Metrics {: states the callable contract: inputs first, result shape last.let count: int = 0: keeps an intermediate decision visible for review.let total: int = 0: keeps an intermediate decision visible for review.for value in values {: supports the chapter contract without adding hidden behavior.set count = count + 1: supports the chapter contract without adding hidden behavior.set total = total + value: supports the chapter contract without adding hidden behavior.}: supports the chapter contract without adding hidden behavior.give Metrics(count, total): ends the local path with an explicit result.}: supports the chapter contract without adding hidden behavior.export *: supports the chapter contract without adding hidden behavior.
Lesson from the invalid example
proc bad_metrics() -> int {: this line helps isolate the failure because it states the callable contract: inputs first, result shape last.let values: int = [1, 2, 3]: this line helps isolate the failure because it keeps an intermediate decision visible for review.give values: this line helps isolate the failure because it ends the local path with an explicit result.}: this line helps isolate the failure because it supports the chapter contract without adding hidden behavior.
Engineering decisions to preserve
- Name the boundary before changing code: Data structures are architectural choices.
- Keep the smallest example executable: Use cases matter more than names.
- Make the invalid path explain one failure only: Aggregation flows are better teaching units than isolated declarations.
- Prefer a visible contract over an implied convention: Broken examples should show a mismatched shape.
- Leave a review anchor that another maintainer can verify: Container choice should remain visible in the code story.
Context-specific review criteria
- The page makes the single value, grouped values, and aggregate result boundary visible before the first code block.
- The intended reader, a reader choosing a container because the domain requires one, can follow the valid example through named contracts instead of memorized tokens.
- The invalid example fails for the same reason the prose discusses.
- The exercise extends the same contract instead of introducing an unrelated concept.
- The next chapter can reuse the vocabulary introduced here without redefining it.
- The chapter stays specific enough that its title materially changes the meaning of the page.
- Every warning connects to a concrete code shape.
- The summary leaves one durable engineering rule behind.
Contract matrix
| Concern | Chapter rule | Evidence to keep |
|---|---|---|
| Ownership | Code belongs behind the boundary named by the chapter. | The chapter keeps ownership visible through single value, grouped values, and aggregate result. |
| Input contract | The procedure receives a shape that is named before branching. | The valid example names the accepted shape before branching. |
| Nominal path | The clean path remains readable without hidden state. | The successful result can be found without reading hidden state. |
| Failure path | The invalid case isolates one failure reason. | The broken example has one main reason to fail. |
| Naming | Names explain the domain rather than only the mechanism. | Names remain tied to the chapter goal. |
| Types | Types remove ambiguity from values and results. | Fields and return values carry domain meaning. |
| Control flow | Branches stay traceable from guard to result. | Guards appear before the result they protect. |
| Module boundary | The public surface stays smaller than implementation detail. | The public surface remains smaller than the implementation detail. |
| Diagnostic value | The failure path points back to the exact contract. | The invalid example points back to the exact contract. |
| Test value | Regression evidence covers one passing path and one failing path. | One passing case and one failing case cover the lesson. |
| Refactor value | Implementation cleanup preserves the result shape. | The result shape stays stable during local cleanup. |
| Publication value | The chapter leaves one concrete engineering rule. | The chapter leaves one concrete engineering rule. |
Rewrite path for this chapter
- Rewrite the opening paragraph so it names single value, grouped values, and aggregate result before naming syntax.
- Keep the valid example small enough that the full contract fits on screen.
- Move any broad claim back to a specific line in the example.
- Preserve one invalid case that fails for the chapter's main reason.
- Add one sentence explaining why the invalid case is not a random error.
- Make every pitfall actionable by naming the code shape it damages.
- Keep the exercise inside the same domain as the example.
- Avoid introducing a second unrelated project just to show variety.
- Use the summary to restate the chapter rule, not the table of contents.
- Check that the next chapter can build on this vocabulary.
- Remove any sentence that would still be true in every other chapter.
- Keep the last action small, local, and testable.
Diagnostic anchors
- The first inspected line is the one that declares the chapter's main contract.
- The central type, field, procedure, or branch carries the chapter's main idea.
- The invalid example includes a sentence-level explanation of its failure.
- Refactors preserve the detail that would otherwise mislead a future reader.
- The behavior that must stay stable is named before implementation changes begin.
- Vague names are replaced before they become review friction.
- Regression coverage protects the chapter's main contract.
- Implementation details stay out of public API unless the chapter explicitly teaches that surface.
- Beginner-facing diagnostics point to the contract, not to a random syntax detail.
- The next chapter can assume one clearly named concept from this page.
When extending this chapter
- Extend toward a reader choosing a container because the domain requires one, not toward a broader catalog of features.
- Add a second example only if it sharpens the same contract.
- Prefer a small variant over a new subsystem.
- Keep prose close to code; every abstract claim should point to a visible shape.
- Do not hide a new concept in the exercise.
- If a paragraph explains policy, add the concrete code boundary it protects.
- If a paragraph explains syntax, add the semantic reason the syntax matters.
- If a paragraph explains architecture, identify the owner of each boundary.
- If a paragraph explains failure, keep the failing line close to the explanation.
- Stop expanding when the chapter has one complete, testable lesson.
Failure modes to avoid
- 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.
Practice scenario
Start from the coherent example in 46. Performance: adapted data structures. Change one identifier, one guard, and one returned value. After each change, write down whether the public contract is still the same contract or a new one.
If the contract changed, update the type or result shape first. If only the implementation changed, keep the external name stable and add one regression note explaining what should not change again.
Before moving on
- You can state the chapter role: teaches data shape as an engineering choice.
- You can point to the main boundary: single value, grouped values, and aggregate result.
- You can connect the invalid case to the problem statement: Readers often see containers as names only, not as data-shape decisions embedded in a complete flow.
- You can perform the exercise: Replace the single summary form with two grouped buckets and explain why the new shape is justified.