Struct LabelBuilder 

pub struct LabelBuilder { /* private fields */ }

Builder for ZPL II label strings.

Elements are added in order; the final ZPL string is produced by calling build. Every method that adds an element validates its arguments and returns a ZplError if any value is out of range.

Example

use zpl_builder::{LabelBuilder, BarcodeType, Color, Orientation};

let zpl = LabelBuilder::new()
    .set_home_position(10, 10).unwrap()
    .add_text("Hello, printer!", 50, 50, 'A', 30, Orientation::Normal).unwrap()
    .add_graphical_box(10, 10, 500, 300, 3, Color::Black, 0).unwrap()
    .add_barcode(BarcodeType::Code128, "ABC-123", 50, 120, 2, 2.5, 80, Orientation::Normal).unwrap()
    .build();

assert!(zpl.starts_with("^XA"));
assert!(zpl.ends_with("^XZ"));

Implementations

impl LabelBuilder

pub fn new() -> Self

Create a new, empty label builder.

The home position defaults to (0, 0). Call set_home_position to change it.

pub fn set_home_position( self, x_origin: u16, y_origin: u16, ) -> Result<Self, ZplError>

Set the label home position (^LH).

The home position is the axis reference point for the label. Any area below and to the right of this point is available for printing. It is recommended to call this before adding any elements.

Arguments

• x_origin — x-axis offset in dots. Range: 0–32000. Default: 0.
• y_origin — y-axis offset in dots. Range: 0–32000. Default: 0.

Errors

Returns ZplError::InvalidPosition if either value exceeds 32000.

Example

let zpl = LabelBuilder::new()
    .set_home_position(50, 10).unwrap()
    .build();

assert!(zpl.contains("^LH50,10"));

pub fn add_text( self, text: &str, x: u16, y: u16, font: char, font_size: u16, orientation: Orientation, ) -> Result<Self, ZplError>

Add a text field (^A / ^FD).

Arguments

• text — the string to print.
• x — x-axis position in dots. Range: 0–32000.
• y — y-axis position in dots. Range: 0–32000.
• font — ZPL font name: a single ASCII uppercase letter (A–Z) or a digit (1–9). The digit 0 (zero) is not valid.
• font_size — font height in dots. Range: 10–32000.
• orientation — field rotation. See Orientation.

Errors

Error	Condition
ZplError::InvalidPosition	x or y > 32000
ZplError::InvalidFont	font is not A–Z or 1–9
ZplError::InvalidFontSize	font_size < 10 or > 32000

Example

let zpl = LabelBuilder::new()
    .add_text("Hello", 10, 10, 'A', 30, Orientation::Normal).unwrap()
    .build();

assert!(zpl.contains("^FDHello^FS"));

pub fn add_barcode( self, _type: BarcodeType, data: &str, x: u16, y: u16, width: u8, width_ratio: f32, height: u16, orientation: Orientation, ) -> Result<Self, ZplError>

Add a barcode field (^BY / ^B*).

Arguments

• _type — barcode symbology. See BarcodeType.
• data — the string to encode.
• x — x-axis position in dots. Range: 0–32000.
• y — y-axis position in dots. Range: 0–32000.
• width — width of the narrowest bar in dots. Range: 1–10.
• width_ratio — wide bar to narrow bar ratio. Range: 2.0–3.0, step 0.1. Has no effect on fixed-ratio symbologies.
• height — barcode height in dots. Range: 1–32000.
• orientation — field rotation. See Orientation.

Errors

Error	Condition
ZplError::InvalidPosition	x or y > 32000
ZplError::InvalidBarcodeWidth	width < 1 or > 10
ZplError::InvalidWidthRatio	width_ratio outside 2.0–3.0
ZplError::InvalidBarcodeHeight	height < 1 or > 32000

Example

let zpl = LabelBuilder::new()
    .add_barcode(BarcodeType::Code128, "ABC-123", 10, 10, 2, 2.5, 80, Orientation::Normal).unwrap()
    .build();

assert!(zpl.contains("^FDABC-123^FS"));

pub fn add_graphical_box( self, x: u16, y: u16, width: u16, height: u16, thickness: u16, color: Color, rounding: u8, ) -> Result<Self, ZplError>

Add a graphical box (^GB).

Draws a rectangle outline. Setting width and height equal to thickness produces a filled square. Set rounding to 0 for sharp corners.

Arguments

