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

    Box.text

    The exact display text of this measured box.

    Box.text: string
    Receiver
    Box
    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

    Box

    Parameter constraints

    Additional contracts are Pending.

    Item.BoxItem, Item.GlueItem, and Item.PenaltyItem preserve their record payloads. Constructing these records and variants does not plan a paragraph or validate its measurements.

    BoxItem and GlueItem contribute one measured unit each in their encounter order. Their unitIndex fields must be exactly zero through the unit count minus one. PenaltyItem contributes a boundary without consuming a unit index.

    Box.text and Glue.text retain the supplied string, including empty text and multiple Unicode scalars. A measured unit remains indivisible. Unit indices count these records rather than bytes, scalars, or grapheme clusters.

    Box.width and Glue.width include trackingAfter. Width and width minus trackingAfter must both be nonnegative. Tracking may be positive, zero, or negative while those two conditions hold.

    Each width, tracking amount, stretch, and shrink is a Length<Pt>. Paragraph planning quantizes it through the selected grid. A line span sums its unit widths and removes the final unit's trackingAfter.

    Glue.stretch and Glue.shrink are nonnegative adjustment capacities. A box supplies zero capacity. The selected cost and justification policies determine how capacities participate in planning.

    Positive capacity does not itself insert text or change the input records. Unjustified planning performs no distributed adjustment. Text trimming and model-specific glue treatment follow the PlanLine and paragraph contracts.

    breakParagraph returns InvalidInput for a noncontiguous unitIndex, a negative width or capacity, or a negative width before tracking. Validation applies even when a later candidate would discard that unit.

    The function uses the supplied measurements without shaping the text again. It does not reorder or mutate the caller's item array or its records.

    Related rule: Preserve measured units and validate their physical extents

    Result

    Additional contracts are Pending.

    The declared result type is string.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

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

    May contain zero, one, or several Unicode scalars. Line breaking preserves the box as one measured unit.

    Why

    Link

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

    Resolved contracts

    Link

    Related entries

    Link

    std.typeset

    Preserve measured units and validate their physical extents

    Link
    Ruletopaz.stdlib.contract.typeset-measured-items.rule

    Preserve measured units and validate their physical extents

    Item.BoxItem, Item.GlueItem, and Item.PenaltyItem preserve their record payloads. Constructing these records and variants does not plan a paragraph or validate its measurements.

    BoxItem and GlueItem contribute one measured unit each in their encounter order. Their unitIndex fields must be exactly zero through the unit count minus one. PenaltyItem contributes a boundary without consuming a unit index.

    Box.text and Glue.text retain the supplied string, including empty text and multiple Unicode scalars. A measured unit remains indivisible. Unit indices count these records rather than bytes, scalars, or grapheme clusters.

    Box.width and Glue.width include trackingAfter. Width and width minus trackingAfter must both be nonnegative. Tracking may be positive, zero, or negative while those two conditions hold.

    Each width, tracking amount, stretch, and shrink is a Length<Pt>. Paragraph planning quantizes it through the selected grid. A line span sums its unit widths and removes the final unit's trackingAfter.

    Glue.stretch and Glue.shrink are nonnegative adjustment capacities. A box supplies zero capacity. The selected cost and justification policies determine how capacities participate in planning.

    Positive capacity does not itself insert text or change the input records. Unjustified planning performs no distributed adjustment. Text trimming and model-specific glue treatment follow the PlanLine and paragraph contracts.

    breakParagraph returns InvalidInput for a noncontiguous unitIndex, a negative width or capacity, or a negative width before tracking. Validation applies even when a later candidate would discard that unit.

    The function uses the supplied measurements without shaping the text again. It does not reorder or mutate the caller's item array or its records.

    Why

    Measured text already has a source order and physical advances. Preserving those units keeps line breaking compatible with shaping. Explicit tracking and capacities give every planner the same measured input.

    Examples Keep measured units and signed tracking in source orderKeep a zero width unit with empty display textReject a gap in measured unit indicesReject negative glue stretch and shrinkReject negative widths and negative extents before tracking

    Source evidence

    Keep measured units and signed tracking in source order

    Link

    run · running · Verification: not-run

    main.tpzKeep measured units and signed tracking in source orderOpen in Playground
    1. import std.typeset as ts
    2. import std.io
    4. let items: Array<ts.Item> = [
    5. ts.Item.PenaltyItem(ts.Penalty { unitEnd: 3, width: 0pt, rule: ts.BreakRule.Forced(), kind: ts.BreakKind.ForcedEnd(), flagged: false }),
    6. ts.Item.BoxItem(ts.Box { unitIndex: 0, text: "AB", width: 3pt, trackingAfter: 1pt }),
    7. ts.Item.GlueItem(ts.Glue { unitIndex: 1, text: " ", width: 2pt, trackingAfter: 0.5pt, stretch: 1pt, shrink: 1pt }),
    8. ts.Item.BoxItem(ts.Box { unitIndex: 2, text: "C", width: 4pt, trackingAfter: -1pt })
    9. ]
    10. let input = ts.Paragraph {
    11. grid: ts.DistanceGrid.MilliPoint(),
    12. items: items,
    13. geometry: ts.LineGeometry { bodyTarget: 10pt, firstTarget: 10pt, dropCapSpan: 0, dropCapInset: 0pt },
    14. justification: ts.JustificationPolicy {
    15. mode: ts.JustificationMode.Unjustified(), minGapCount: 0,
    16. minLineWidthRatioM: 0, minFinalLineWidthRatioM: None(),
    17. maxAdjustment: 0pt, maxGapAdjustment: 0pt, maxGapRatioR: 0,
    18. latinSpacing: None(), cjkStretchRatio: 0.0
    19. },
    20. costModel: ts.CostModel.FixedPoint(),
    21. knuthPlass: ts.KnuthPlassPolicy { toleranceR: 100000000, linePenalty: 10, fitnessDemerit: 0, flaggedDemerit: 0, finalFlaggedDemerit: 0 }
    22. }
    23. match (ts.breakParagraph(input)) {
    24. case Ok(result) => {
    25. let line = result.optimized.lines[0]
    26. io.writeLine("{line.start}:{line.endExclusive}:{line.displayTextScalarLength}")
    27. io.writeLine("{line.rawTextWidth == 10pt}:{line.trimmedTextWidth == 10pt}")
    28. io.writeLine("{items.length}")
    29. match (items[0]) {
    30. case PenaltyItem(_) => io.writeLine("penalty first")
    31. case _ => io.writeLine("changed input")
    32. }
    33. }
    34. case Err(_) => io.writeLine("unexpected error")
    35. }
    Expected outputexit 0
    0:3:4
