Skip to content
Topaz6.0 · Before release
Download

Search documentation

Specification 6.0 · Not released · Tested product 5.21.3

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Library · std.typeset

    Penalty.width

    The nonnegative point width added when this candidate is selected.

    Penalty.width: Length<Pt>
    Receiver
    Penalty
    Minimum arity
    0
    Maximum arity
    0

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.typeset in language mode 5.21.

    The current compiler selects std/typeset.tpz for this language mode. Availability in other released editions and inclusion in each installed distribution are Pending.

    Source evidence

    Receiver

    Penalty

    Parameter constraints

    Additional contracts are Pending.

    Public measurement fields use Length<Pt>. Widths, advances, tracking, stretch, shrink, physical targets, insets, font sizes, and optional width limits keep that type across input and output records. Explicit Length conversion functions remain the integer interchange boundary.

    Box.width, Box.trackingAfter, Glue.width, Glue.trackingAfter, Glue.stretch, Glue.shrink, and Penalty.width have type Length<Pt>.

    BreakCluster.advance, BreakCluster.trackingAfter, BreakPolicy.narrowestWordTarget, and BreakPolicy.bodyWordTarget have type Length<Pt>.

    LatinSpacing.fontSizePt, JustificationPolicy.maxAdjustment, and JustificationPolicy.maxGapAdjustment have type Length<Pt>.

    LineGeometry.bodyTarget, LineGeometry.firstTarget, and LineGeometry.dropCapInset have type Length<Pt>.

    PlanLine.target, PlanLine.rawTextWidth, PlanLine.trimmedTextWidth, PlanLine.costTextWidth, and PlanLine.selectedPenaltyWidth have type Length<Pt>. PlanLine.postValidationWidthLimit has type Option<Length<Pt>>.

    An int, a float, or a Length with another unit marker is not an implicit point-length argument. Convert physical units explicitly with toPt() before constructing a typesetting record.

    Indices, counts, penalties, costs, and dimensionless ratios retain their declared types. LatinSpacing.maxLetterSpacingEm is a relative Length<Em>. Resolve it to Length<Pt> with fontSizePt before selecting the computation grid.

    Paragraph.grid selects quantization at the computation boundary. ScaledPoint uses the exact scaled-point integer. MilliPoint uses the existing nearest-even conversion to millipoints. The selected grid never changes the physical interpretation of a public Length<Pt> value.

    Returned distances are converted from the computation grid into Length<Pt> at the output boundary. ParagraphPlan.grid reports the computation policy and is not needed to interpret its distances.

    The public type change preserves the selected cost model. FixedPoint retains its MilliPoint computation requirement. Word-space and CJK ratio calculations keep their independent floor rules. The relative letter-spacing distance is resolved and quantized through the shared Length conversions before it contributes to capacity.

    The public line-badness entry point also receives width, target, and hyphen advance as Length<Pt>. It converts those distances to millipoints at entry and preserves its existing integer cost calculation.

    Related rule: Give public typesetting distances a point-length type

    Penalty.unitEnd is the exclusive end of a measured unit span. It must be greater than zero and no greater than the paragraph unit count. The penalty's position in the Item array does not set that boundary.

    Planning collects penalties and visits them in increasing unitEnd order. Equal endpoints retain input order. Duplicate endpoints remain separate candidates and are counted separately in breakOpportunityCount.

    Penalty.rule determines whether a candidate is selectable and how its additional cost is interpreted. Forbidden removes that candidate. A selectable duplicate at the same endpoint remains available. A Forced entry prevents any line from crossing that boundary.

    Penalty.kind describes the selected boundary independently of its rule. For example a Forced rule can carry a LatinHyphen kind. The chosen line reports the selected candidate's kind.

    Penalty.width is a nonnegative Length<Pt> that contributes when that candidate ends a line. Both cost models include this width for every kind. Unselected candidates contribute no width.

    PlanLine.selectedPenaltyWidth reports that selected width separately from the measured text widths. Input penalty widths are validated even for Forbidden candidates.

    Penalty.flagged marks a break for KnuthPlassPolicy.flaggedDemerit and finalFlaggedDemerit. FixedPoint does not use this flag. Its consecutive soft hyphen rule depends on kind.

    An out-of-range unitEnd or negative penalty width returns InvalidInput from breakParagraph. Record and Item construction preserve the supplied data until that call validates it.

    A complete plan needs a selectable terminal candidate at the unit count. Paragraph planning does not synthesize a terminal penalty or invoke break classification on the measured items.

    Related rule: Apply penalties at measured unit boundaries

    Result

    Additional contracts are Pending.

    The declared result type is Length<Pt>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Select this field from a value of its named type without call parentheses.

    Every selected kind contributes this width under either cost model. PlanLine reports it separately from text widths.

    Why

    Link

    The record keeps source identity, measured geometry, and boundary policy explicit at the paragraph planning call.

    Related entries

    Link

    std.typeset

    Give public typesetting distances a point-length type

    Link
    Ruletopaz.stdlib.contract.typeset-length-pt.rule

    Give public typesetting distances a point-length type

    Public measurement fields use Length<Pt>. Widths, advances, tracking, stretch, shrink, physical targets, insets, font sizes, and optional width limits keep that type across input and output records. Explicit Length conversion functions remain the integer interchange boundary.

    Box.width, Box.trackingAfter, Glue.width, Glue.trackingAfter, Glue.stretch, Glue.shrink, and Penalty.width have type Length<Pt>.

    BreakCluster.advance, BreakCluster.trackingAfter, BreakPolicy.narrowestWordTarget, and BreakPolicy.bodyWordTarget have type Length<Pt>.

    LatinSpacing.fontSizePt, JustificationPolicy.maxAdjustment, and JustificationPolicy.maxGapAdjustment have type Length<Pt>.

    LineGeometry.bodyTarget, LineGeometry.firstTarget, and LineGeometry.dropCapInset have type Length<Pt>.

    PlanLine.target, PlanLine.rawTextWidth, PlanLine.trimmedTextWidth, PlanLine.costTextWidth, and PlanLine.selectedPenaltyWidth have type Length<Pt>. PlanLine.postValidationWidthLimit has type Option<Length<Pt>>.

    An int, a float, or a Length with another unit marker is not an implicit point-length argument. Convert physical units explicitly with toPt() before constructing a typesetting record.

    Indices, counts, penalties, costs, and dimensionless ratios retain their declared types. LatinSpacing.maxLetterSpacingEm is a relative Length<Em>. Resolve it to Length<Pt> with fontSizePt before selecting the computation grid.

    Paragraph.grid selects quantization at the computation boundary. ScaledPoint uses the exact scaled-point integer. MilliPoint uses the existing nearest-even conversion to millipoints. The selected grid never changes the physical interpretation of a public Length<Pt> value.

    Returned distances are converted from the computation grid into Length<Pt> at the output boundary. ParagraphPlan.grid reports the computation policy and is not needed to interpret its distances.

    The public type change preserves the selected cost model. FixedPoint retains its MilliPoint computation requirement. Word-space and CJK ratio calculations keep their independent floor rules. The relative letter-spacing distance is resolved and quantized through the shared Length conversions before it contributes to capacity.

    The public line-badness entry point also receives width, target, and hyphen advance as Length<Pt>. It converts those distances to millipoints at entry and preserves its existing integer cost calculation.

    Why

    A physical distance carries the same Length<Pt> type in application geometry and paragraph planning. The type prevents a grid selector or an unlabelled scalar from silently changing the distance.

    Examples Use point lengths in BoxReject untyped physical distances in BoxUse point lengths in GlueReject untyped physical distances in GlueUse point lengths in PenaltyReject untyped physical distances in PenaltyUse point lengths in BreakPolicyReject untyped physical distances in BreakPolicyUse point lengths in BreakClusterReject untyped physical distances in BreakClusterUse point lengths in LatinSpacingReject untyped physical distances in LatinSpacingUse point lengths in JustificationPolicyReject untyped physical distances in JustificationPolicyUse point lengths in LineGeometryReject untyped physical distances in LineGeometryUse point lengths in PlanLineReject untyped physical distances in PlanLinePass typed distances to the line-cost functionReject raw distances at the line-cost boundary

    Diagnostics TPZ5001

    Source evidence

    Use point lengths in Box

    Link

    check · checking · Verification: not-run

    main.tpzUse point lengths in BoxOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.Box = ts.Box {
    3. unitIndex: 0,
    4. text: "A",
    5. width: 12pt,
    6. trackingAfter: 0pt
    7. }
    8. let distance: Length<Pt> = value.width
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject untyped physical distances in Box

    Link

    reject · checking · Verification: not-run

    main.tpzReject untyped physical distances in BoxOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.Box = ts.Box {
    3. unitIndex: 0,
    4. text: "A",
    5. width: 12,
    6. trackingAfter: 0
    7. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 stdlib-physical-distance-requires-points at main.tpz:5:10

    No stdout.

    This exact example has not been executed.

    Source evidence

    Use point lengths in Glue

    Link

    check · checking · Verification: not-run

    main.tpzUse point lengths in GlueOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.Glue = ts.Glue {
    3. unitIndex: 1,
    4. text: " ",
    5. width: 3pt,
    6. trackingAfter: 0pt,
    7. stretch: 1pt,
    8. shrink: 1pt
    9. }
    10. let distance: Length<Pt> = value.width
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject untyped physical distances in Glue

    Link

    reject · checking · Verification: not-run

    main.tpzReject untyped physical distances in GlueOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.Glue = ts.Glue {
    3. unitIndex: 1,
    4. text: " ",
    5. width: 3,
    6. trackingAfter: 0,
    7. stretch: 1,
    8. shrink: 1
    9. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 stdlib-physical-distance-requires-points at main.tpz:5:10

    No stdout.

    This exact example has not been executed.

    Source evidence

    Use point lengths in Penalty

    Link

    check · checking · Verification: not-run

    main.tpzUse point lengths in PenaltyOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.Penalty = ts.Penalty {
    3. unitEnd: 1,
    4. width: 0pt,
    5. rule: ts.BreakRule.Forced(),
    6. kind: ts.BreakKind.ForcedEnd(),
    7. flagged: false
    8. }
    9. let distance: Length<Pt> = value.width
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject untyped physical distances in Penalty

    Link

    reject · checking · Verification: not-run

    main.tpzReject untyped physical distances in PenaltyOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.Penalty = ts.Penalty {
    3. unitEnd: 1,
    4. width: 0,
    5. rule: ts.BreakRule.Forced(),
    6. kind: ts.BreakKind.ForcedEnd(),
    7. flagged: false
    8. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 stdlib-physical-distance-requires-points at main.tpz:4:10

    No stdout.

    This exact example has not been executed.

    Source evidence

    Use point lengths in BreakPolicy

    Link

    check · checking · Verification: not-run

    main.tpzUse point lengths in BreakPolicyOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.BreakPolicy = ts.BreakPolicy {
    3. mode: ts.BreakMode.Character(),
    4. rules: ts.KinsokuRules.Unicode16Ja(),
    5. forbidBefore: [],
    6. forbidAfter: [],
    7. boundaryAllowed: [true],
    8. generatedHyphenEnds: [],
    9. protectFittingLatin: true,
    10. preserveShortWords: true,
    11. narrowestWordTarget: 12pt,
    12. bodyWordTarget: 24pt
    13. }
    14. let distance: Length<Pt> = value.narrowestWordTarget
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject untyped physical distances in BreakPolicy

    Link

    reject · checking · Verification: not-run

    main.tpzReject untyped physical distances in BreakPolicyOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.BreakPolicy = ts.BreakPolicy {
    3. mode: ts.BreakMode.Character(),
    4. rules: ts.KinsokuRules.Unicode16Ja(),
    5. forbidBefore: [],
    6. forbidAfter: [],
    7. boundaryAllowed: [true],
    8. generatedHyphenEnds: [],
    9. protectFittingLatin: true,
    10. preserveShortWords: true,
    11. narrowestWordTarget: 12,
    12. bodyWordTarget: 24
    13. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 stdlib-physical-distance-requires-points at main.tpz:11:24

    No stdout.

    This exact example has not been executed.

    Source evidence

    Use point lengths in BreakCluster

    Link

    check · checking · Verification: not-run

    main.tpzUse point lengths in BreakClusterOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.BreakCluster = ts.BreakCluster {
    3. text: "A",
    4. advance: 12pt,
    5. trackingAfter: 0pt
    6. }
    7. let distance: Length<Pt> = value.advance
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject untyped physical distances in BreakCluster

    Link

    reject · checking · Verification: not-run

    main.tpzReject untyped physical distances in BreakClusterOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.BreakCluster = ts.BreakCluster {
    3. text: "A",
    4. advance: 12,
    5. trackingAfter: 0
    6. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 stdlib-physical-distance-requires-points at main.tpz:4:12

    No stdout.

    This exact example has not been executed.

    Source evidence

    Use point lengths in LatinSpacing

    Link

    check · checking · Verification: not-run

    main.tpzUse point lengths in LatinSpacingOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.LatinSpacing = ts.LatinSpacing {
    3. minWordSpaceRatio: 0.8,
    4. maxWordSpaceRatio: 1.33,
    5. maxLetterSpacingEm: 0.01em,
    6. fontSizePt: 12pt
    7. }
    8. let distance: Length<Pt> = value.fontSizePt
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject untyped physical distances in LatinSpacing

    Link

    reject · checking · Verification: not-run

    main.tpzReject untyped physical distances in LatinSpacingOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.LatinSpacing = ts.LatinSpacing {
    3. minWordSpaceRatio: 0.8,
    4. maxWordSpaceRatio: 1.33,
    5. maxLetterSpacingEm: 0.01em,
    6. fontSizePt: 12.0
    7. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 stdlib-physical-distance-requires-points at main.tpz:6:15

    No stdout.

    This exact example has not been executed.

    Source evidence

    Use point lengths in JustificationPolicy

    Link

    check · checking · Verification: not-run

    main.tpzUse point lengths in JustificationPolicyOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.JustificationPolicy = ts.JustificationPolicy {
    3. mode: ts.JustificationMode.Unjustified(),
    4. minGapCount: 0,
    5. minLineWidthRatioM: 0,
    6. minFinalLineWidthRatioM: None(),
    7. maxAdjustment: 12pt,
    8. maxGapAdjustment: 3pt,
    9. maxGapRatioR: 0,
    10. latinSpacing: None(),
    11. cjkStretchRatio: 0.0
    12. }
    13. let distance: Length<Pt> = value.maxAdjustment
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject untyped physical distances in JustificationPolicy

    Link

    reject · checking · Verification: not-run

    main.tpzReject untyped physical distances in JustificationPolicyOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.JustificationPolicy = ts.JustificationPolicy {
    3. mode: ts.JustificationMode.Unjustified(),
    4. minGapCount: 0,
    5. minLineWidthRatioM: 0,
    6. minFinalLineWidthRatioM: None(),
    7. maxAdjustment: 12,
    8. maxGapAdjustment: 3,
    9. maxGapRatioR: 0,
    10. latinSpacing: None(),
    11. cjkStretchRatio: 0.0
    12. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 stdlib-physical-distance-requires-points at main.tpz:7:18

    No stdout.

    This exact example has not been executed.

    Source evidence

    Use point lengths in LineGeometry

    Link

    check · checking · Verification: not-run

    main.tpzUse point lengths in LineGeometryOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.LineGeometry = ts.LineGeometry {
    3. bodyTarget: 24pt,
    4. firstTarget: 20pt,
    5. dropCapSpan: 0,
    6. dropCapInset: 0pt
    7. }
    8. let distance: Length<Pt> = value.bodyTarget
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject untyped physical distances in LineGeometry

    Link

    reject · checking · Verification: not-run

    main.tpzReject untyped physical distances in LineGeometryOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.LineGeometry = ts.LineGeometry {
    3. bodyTarget: 24,
    4. firstTarget: 20,
    5. dropCapSpan: 0,
    6. dropCapInset: 0
    7. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 stdlib-physical-distance-requires-points at main.tpz:3:15

    No stdout.

    This exact example has not been executed.

    Source evidence

    Use point lengths in PlanLine

    Link

    check · checking · Verification: not-run

    main.tpzUse point lengths in PlanLineOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.PlanLine = ts.PlanLine {
    3. start: 0,
    4. endExclusive: 1,
    5. trimmedEndExclusive: 1,
    6. displayTextScalarLength: 1,
    7. kind: ts.BreakKind.ForcedEnd(),
    8. target: 12pt,
    9. rawTextWidth: 10pt,
    10. trimmedTextWidth: 10pt,
    11. costTextWidth: 10pt,
    12. selectedPenaltyWidth: 0pt,
    13. postValidationWidthLimit: Some(13pt),
    14. cost: 0,
    15. adjustmentRatioR: 0
    16. }
    17. let distance: Length<Pt> = value.target
    18. let limit: Option<Length<Pt>> = value.postValidationWidthLimit
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject untyped physical distances in PlanLine

    Link

    reject · checking · Verification: not-run

    main.tpzReject untyped physical distances in PlanLineOpen in Playground
    1. import std.typeset as ts
    2. let value: ts.PlanLine = ts.PlanLine {
    3. start: 0,
    4. endExclusive: 1,
    5. trimmedEndExclusive: 1,
    6. displayTextScalarLength: 1,
    7. kind: ts.BreakKind.ForcedEnd(),
    8. target: 12,
    9. rawTextWidth: 10,
    10. trimmedTextWidth: 10,
    11. costTextWidth: 10,
    12. selectedPenaltyWidth: 0,
    13. postValidationWidthLimit: Some(13),
    14. cost: 0,
    15. adjustmentRatioR: 0
    16. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 stdlib-physical-distance-requires-points at main.tpz:8:11

    No stdout.

    This exact example has not been executed.

    Source evidence

    Pass typed distances to the line-cost function

    Link

    check · checking · Verification: not-run

    main.tpzPass typed distances to the line-cost functionOpen in Playground
    1. import std.typeset as ts
    2. let value = ts.lineBadness(20pt, 20pt, 4, 1, ts.BreakKind.ForcedEnd(), false, 0, 0pt)
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject raw distances at the line-cost boundary

    Link

    reject · checking · Verification: not-run

    main.tpzReject raw distances at the line-cost boundaryOpen in Playground
    1. import std.typeset as ts
    2. let value = ts.lineBadness(20, 20, 4, 1, ts.BreakKind.ForcedEnd(), false, 0, 0)
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5001 stdlib-physical-distance-requires-points at main.tpz:2:28

    No stdout.

    This exact example has not been executed.

    Source evidence

    Diagnostics

    Link

    TPZ5001

    Apply penalties at measured unit boundaries

    Link
    Ruletopaz.stdlib.contract.typeset-penalties.rule

    Apply penalties at measured unit boundaries

    Penalty.unitEnd is the exclusive end of a measured unit span. It must be greater than zero and no greater than the paragraph unit count. The penalty's position in the Item array does not set that boundary.

    Planning collects penalties and visits them in increasing unitEnd order. Equal endpoints retain input order. Duplicate endpoints remain separate candidates and are counted separately in breakOpportunityCount.

    Penalty.rule determines whether a candidate is selectable and how its additional cost is interpreted. Forbidden removes that candidate. A selectable duplicate at the same endpoint remains available. A Forced entry prevents any line from crossing that boundary.

    Penalty.kind describes the selected boundary independently of its rule. For example a Forced rule can carry a LatinHyphen kind. The chosen line reports the selected candidate's kind.

    Penalty.width is a nonnegative Length<Pt> that contributes when that candidate ends a line. Both cost models include this width for every kind. Unselected candidates contribute no width.

    PlanLine.selectedPenaltyWidth reports that selected width separately from the measured text widths. Input penalty widths are validated even for Forbidden candidates.

    Penalty.flagged marks a break for KnuthPlassPolicy.flaggedDemerit and finalFlaggedDemerit. FixedPoint does not use this flag. Its consecutive soft hyphen rule depends on kind.

    An out-of-range unitEnd or negative penalty width returns InvalidInput from breakParagraph. Record and Item construction preserve the supplied data until that call validates it.

    A complete plan needs a selectable terminal candidate at the unit count. Paragraph planning does not synthesize a terminal penalty or invoke break classification on the measured items.

    Why

    A boundary candidate separates admissibility, category, visible width, and cost history. The same selected width has one meaning in either cost model. Keeping duplicate candidates distinct permits explicit alternatives without changing source unit indices.

    Examples Include a selected nonsoft penalty width with fixed costsInclude a selected nonsoft penalty width with knuth costsReject boundaries outside the measured unitsReject a negative boundary width

    Source evidence

    Include a selected nonsoft penalty width with fixed costs

    Link

    run · running · Verification: not-run

    main.tpzInclude a selected nonsoft penalty width with fixed costsOpen in Playground
    1. import std.typeset as ts
    2. import std.io
    4. let items: Array<ts.Item> = [
    5. ts.Item.BoxItem(ts.Box { unitIndex: 0, text: "a", width: 4pt, trackingAfter: 0pt }),
    6. ts.Item.PenaltyItem(ts.Penalty { unitEnd: 1, width: 1pt, rule: ts.BreakRule.Forced(), kind: ts.BreakKind.LatinHyphen(), flagged: false })
    7. ]
    8. let input = ts.Paragraph {
    9. grid: ts.DistanceGrid.MilliPoint(),
    10. items: items,
    11. geometry: ts.LineGeometry { bodyTarget: 5pt, firstTarget: 5pt, dropCapSpan: 0, dropCapInset: 0pt },
    12. justification: ts.JustificationPolicy {
    13. mode: ts.JustificationMode.Unjustified(), minGapCount: 0,
    14. minLineWidthRatioM: 0, minFinalLineWidthRatioM: None(),
    15. maxAdjustment: 0pt, maxGapAdjustment: 0pt, maxGapRatioR: 0,
    16. latinSpacing: None(), cjkStretchRatio: 0.0
    17. },
    18. costModel: ts.CostModel.FixedPoint(),
    19. knuthPlass: ts.KnuthPlassPolicy { toleranceR: 100000000, linePenalty: 10, fitnessDemerit: 0, flaggedDemerit: 0, finalFlaggedDemerit: 0 }
    20. }
    21. match (ts.breakParagraph(input)) {
    22. case Ok(result) => {
    23. let line = result.optimized.lines[0]
    24. io.writeLine("{line.selectedPenaltyWidth == 1pt}:{line.costTextWidth == 4pt}:{line.cost}")
    25. }
    26. case Err(_) => io.writeLine("unexpected error")
    27. }
    Expected outputexit 0
    true:true:350000000
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true:true:350000000

    This exact example has not been executed.

    Source evidence

    Include a selected nonsoft penalty width with knuth costs

    Link

    run · running · Verification: not-run

    main.tpzInclude a selected nonsoft penalty width with knuth costsOpen in Playground
    1. import std.typeset as ts
    2. import std.io
    4. let items: Array<ts.Item> = [
    5. ts.Item.BoxItem(ts.Box { unitIndex: 0, text: "a", width: 4pt, trackingAfter: 0pt }),
    6. ts.Item.PenaltyItem(ts.Penalty { unitEnd: 1, width: 1pt, rule: ts.BreakRule.Forced(), kind: ts.BreakKind.LatinHyphen(), flagged: false })
    7. ]
    8. let input = ts.Paragraph {
    9. grid: ts.DistanceGrid.MilliPoint(),
    10. items: items,
    11. geometry: ts.LineGeometry { bodyTarget: 5pt, firstTarget: 5pt, dropCapSpan: 0, dropCapInset: 0pt },
    12. justification: ts.JustificationPolicy {
    13. mode: ts.JustificationMode.Unjustified(), minGapCount: 0,
    14. minLineWidthRatioM: 0, minFinalLineWidthRatioM: None(),
    15. maxAdjustment: 0pt, maxGapAdjustment: 0pt, maxGapRatioR: 0,
    16. latinSpacing: None(), cjkStretchRatio: 0.0
    17. },
    18. costModel: ts.CostModel.KnuthPlass(),
    19. knuthPlass: ts.KnuthPlassPolicy { toleranceR: 100000000, linePenalty: 10, fitnessDemerit: 0, flaggedDemerit: 0, finalFlaggedDemerit: 0 }
    20. }
    21. match (ts.breakParagraph(input)) {
    22. case Ok(result) => {
    23. let line = result.optimized.lines[0]
    24. io.writeLine("{line.selectedPenaltyWidth == 1pt}:{line.costTextWidth == 4pt}:{line.cost}")
    25. }
    26. case Err(_) => io.writeLine("unexpected error")
    27. }
    Expected outputexit 0
    true:true:100
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true:true:100

    This exact example has not been executed.

    Source evidence

    Reject boundaries outside the measured units

    Link

    run · running · Verification: not-run

    main.tpzReject boundaries outside the measured unitsOpen in Playground
    1. import std.typeset as ts
    2. import std.io
    4. function report(items: Array<ts.Item>) -> () {
    5. let input = ts.Paragraph {
    6. grid: ts.DistanceGrid.MilliPoint(),
    7. items: items,
    8. geometry: ts.LineGeometry { bodyTarget: 10pt, firstTarget: 10pt, dropCapSpan: 0, dropCapInset: 0pt },
    9. justification: ts.JustificationPolicy {
    10. mode: ts.JustificationMode.Unjustified(), minGapCount: 0,
    11. minLineWidthRatioM: 0, minFinalLineWidthRatioM: None(),
    12. maxAdjustment: 0pt, maxGapAdjustment: 0pt, maxGapRatioR: 0,
    13. latinSpacing: None(), cjkStretchRatio: 0.0
    14. },
    15. costModel: ts.CostModel.FixedPoint(),
    16. knuthPlass: ts.KnuthPlassPolicy { toleranceR: 100000000, linePenalty: 10, fitnessDemerit: 0, flaggedDemerit: 0, finalFlaggedDemerit: 0 }
    17. }
    18. match (ts.breakParagraph(input)) {
    19. case Err(InvalidInput(_)) => io.writeLine("InvalidInput")
    20. case _ => io.writeLine("unexpected result")
    21. }
    22. }
    24. report([ts.Item.BoxItem(ts.Box { unitIndex: 0, text: "a", width: 1pt, trackingAfter: 0pt }), ts.Item.PenaltyItem(ts.Penalty { unitEnd: 0, width: 0pt, rule: ts.BreakRule.Forced(), kind: ts.BreakKind.ForcedEnd(), flagged: false })])
    25. report([ts.Item.BoxItem(ts.Box { unitIndex: 0, text: "a", width: 1pt, trackingAfter: 0pt }), ts.Item.PenaltyItem(ts.Penalty { unitEnd: 2, width: 0pt, rule: ts.BreakRule.Forced(), kind: ts.BreakKind.ForcedEnd(), flagged: false })])
    Expected outputexit 0
    InvalidInput
InvalidInput
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. InvalidInput
    2. InvalidInput

    This exact example has not been executed.

    Source evidence

    Reject a negative boundary width

    Link

    run · running · Verification: not-run

    main.tpzReject a negative boundary widthOpen in Playground
    1. import std.typeset as ts
    2. import std.io
    4. let items: Array<ts.Item> = [
    5. ts.Item.BoxItem(ts.Box { unitIndex: 0, text: "a", width: 1pt, trackingAfter: 0pt }),
    6. ts.Item.PenaltyItem(ts.Penalty { unitEnd: 1, width: -1pt, rule: ts.BreakRule.Forced(), kind: ts.BreakKind.ForcedEnd(), flagged: false })
    7. ]
    8. let input = ts.Paragraph {
    9. grid: ts.DistanceGrid.MilliPoint(),
    10. items: items,
    11. geometry: ts.LineGeometry { bodyTarget: 10pt, firstTarget: 10pt, dropCapSpan: 0, dropCapInset: 0pt },
    12. justification: ts.JustificationPolicy {
    13. mode: ts.JustificationMode.Unjustified(), minGapCount: 0,
    14. minLineWidthRatioM: 0, minFinalLineWidthRatioM: None(),
    15. maxAdjustment: 0pt, maxGapAdjustment: 0pt, maxGapRatioR: 0,
    16. latinSpacing: None(), cjkStretchRatio: 0.0
    17. },
    18. costModel: ts.CostModel.FixedPoint(),
    19. knuthPlass: ts.KnuthPlassPolicy { toleranceR: 100000000, linePenalty: 10, fitnessDemerit: 0, flaggedDemerit: 0, finalFlaggedDemerit: 0 }
    20. }
    21. match (ts.breakParagraph(input)) {
    22. case Err(InvalidInput(_)) => io.writeLine("InvalidInput")
    23. case _ => io.writeLine("unexpected result")
    24. }
    Expected outputexit 0
    InvalidInput
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. InvalidInput

    This exact example has not been executed.

    Source evidence

    Menu

    Download