.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 "FastPermute 3pm"
.TH FastPermute 3pm "2008-02-23" "perl v5.34.0" "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"
Algorithm::FastPermute \- Rapid generation of permutations
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  use Algorithm::FastPermute (\*(Aqpermute\*(Aq);
\&  my @array = (1..shift());
\&  permute {
\&      print "@array\en";         # Print all the permutations
\&  } @array;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Algorithm::FastPermute generates all the permutations of an array. You pass a
block of code, which will be executed for each permutation. The array will be
changed in place, and then changed back again before \f(CW\*(C`permute\*(C'\fR returns. During
the execution of the callback, the array is read-only and you'll get an error
if you try to change its length. (You \fIcan\fR change its elements, but the
consequences are liable to confuse you and may change in future versions.)
.PP
You have to pass an array, it can't just be a list. It \fBdoes\fR work with
special arrays and tied arrays, though unless you're doing something
particularly abstruse you'd be better off copying the elements into a normal
array first.
.PP
It's very fast. My tests suggest it's four or five times as fast as
Algorithm::Permute's traditional interface.  If you're permuting a large list
(nine or more elements, say) then you'll appreciate this enormously. If your
lists are short then Algorithm::Permute will still finish faster than you can
blink, and you may find its interface more convenient.
.PP
In fact, the FastPermute interface (and code) is now also included in
Algorithm::Permute, so you may not need both. Enhancements and bug fixes
will appear here first, from where (at Edwin Pratomo's discretion) they'll
probably make their way into Algorithm::Permute.
.PP
The code is run inside a pseudo block, rather than as a normal subroutine. That
means you can't use \f(CW\*(C`return\*(C'\fR, and you can't jump out of it using \f(CW\*(C`goto\*(C'\fR and
so on. Also, \f(CW\*(C`caller\*(C'\fR won't tell you anything helpful from inside the
callback. Such is the price of speed.
.PP
The order in which the permutations are generated is not guaranteed, so don't
rely on it.
.SH "EXPORT"
.IX Header "EXPORT"
The \f(CW\*(C`permute\*(C'\fR function is exported by default.
.SH "AUTHOR"
.IX Header "AUTHOR"
Robin Houston, <robin@kitsite.com>
.PP
Based on a C program by Matt Day.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Algorithm::Permute
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2001\-2008, Robin Houston. All Rights Reserved.
This module is free software. It may be used, redistributed
and/or modified under the same terms as Perl itself.