std.typeset.breakParagraph

For the same ordered input values, policies, calculation grid, and product release, classifyBreaks and breakParagraph produce the same result. This includes boundary order, selected breaks, line widths, costs, and the returned error variant.

Planning reads measured text and policy values without changing caller arrays. It does not shape text, load fonts, or write output. Ordinary argument evaluation finishes before the operation begins.

The selected cost model, admission rules, and search bounds define plan quality. The two reported plans expose their own costs for inspection.

breakParagraph evaluates its Paragraph argument through the ordinary call rules, then reads its item sequence and policies. Planning performs no input mutation, text shaping, external I/O, or random selection. The same ordered input and computation rules produce the same lines and scores.

Paragraph.items supplies measured BoxItem and GlueItem units with contiguous indices from zero. PenaltyItem entries refer to boundaries between those units. The planner uses these measurements and supplied penalties directly. It does not call classifyBreaks or insert a terminal penalty.

Paragraph.grid selects integer quantization at the computation boundary. Every public distance remains Length<Pt>. FixedPoint requires MilliPoint. KnuthPlass accepts either DistanceGrid. The ordinary checked length conversion applies before integer planning.

Policy validation precedes item validation. Geometry, the cost model and grid combination, justification values, and KnuthPlassPolicy are validated even when a chosen model does not use a policy field for scoring. Invalid configuration returns TypesetError.InvalidPolicy. Invalid unit indices, capacities, or penalty endpoints return TypesetError.InvalidInput.

A valid empty items array returns two empty plans with zero totalCost and zero breakOpportunityCount. This case still validates the policies. Each empty plan reports its selected grid and None() for boundedFillFeasible.

For nonempty input, the planner orders penalties by increasing unitEnd and preserves supplied order at equal boundaries. Allowed and Forced entries are candidates. Forbidden entries are excluded individually. Duplicate candidates remain distinct. A Forced entry requires the plan to visit its boundary, where another eligible entry may be selected.

No candidates returns TypesetError.NoBreakOpportunities. The planner constructs the greedy baseline before the optimized search. Failure to complete that baseline returns TypesetError.NoGreedyPlan. A completed baseline followed by an unsuccessful optimized search returns TypesetError.NoPlan. An Err result contains no partial ParagraphResult.

For FixedPoint, greedy chooses the farthest raw width that fits the next target before the first overwide candidate or Forced boundary. If the first candidate is already overwide, greedy chooses it to advance. For KnuthPlass, greedy chooses the last ratio-admissible candidate up to the next Forced boundary. Every chosen boundary advances past the previous one.

FixedPoint optimization starts with the preceding 80 candidates at each destination. It extends the search backward while the preceding span fits the larger base target plus available shrink and one grid unit. It retains the least score for each boundary and semantic state. It admits at most two consecutive LatinSoftHyphen breaks.

FixedPoint optimized admission uses trimmed text width plus the selected penalty width. The width limit is the target plus available shrink for a nonfinal line, with one grid unit of rounding allowance. A line containing one unit can exceed this limit so an indivisible unit can make progress. Greedy reports the same limit but selects candidates using its raw width rule.

With FixedPoint, a justified mode, and Some(latinSpacing), optimization first searches for a complete plan whose lines satisfy the bounded fill check. It prefers that plan when found. Otherwise it repeats the search without that check. This preference can select a plan with a higher totalCost than the greedy plan.

KnuthPlass optimization considers every preceding candidate and retains each distinct line geometry bucket, fitness class, and flagged state at a boundary. FixedPoint also retains its soft hyphen streak. State buckets distinguish drop cap lines and collapse after the inset ends.

Equal scores retain the first visited predecessor. Candidates are visited in boundary order, with supplied order at equal boundaries. States are visited by increasing line geometry bucket, soft hyphen streak, fitness class, and then unflagged before flagged. Final selection uses the same first-on-equal rule.

The optimized field reports the selected model search and admission policy. The greedy field reports its baseline from the same input. Each reported cost belongs to the plan selected by these candidate, state, and admission rules. Ordinary checked arithmetic faults remain faults and are not converted into a TypesetError value.