.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PDF::Builder::Util 3pm"
.TH PDF::Builder::Util 3pm "2021-03-28" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDF::Builder::Util \- utility package for often\-used methods across the package.
.SS "\s-1PREDEFINED COLORS\s0"
.IX Subsection "PREDEFINED COLORS"
See the source of PDF::Builder::Resource::Colors for a complete list.
.PP
\&\fBPlease Note:\fR This is an amalgamation of the X11, \s-1SGML\s0 and (X)HTML
specification sets.
.PP
There are many color model conversion and input conversion routines 
defined here.
.SS "\s-1STREAM FILTERS\s0"
.IX Subsection "STREAM FILTERS"
There are a number of functions here to handle stream filtering.
.SS "\s-1PREDEFINED\s0 GLYPH-NAMES"
.IX Subsection "PREDEFINED GLYPH-NAMES"
See the file \f(CW\*(C`uniglyph.txt\*(C'\fR for a complete list.
.PP
\&\fBPlease Note:\fR You may notice that apart from the '\s-1AGL/WGL4\s0', names
from the \s-1XML,\s0 (X)HTML and \s-1SGML\s0 specification sets have been included
to enable interoperability towards \s-1PDF.\s0
.PP
There are a number of functions here to handle various
aspects of glyph identification.
.SS "\s-1PREDEFINED PAPER SIZES\s0"
.IX Subsection "PREDEFINED PAPER SIZES"
Dimensions are in points.
.ie n .IP "@box_corners = paper_size($x1,$y1, $x2,$y2);" 4
.el .IP "\f(CW@box_corners\fR = paper_size($x1,$y1, \f(CW$x2\fR,$y2);" 4
.IX Item "@box_corners = paper_size($x1,$y1, $x2,$y2);"
Returns an array ($x1,$y1, \f(CW$x2\fR,$y2) (full bounding box).
.ie n .IP "@box_corners = paper_size($x1,$y1);" 4
.el .IP "\f(CW@box_corners\fR = paper_size($x1,$y1);" 4
.IX Item "@box_corners = paper_size($x1,$y1);"
Returns an array (0,0, \f(CW$x1\fR,$y1) (half bounding box).
.ie n .IP "@box_corners = paper_size($media_name);" 4
.el .IP "\f(CW@box_corners\fR = paper_size($media_name);" 4
.IX Item "@box_corners = paper_size($media_name);"
Returns an array (0,0, paper_width,paper_height) for the named media.
.ie n .IP "@box_corners = paper_size($x1);" 4
.el .IP "\f(CW@box_corners\fR = paper_size($x1);" 4
.IX Item "@box_corners = paper_size($x1);"
Returns an array (0,0, \f(CW$x1\fR,$x1) (single quadratic).
.Sp
Otherwise, array (0,0, 612,792) (\s-1US\s0 Letter dimensions) is returned.
.ie n .IP "%sizes = \fBgetPaperSizes()\fR;" 4
.el .IP "\f(CW%sizes\fR = \fBgetPaperSizes()\fR;" 4
.IX Item "%sizes = getPaperSizes();"
Returns a hash containing the available paper size aliases as keys and
their dimensions as a two-element array reference.
.Sp
See the source of PDF::Builder::Resource::PaperSizes for the complete list.
.SS "\s-1STRING TO DIMENSION\s0"
.IX Subsection "STRING TO DIMENSION"
Convert a string \*(L"number [unit]\*(R" to the value in desired units. Units are
case-insensitive (the input is first folded to lower case).
.PP
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.
.ie n .IP "$value = str2dim($string, $type, $default_units);" 4
.el .IP "\f(CW$value\fR = str2dim($string, \f(CW$type\fR, \f(CW$default_units\fR);" 4
.IX Item "$value = str2dim($string, $type, $default_units);"
\&\f(CW$string\fR 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.
.Sp
\&\f(CW$type\fR is for validation of the input \f(CW$string\fR's numeric value. The first 
character is \fBi\fR for an \fIinteger\fR is required (no decimal point), or \fBf\fR for
other (floating point) numbers. Next is an optional \fBc\fR to indicate that an
out-of-range input value is to be silently \fIclamped\fR to be within the given 
range (the default is to raise a fatal error). Finally, an optional \fIrange\fR
expression: {lower limit,upper limit}. The limits are either numbers or \fB*\fR (to
indicate +/\- infinity (no limit) on that end of the range). \fB{\fR is \fB[\fR to say 
that the lower limit is \fIincluded\fR in the range, while \fB(\fR says that the 
lower limit is \fIexcluded\fR from the range. Likewise, \fB}\fR is \fB]\fR for 
\&\fIincluded\fR upper limit, and \fB)\fR for \fIexcluded\fR. 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.
.Sp
Example types:
.RS 4
.ie n .IP "\*(Aqf(*,*)\*(Aq  no limits (the default) \*(-- all values \s-1OK\s0" 4
.el .IP "\f(CW\*(Aqf(*,*)\*(Aq\fR  no limits (the default) \*(-- all values \s-1OK\s0" 4
.IX Item "f(*,*) no limits (the default) all values OK"
.PD 0
.ie n .IP "\*(Aqi(0,*)\*(Aq  integer greater than 0" 4
.el .IP "\f(CW\*(Aqi(0,*)\*(Aq\fR  integer greater than 0" 4
.IX Item "i(0,*) integer greater than 0"
.ie n .IP "\*(Aqfc[\-3.2,7.86]\*(Aq  a number between \-3.2 and 7.86, with value clamped to be within that range (including the endpoints)" 4
.el .IP "\f(CW\*(Aqfc[\-3.2,7.86]\*(Aq\fR  a number between \-3.2 and 7.86, with value clamped to be within that range (including the endpoints)" 4
.IX Item "fc[-3.2,7.86] a number between -3.2 and 7.86, with value clamped to be within that range (including the endpoints)"
.RE
.RS 4
.PD
.Sp
\&\f(CW$default_units\fR 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).
.RE