PDF::Builder::Util(3)

💖 PDF::Builder::Util 💖

okay bestie, gather round, because this is PDF::Builder::Util — the utility package that's out here doing the most for the whole PDF::Builder family. It's giving "group chat of helper methods", and honestly? It carries. This page lives in the User Contributed Perl Documentation section, and you're gonna want to bookmark it, fr fr.

---

✨ NAME ✨

PDF::Builder::Util — the utility package for often-used methods across the package. It's the friend who always has a charger, a snack, and a conversion table. 🫶

---

🌈 PREDEFINED COLORS 🌈

See the source of PDF::Builder::Resource::Colors for a complete list. That's where the full roster lives, go peek.

Please Note: this is an amalgamation of the X11, SGML and (X)HTML specification sets. So it's a whole crossover episode. 👑

There are many color model conversion and input conversion routines defined here. Many. Like, a lot a lot.

---

🦋 STREAM FILTERS 🦋

There are a number of functions here to handle stream filtering. Streams, filtered. Iconic behavior.

---

🎀 PREDEFINED GLYPH-NAMES 🎀

See the file uniglyph.txt for a complete list. Yes, it's a whole file. She's thorough.

Please Note: you may notice that apart from the 'AGL/WGL4', names from the XML, (X)HTML and SGML specification sets have been included to enable interoperability towards PDF. iykyk — it's all about playing nice with PDF. 💅

There are a number of functions here to handle various aspects of glyph identification.

---

📏 PREDEFINED PAPER SIZES 📏

Dimensions are in points. Periodt.

paper_size

@box_corners = paper_size($x1,$y1, $x2,$y2);

Returns an array ($x1,$y1, $x2,$y2) (full bounding box). The whole rectangle, bestie.

@box_corners = paper_size($x1,$y1);

Returns an array (0,0, $x1,$y1) (half bounding box). Half the vibe, same energy.

@box_corners = paper_size($media_name);

Returns an array (0,0, paper_width,paper_height) for the named media. Just hand her a name and she delivers. ✨

@box_corners = paper_size($x1);

Returns an array (0,0, $x1,$x1) (single quadratic). Square. Balanced. Main character.

Otherwise, array (0,0, 612,792) (US Letter dimensions) is returned. That's the fallback fit, no cap.

getPaperSizes

%sizes = getPaperSizes();

Returns a hash containing the available paper size aliases as keys and their dimensions as a two-element array reference.

See the source of PDF::Builder::Resource::PaperSizes for the complete list. Go look, she's not gatekeeping.

---

📐 STRING TO DIMENSION 📐

Convert a string "number [unit]" to the value in desired units. Units are case-insensitive (the input is first folded to lower case). Lowercase gang rise up. 🔥

Supported units: mm, cm, in (inch), pt (Big point, 72/inch), ppt (printer's point, 72.27/inch), pc (pica, 6/inch), dd (Didot point, 67.5532/inch), and cc (Ciceros, 5.62943/inch). More can be added easily.

Invalid units are a fatal error. Like, do not test her. 🚨

str2dim

$value = str2dim($string, $type, $default_units);

$string contains a number and optionally, a unit. Space(s) between the number and the unit are optional. E.g., '200', '35.2 mm', and '1.5in' are all allowable input strings. So casual, so flexible. 💖

$type is for validation of the input $string's numeric value. The first character is i for an integer is required (no decimal point), or f for other (floating point) numbers. Next is an optional c to indicate that an out-of-range input value is to be silently clamped to be within the given range (the default is to raise a fatal error). Finally, an optional range expression: {lower limit,upper limit}. The limits are either numbers or * (to indicate +/- infinity (no limit) on that end of the range). { is [ to say that the lower limit is included in the range, while ( says that the lower limit is excluded from the range. Likewise, } is ] for included upper limit, and ) for excluded. The limits (and silent clamping, or fatal error if the input is out of range) are against the input value, before conversion to the output units. Read that last part again, bestie, it matters. 👀

Example types:

• 'f(*,*)' — no limits (the default) — all values OK. Live your truth.
• 'i(0,*)' — integer greater than 0
• 'fc[-3.2,7.86]' — a number between -3.2 and 7.86, with value clamped to be within that range (including the endpoints)

$default_units is a required string, giving the units that the input is converted to. For example, if the default units are 'pt', and the input string '2 in', the output value would be '144'. If the input string has no explicit units, it is assumed to be in the default units (no conversion is done). No math, no stress. 🧚

---

and that's the whole page, bestie!! this one came from perl v5.42.0, dated 2026-01-17, and it's the PDF::Builder::Util(3) page, so now you know exactly where it came from. go forth and convert units responsibly, mwah 💅✨🌸