.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Tr 3"
.TH Tr 3 "2003-06-09" "perl v5.16.3" "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"
Regexp::Tr \- Run\-time\-compiled tr/// objects.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&  use Regexp::Tr;
\&  my $trier = Regexp::Tr\->new("a\-z","z\-a");
\&  my $swapped = "foobar";
\&  $trier\->bind(\e$swapped);               # $swapped is now "ullyzi"
\&  my $tred = $trier\->trans("barfoo");    # $tred is "yziull"
\&  Regexp::Tr\->flush();                   # Cache is gone!
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
Solves the problem requiring compile-time knowledge of tr/// 
constructs by generating the tr/// at run-time and storing it as an 
object.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
One very useful ability of Perl is to do relatively cheap 
transliteration via the tr/// regex operator.  Unfortunately, Perl 
requires tr/// to be known at compile-time.  The common solution has 
been to put an eval around any dynamic tr/// operations, but that is 
very expensive to be used often (for instance, within a loop).  This 
module solves that problem by compiling the tr/// a single time and 
allowing the user to use it repeatedly and delete it when it it no 
longer useful.
.SS "User Efficiency Notes"
.IX Subsection "User Efficiency Notes"
The last instance created is stored for efficient recreation.  This is 
useful for repeated iterations over the same code (for instance, 
within a loop).  The last instance created is stored seperately for 
every package which uses this module, so multiple packages relying on 
this ability can still gain the speed benefit.
.PP
This cache may be emptied may be regained at any time by calling the 
class method \s-1CLASS\-\s0>\fIflush()\fR.  All objects will continue to function, 
but the internal cache will be emptied.  This is probably not worth it
unless there are many different namespaces using this package or the
program is very memory-sensitive.
.SH "METHODS"
.IX Header "METHODS"
.SS "\s-1CLASS\-\s0>new(\s-1FROMSTRING,TOSTRING\s0,[\s-1MODIFIERS\s0])"
.IX Subsection "CLASS->new(FROMSTRING,TOSTRING,[MODIFIERS])"
This creates a new instance of this object.  \s-1FROMSTRING\s0 is the 
precursor string for the tr/// (eg: \*(L"a\-z\*(R"), \s-1TOSTRING\s0 is the succsessor 
string for the tr/// (eg: \*(L"bac-z\*(R"), and the optional \s-1MODIFIERS\s0 is a 
string containing any modifiers to the tr/// (eg: \*(L"e\*(R", etc.).
.ie n .SS "$obj\->bind(\s-1SCALARREF\s0)"
.el .SS "\f(CW$obj\fP\->bind(\s-1SCALARREF\s0)"
.IX Subsection "$obj->bind(SCALARREF)"
This binds the given \s-1SCALARREF\s0 and then performs the object's tr/// 
operation, returning what the tr/// operation will return.  Note that
this method does not create the reference, so the user is responsible 
for backslashing the variable.
.ie n .SS "$obj\->trans(\s-1SCALAR\s0)"
.el .SS "\f(CW$obj\fP\->trans(\s-1SCALAR\s0)"
.IX Subsection "$obj->trans(SCALAR)"
This takes a scalar, performs the tr/// operation, and returns the 
tr///ed string in scalar context, or a list consisting of the tr///ed 
string and the tr/// return value in list context.
.SS "\s-1CLASS\-\s0>\fIflush()\fP"
.IX Subsection "CLASS->flush()"
Flushes the efficiency cache, potentially gaining some memory back 
but forcing the next object to be created entirely from scratch.
Returns void.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "perlop" 4
.IX Item "perlop"
Provides a definition of the tr/// operator.
.IP "perlre" 4
.IX Item "perlre"
Provides more information on the operator.
.SH "AUTHOR"
.IX Header "AUTHOR"
Robert Fischer, <chia@cpan.org>
Hamline University, class of 2004.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2003 by Robert Fischer
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.