• x — x-axis position in dots. Range: 0–32000.
• y — y-axis position in dots. Range: 0–32000.
• width — box width in dots. Must be ≥ thickness. Range: thickness–32000.
• height — box height in dots. Must be ≥ thickness. Range: thickness–32000.
• thickness — line thickness in dots. Range: 1–32000.
• color — line color. See Color.
• rounding — corner rounding amount. Range: 0–8 (0 = sharp, 8 = most rounded).

Errors

Error	Condition
ZplError::InvalidPosition	x or y > 32000
ZplError::InvalidThickness	thickness < 1 or > 32000
ZplError::InvalidBoxDimension	width or height < thickness or > 32000
ZplError::InvalidRounding	rounding > 8

Example

let zpl = LabelBuilder::new()
    .add_graphical_box(10, 10, 200, 100, 3, Color::Black, 0).unwrap()
    .build();

assert!(zpl.contains("^GB200,100,3,B,0"));

pub fn add_graphical_circle( self, x: u16, y: u16, diameter: u16, thickness: u16, color: Color, ) -> Result<Self, ZplError>

Add a graphical circle (^GC).

Arguments

• x — x-axis position in dots. Range: 0–32000.
• y — y-axis position in dots. Range: 0–32000.
• diameter — outer diameter in dots. Range: 3–4095.
• thickness — line thickness in dots. Range: 1–32000. Set equal to diameter to produce a filled circle.
• color — line color. See Color.

Errors

Error	Condition
ZplError::InvalidPosition	x or y > 32000
ZplError::InvalidThickness	thickness < 1 or > 32000
ZplError::InvalidGraphicDimension	diameter < 3 or > 4095

Example

let zpl = LabelBuilder::new()
    .add_graphical_circle(50, 50, 100, 3, Color::Black).unwrap()
    .build();

assert!(zpl.contains("^GC100,3,B"));

pub fn add_graphical_ellipse( self, x: u16, y: u16, width: u16, height: u16, thickness: u16, color: Color, ) -> Result<Self, ZplError>

Add a graphical ellipse (^GE).

Arguments

• x — x-axis position in dots. Range: 0–32000.
• y — y-axis position in dots. Range: 0–32000.
• width — ellipse width in dots. Range: 3–4095.
• height — ellipse height in dots. Range: 3–4095.
• thickness — line thickness in dots. Range: 1–32000.
• color — line color. See Color.

Errors

Error	Condition
ZplError::InvalidPosition	x or y > 32000
ZplError::InvalidThickness	thickness < 1 or > 32000
ZplError::InvalidGraphicDimension	width or height < 3 or > 4095

Example

let zpl = LabelBuilder::new()
    .add_graphical_ellipse(20, 20, 200, 100, 2, Color::Black).unwrap()
    .build();

assert!(zpl.contains("^GE200,100,2,B"));

pub fn add_graphical_diagonal_line( self, x: u16, y: u16, box_width: u16, box_height: u16, thickness: u16, color: Color, orientation: DiagonalOrientation, ) -> Result<Self, ZplError>

Add a diagonal line (^GD).

The line is drawn within a bounding box of size box_width × box_height. A square bounding box (box_width == box_height) produces a 45° angle.

Arguments

• x — x-axis position of the bounding box in dots. Range: 0–32000.
• y — y-axis position of the bounding box in dots. Range: 0–32000.
• box_width — width of the bounding box in dots. Must be ≥ thickness. Range: thickness–32000.
• box_height — height of the bounding box in dots. Must be ≥ thickness. Range: thickness–32000.
• thickness — line thickness in dots. Range: 1–32000.
• color — line color. See Color.
• orientation — direction of the line. See DiagonalOrientation.

Errors

Error	Condition
ZplError::InvalidPosition	x or y > 32000
ZplError::InvalidThickness	thickness < 1 or > 32000
ZplError::InvalidBoxDimension	box_width or box_height < thickness or > 32000

Example

let zpl = LabelBuilder::new()
    .add_graphical_diagonal_line(10, 10, 100, 100, 2, Color::Black, DiagonalOrientation::RightLeaning).unwrap()
    .build();

assert!(zpl.contains("^GD100,100,2,B,R"));

pub fn build(&self) -> String

Assemble and return the complete ZPL string.

The string starts with ^XA and ends with ^XZ. It can be sent directly to a Zebra printer over TCP, USB, or serial.

Example

let zpl = LabelBuilder::new().build();
assert_eq!(zpl, "^XA\n^LH0,0\n^XZ");

Trait Implementations

impl Debug for LabelBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for LabelBuilder

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for LabelBuilder

fn eq(&self, other: &LabelBuilder) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for LabelBuilder