---
name: "PDF::Builder::Util"
section: "3pm"
platform: "linux"
package: "perl-pdf-builder"
version: "3.028-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/PDF::Builder::Util"
---

# PDF::Builder::Util(3pm)

Utility package for often-used methods across the package

## NAME

PDF::Builder::Util - Utility package for often-used methods across the package

### PREDEFINED COLORS

See the source of PDF::Builder::Resource::Colors for a complete list.

**Please Note:** This is an amalgamation of the X11, SGML and (X)HTML specification sets.

There are many color model conversion and input conversion routines  defined here.

### STREAM FILTERS

There are a number of functions here to handle stream filtering.

### PREDEFINED GLYPH-NAMES

See the file `"uniglyph.txt"` for a complete list.

**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.

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

### PREDEFINED PAPER SIZES

Dimensions are in points.

*paper\_size*

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

Returns an array ($x1,$y1, `$x2`,$y2) (full bounding box).

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

Returns an array (0,0, `$x1`,$y1) (half bounding box).

```
    @box_corners = paper_size($media_name);
```

Returns an array (0,0, paper\_width,paper\_height) for the named media.

```
    @box_corners = paper_size($x1);
```

Returns an array (0,0, `$x1`,$x1) (single quadratic).

Otherwise, array (0,0, 612,792) (US Letter dimensions) is returned.

*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.

### 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).

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.

*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.

`$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.

Example types:

- 'f(\*,\*)' no limits (the default) -- all values OK

  - '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).