true:true
4
penalty first
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 0:3:4
    2. true:true
    3. 4
    4. penalty first

    This exact example has not been executed.

    Source evidence

    Keep a zero width unit with empty display text

    Link

    run · running · Verification: not-run

    main.tpzKeep a zero width unit with empty display textOpen 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: "", width: 0pt, trackingAfter: 0pt }),
    6. ts.Item.PenaltyItem(ts.Penalty { unitEnd: 1, width: 0pt, 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: 1pt, firstTarget: 1pt, 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.endExclusive}:{line.displayTextScalarLength}:{line.rawTextWidth == 0pt}")
    25. }
    26. case Err(_) => io.writeLine("unexpected error")
    27. }
    Expected outputexit 0
    1:0:true
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 1:0:true

    This exact example has not been executed.

    Source evidence

    Reject a gap in measured unit indices

    Link

    run · running · Verification: not-run

    main.tpzReject a gap in measured unit indicesOpen 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: 1, text: "a", width: 1pt, trackingAfter: 0pt }),
    6. ts.Item.PenaltyItem(ts.Penalty { unitEnd: 1, width: 0pt, 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

    Reject negative glue stretch and shrink

    Link

    run · running · Verification: not-run

    main.tpzReject negative glue stretch and shrinkOpen 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.GlueItem(ts.Glue { unitIndex: 0, text: " ", width: 1pt, trackingAfter: 0pt, stretch: -1pt, shrink: 0pt }), ts.Item.PenaltyItem(ts.Penalty { unitEnd: 1, width: 0pt, rule: ts.BreakRule.Forced(), kind: ts.BreakKind.ForcedEnd(), flagged: false })])
    25. report([ts.Item.GlueItem(ts.Glue { unitIndex: 0, text: " ", width: 1pt, trackingAfter: 0pt, stretch: 0pt, shrink: -1pt }), ts.Item.PenaltyItem(ts.Penalty { unitEnd: 1, 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 negative widths and negative extents before tracking

    Link

    run · running · Verification: not-run

    main.tpzReject negative widths and negative extents before trackingOpen 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: 1, width: 0pt, rule: ts.BreakRule.Forced(), kind: ts.BreakKind.ForcedEnd(), flagged: false })])
    25. report([ts.Item.GlueItem(ts.Glue { unitIndex: 0, text: " ", width: -1pt, trackingAfter: 0pt, stretch: 0pt, shrink: 0pt }), ts.Item.PenaltyItem(ts.Penalty { unitEnd: 1, width: 0pt, rule: ts.BreakRule.Forced(), kind: ts.BreakKind.ForcedEnd(), flagged: false })])
    26. report([ts.Item.BoxItem(ts.Box { unitIndex: 0, text: "a", width: 1pt, trackingAfter: 2pt }), ts.Item.PenaltyItem(ts.Penalty { unitEnd: 1, width: 0pt, rule: ts.BreakRule.Forced(), kind: ts.BreakKind.ForcedEnd(), flagged: false })])
    27. report([ts.Item.GlueItem(ts.Glue { unitIndex: 0, text: " ", width: 1pt, trackingAfter: 2pt, stretch: 0pt, shrink: 0pt }), ts.Item.PenaltyItem(ts.Penalty { unitEnd: 1, width: 0pt, rule: ts.BreakRule.Forced(), kind: ts.BreakKind.ForcedEnd(), flagged: false })])
    Expected outputexit 0
    InvalidInput
InvalidInput
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
    3. InvalidInput
    4. InvalidInput

    This exact example has not been executed.

    Source evidence

    Menu

    Download