permutation 0.1.3

data/CHANGES

@@ -0,0 +1,11 @@
+2004-07-16 (0.1.3)
+    * Moved gemspec into Rakefile
+    * Cleaned up a bit.
+2004-07-16 (0.1.2)
+    * Added Permutation.for factory method for convenience.
+    * Raising ArgumentError instead of simple strings.
+2004-07-03 (0.1.1)
+    * First Rubyforge version.
+    * Supports rubygems now.
+2004-04-29 (0.1.0)
+    * Initial version

data/GPL

@@ -0,0 +1,340 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+                       59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.

data/README.en

@@ -0,0 +1,35 @@
+Installation
+============
+
+Just type into the command line as root:
+
+# ruby install.rb
+
+Or if you already use rubygems (you should!) just type and rubygems fetches
+the gem and installs it for you:
+
+# gem install permutation
+
+Documentation
+=============
+
+To create the documentation of this module, type
+
+$ ruby make_doc.rb
+
+and the API documentation is generated by your rdoc command in
+the doc/ sub-directory.
+
+In the examples direcotry is a small example that solves the
+Traveling Salesman Problem (TSP) with this library.
+
+Author
+======
+
+Florian Frank <flori@ping.de>
+
+License
+=======
+
+GNU General Public License (GPL)
+

data/Rakefile

@@ -0,0 +1,78 @@
+require 'rake/gempackagetask'
+require 'rbconfig'
+
+include Config
+
+PKG_NAME = 'permutation'
+PKG_VERSION = File.read('VERSION').chomp
+PKG_FILES = Dir.glob("**/*").delete_if { |item|
+  item.include?("CVS") or item.include?("pkg")
+}
+
+desc "Installing library"
+task :install  do
+  ruby 'install.rb'
+end
+
+desc "Creating documentation"
+task :doc do
+  ruby 'make_doc.rb'
+end
+
+desc "Testing library"
+task :test  do
+  ruby %{-Ilib test/test.rb}
+end
+
+spec = Gem::Specification.new do |s|
+
+  #### Basic information.
+
+  s.name = 'permutation'
+  s.version = PKG_VERSION
+  s.summary = 'Permutation library in pure Ruby'
+  s.description = ""
+
+  #### Dependencies and requirements.
+
+  #s.add_dependency('log4r', '> 1.0.4')
+  #s.requirements << ""
+
+  s.files = PKG_FILES
+
+  #### C code extensions.
+
+  #s.extensions << "ext/extconf.rb"
+
+  #### Load-time details: library and application (you will need one or both).
+
+  s.require_path = 'lib'                         # Use these for libraries.
+  s.autorequire = 'permutation'
+
+  #s.bindir = "bin"                              # Use these for applications.
+  #s.executables = ["bla.rb"]
+  #s.default_executable = "bla.rb"
+
+  #### Documentation and testing.
+
+  s.has_rdoc = true
+  #s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
+  #s.rdoc_options <<
+  #  '--title' <<  'Rake -- Ruby Make' <<
+  #  '--main' << 'README' <<
+  #  '--line-numbers'
+  s.test_files << 'test/test.rb'
+
+  #### Author and project details.
+
+  s.author = "Florian Frank"
+  s.email = "flori@ping.de"
+  s.homepage = "http://permutation.rubyforge.org"
+  s.rubyforge_project = "permutation"
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_tar = true
+  pkg.package_files += PKG_FILES
+end
+  # vim: set et sw=2 ts=2:

data/VERSION

@@ -0,0 +1 @@
+0.1.3

data/examples/tsp.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+#
+# Solves the Traveling Salesmen Problem: A minimal length tour through n
+# cities (and returning to the first city) is computed -- by brute
+# force.
+
+require 'permutation'
+
+def make_matrix(n)
+    dist = Array.new(n) { [] }
+    for i in 0...n
+        for j in 0...n
+            case
+            when i == j then dist[i][j] = 0
+            when i < j then  dist[i][j] = 1 + rand(999)
+            when i > j then  dist[i][j] = dist[j][i]
+            end
+        end
+    end
+    dist
+end
+
+def pretty_distances(dist)
+    dist.map { |line| line.map { |x| "%3u" % x }.join(' ') }.join("\n")
+end
+
+def solution(p, dist)
+    (0...p.size).map { |i| dist[ p[i - 1] ][ p[i] ] }.join(' + ')
+end
+
+n = ARGV.empty? ? 7 : ARGV.shift.to_i
+distances = make_matrix(n)
+puts "Random distance matrix", pretty_distances(distances)
+optimum, minsum = nil, nil
+perm = Permutation.new(distances.size - 1)
+puts "Searching through #{perm.last + 1} solutions..."
+projection = (1...distances.size).to_a
+perm.each! do |p|
+    tour = p.project(projection)
+    # Little trick: We always start in city 0:
+    tour.unshift(0)
+    sum = 0
+    0.upto(tour.size - 1) do |i|
+        sum += distances[ tour[i - 1] ][ tour[i] ]
+    end
+    if $DEBUG
+        puts "Computed tour #{tour.inspect} with sum = #{sum} = " +
+            "#{solution(tour, distances)}."
+    end
+    if not minsum or minsum > sum
+        optimum, minsum = tour, sum
+    end
+end
+puts "Optimal tour is #{optimum.inspect} with sum = #{minsum} = " +
+     "#{solution(optimum, distances)}."
+    # vim: set et sw=4 ts=4:

data/install.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'rbconfig'
+require 'fileutils'
+include FileUtils::Verbose
+
+include Config
+
+file = 'lib/permutation.rb'
+dest = CONFIG["sitelibdir"]
+install(file, dest)
+    # vim: set et sw=4 ts=4:

data/lib/permutation.rb

@@ -0,0 +1,474 @@
+# = permutation.rb - Permutation class for Ruby
+#
+# == Author
+#
+# Florian Frank mailto:flori@ping.de
+#
+# == License
+#
+# This is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License Version 2 as published by the Free
+# Software Foundation: www.gnu.org/copyleft/gpl.html
+#
+# == Download
+#
+# The latest version of <b>permutation</b> can be found at
+#
+# * http://rubyforge.org/frs/?group_id=291
+#
+# The homepage of this library is located at
+#
+# * http://permutation.rubyforge.org
+#
+# == Description
+#
+# This class has a dual purpose: It can be used to create permutations
+# of a given size and to do some simple computations with/on
+# permutations. The instances of this class don't require much memory
+# because they don't include the permutation as a data structure. They
+# only save the information necessary to create the permutation if asked
+# to do so.
+#
+# To generate permutations the ranking/unranking method described in [SS97]
+# is used. Because of Ruby's Bignum arithmetic it is useful also
+# for permutations of very large size.
+# 
+# == Examples
+#
+# In this section some examples show what can be done with this class.
+#
+# Creating all permutations and project them on data:
+#
+#  perm = Permutation.new(3)
+#  # => #<Permutation:0x57dc94 @last=5, @rank=0, @size=3>
+#  perm.map { |p| p.value }
+#  # => [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]]
+#  colors = [:r, :g, :b]
+#  # => [:r, :g, :b]
+#  perm.map { |p| p.project(colors) }
+#  # => [[:r, :g, :b], [:r, :b, :g], [:g, :r, :b], [:g, :b, :r], [:b, :r, :g],
+#  #    [:b, :g, :r]]
+#  string = "abc"# => "abc"
+#  perm.map { |p| p.project(string) }
+#  # => ["abc", "acb", "bac", "bca", "cab", "cba"]
+#
+# Or perhaps more convenient to use:
+#
+#  perm = Permutation.for("abc")
+#  perm.map { |p| p.project }
+#  # => ["abc", "acb", "bac", "bca", "cab", "cba"]
+#
+# Finding the successor and predecessor of Permutations or a
+# certain Permutation for a given rank:
+#
+#  perm = Permutation.new(7)
+#  # => #<Permutation:0x8453c @rank=0, @size=7, @last=5039>
+#  perm.succ!
+#  # => #<Permutation:0x8453c @rank=1, @size=7, @last=5039>
+#  perm.succ!
+#  # => #<Permutation:0x8453c @rank=2, @size=7, @last=5039>
+#  perm.succ!
+#  # => #<Permutation:0x8453c @rank=3, @size=7, @last=5039>
+#  perm.pred!
+#  # => #<Permutation:0x8453c @rank=2, @size=7, @last=5039>
+#  perm.rank = 3200
+#  # => 3200
+#  perm
+#  # => #<Permutation:0x8453c @rank=3200, @size=7, @last=5039>
+#  perm.value
+#  # => [4, 2, 5, 1, 3, 0, 6]
+#
+# Generating random Permutations
+#
+#  perm = Permutation.new(10)
+#  # => #<Permutation:0x59f4c0 @rank=0, @size=10, @last=3628799>
+#  perm.random!.value
+#  # => [6, 4, 9, 7, 3, 5, 8, 1, 2, 0]
+#  perm.random!.value
+#  # => [3, 7, 6, 1, 4, 8, 9, 2, 5, 0]
+#  perm.random!.value
+#  # => [2, 8, 4, 9, 3, 5, 6, 7, 0, 1]
+#  perm.random!.project("ABCDEFGHIJ")
+#  # => "DFJGAEBCIH"
+#  perm.random!.project("ABCDEFGHIJ")
+#  # => "BFADEGHJCI"
+#
+# Performing some mathematical operations on/with Permutations
+#
+#  p1 = Permutation.from_cycles([[1, 3, 2], [5, 7]], 10)
+#  # => #<Permutation:0x593594 @rank=80694, @size=10, @last=3628799>
+#  p2 = Permutation.from_value [3, 2, 0, 5, 6, 8, 9, 1, 4, 7]
+#  # => #<Permutation:0x5897b0 @rank=1171050, @size=10, @last=3628799>
+#  p3 = p1 * p2
+#  # => #<Permutation:0x586a88 @rank=769410, @size=10, @last=3628799>
+#  p3.value
+#  # => [2, 1, 0, 7, 6, 8, 9, 3, 4, 5]
+#  p3.cycles
+#  # => [[0, 2], [3, 7], [4, 6, 9, 5, 8]]
+#  p4 = p1 * -p2
+#  # => #<Permutation:0x581a10 @rank=534725, @size=10, @last=3628799>
+#  p4.value
+#  # => [1, 5, 3, 0, 8, 2, 4, 9, 7, 6]
+#  p4.cycles
+#  # => [[0, 1, 5, 2, 3], [4, 8, 7, 9, 6]]
+#  id = p1 * -p1
+#  # => #<Permutation:0x583a7c @rank=0, @size=10, @last=3628799>
+#
+# == References
+#
+#  [SS97] The Algorithm Design Manual, Steven S. Skiena, Telos/Springer, 1997.
+# 
+
+class Permutation
+
+    include Enumerable
+    include Comparable
+
+    # Creates a new Permutation instance of <code>size</code>
+    # (and ranked with <code>rank</code>).
+    def initialize(size, rank = 0)
+        @size, @rank = size, rank
+        @last = factorial(size) - 1
+    end
+
+    # Creates a new Permutation instance from the Array
+    # <code>indices</code>, that should consist of a permutation of Fixnums
+    # in the range of <code>0</code> and <code>indices.size - 1</code>. This is
+    # for example the result of a call to the Permutation#value method.
+    def self.from_value(indices)
+        obj = new(indices.size)
+        obj.instance_eval do
+            self.rank = rank_indices(indices)
+        end
+        obj
+    end
+
+    # Creates a new Permutation instance from the Array of Arrays
+    # <code>cycles</code>. This is for example the result of a
+    # call to the Permutation#cycles method .
+    def self.from_cycles(cycles, max = 0)
+        indices = Array.new(max)
+        cycles.each do |cycle|
+            cycle.empty? and next
+            for i in 0...cycle.size
+                indices[ cycle[i - 1] ] = cycle[i]
+            end
+        end
+        indices.each_with_index { |r, i| r or indices[i] = i }
+        from_value(indices)
+    end
+
+	# A permutation instance of size collection.size is created with
+	# collection as the default Permutation#project data object. A
+	# collection should respond to size, [], and []=. The Permutation
+	# instance will default to rank 0 if none is given.
+	def self.for(collection, rank = 0)
+		perm = new(collection.size, rank)
+		perm.instance_variable_set(:@collection, collection)
+		perm
+	end
+
+    # Returns the size of this permutation, a Fixnum.
+    attr_reader :size
+
+    # Returns the size of this permutation, a Fixnum in the range
+    # of 0 and Permutation#last.
+    attr_reader :rank
+
+    # Returns the rank of the last ranked Permutation of size
+    # Permutation#size .
+    attr_reader :last
+
+    # Assigns <code>m</code> to the rank attribute of this Permutation
+    # instance. That implies that the indices produced by a call to the
+    # Permutation#value method of this instance is the permutation ranked with
+    # this new <code>rank</code>.
+    def rank=(m)
+        last = factorial(size) - 1
+        while m > last do m -= last end
+        while m < 0 do m += last end
+        @rank = m
+    end
+
+    # Returns the indices in the range of 0    to Permutation#size - 1
+    # of this permutation that is ranked with Permutation#rank.
+    #
+    # <b>Example:</b>
+    #  perm = Permutation.new(6, 312)
+    #  # => #<Permutation:0x6ae34 @last=719, @rank=312, @size=6>
+    #  perm.value            
+    #  # => [2, 4, 0, 1, 3, 5]
+    def value
+        unrank_indices(@rank)
+    end
+
+    # Returns the projection of this instance's Permutation#value
+    # into the <code>data</code> object that should respond to
+    # the #[] method. If this Permutation inbstance was created
+    # with Permutation.for the collection used to create
+    # it is used as a data object.
+    #
+    # <b>Example:</b>
+    #  perm = Permutation.new(6, 312)
+    #  # => #<Permutation:0x6ae34 @last=719, @rank=312, @size=6>
+    #  perm.project("abcdef")
+    #  # => "ceabdf"
+    def project(data = @collection)
+        data or raise ArgumentError.new("a collection is required to project")
+        raise ArgumentError.new("data size is != #{size}!") if data.size != size
+        projection = data.clone
+        value.each_with_index { |i, j| projection[j] = data[i] }
+        projection
+    end
+
+    # Switches this instances to the next ranked Permutation.
+    # If this was the Permutation#last permutation it wraps around
+    # the first (<code>rank == 0</code>) permutation.
+    def next!
+        @rank += 1
+        last = factorial(size) - 1
+        @rank = 0 if @rank > last
+        self
+    end
+
+    alias succ! next!
+
+    # Returns the next ranked Permutation instance.
+    # If this instance is the Permutation#last permutation it returns the first
+    # (<code>rank == 0</code>) permutation.
+    def next
+        clone.next!
+    end
+
+    alias succ next
+
+    # Switches this instances to the previously ranked Permutation.
+    # If this was the first permutation it returns the last (<code>rank ==
+    # Permutation#last</code>) permutation.
+    def pred!
+        @rank -= 1
+        last = factorial(size) - 1
+        @rank = last if @rank < 0
+        self
+    end
+
+    # Returns the previously ranked Permutation. If this was the first
+    # permutation it returns the last (<code>rank == Permutation#last</code>)
+    # permutation.
+    def pred
+        clone.pred!
+    end
+
+    # Switches this Permutation instance to random permutation
+    # of size Permutation#size.
+    def random!
+        new_rank = rand(last).to_i
+        self.rank = new_rank
+        self
+    end
+
+    # Returns a random Permutation instance # of size Permutation#size.
+    def random
+        clone.random!
+    end
+
+    # Iterates over all permutations of size Permutation#size starting with the
+    # first (<code>rank == 0</code>) ranked permutation and ending with the
+    # last (<code>rank == Permutation#last</code>) ranked permutation while
+    # yielding to a freshly created Permutation instance for every iteration
+    # step.
+    #
+    # The mixed in methods from the Enumerable module rely on this method.
+    def each # :yields: perm
+        0.upto(last) do |r|
+            klon = clone
+            klon.rank = r
+            yield klon
+        end
+    end
+
+    # Does something similar to Permutation#each. It doesn't create new
+    # instances (less overhead) for every iteration step, but yields to a
+    # modified self instead. This is useful if one only wants to call a
+    # method on the yielded value and work with the result of this call. It's
+    # not a good idea to put the yielded values in a data structure because the
+    # will all reference the same (this!) instance. If you want to do this
+    # use Permutation#each.
+    def each!
+        old_rank = rank
+        0.upto(last) do |r|
+            self.rank = r
+            yield self
+        end
+        self.rank = old_rank
+    end
+
+    # Compares to Permutation instances according to their Permutation#size
+    # and the Permutation#rank.
+    #
+    # The mixed in methods from the Comparable module rely on this method.
+    def <=>(other)
+        size <=> other.size.zero? || rank <=> other.rank
+    end
+
+    # Returns true if this Permutation instance and the other have the same
+    # value, that is both Permutation instances have the same Permutation#size
+    # and the same Permutation#rank.
+    def eql?(other)
+        self.class == other.class && size == other.size && rank == other.rank
+    end
+
+    alias == eql?
+
+    # Computes a unique hash value for this Permutation instance.
+    def hash
+        size.hash ^ rank.hash
+    end
+
+    # Switchtes this Permutation instance to the inverted permutation.
+    # (See Permutation#compose for an example.)
+    def invert!
+        indices = unrank_indices(rank)
+        inverted = Array.new(size)
+        for i in 0...size
+            inverted[indices[i]] = i
+        end
+        self.rank = rank_indices(inverted)
+        self
+    end
+
+    # Returns the inverted Permutation of this Permutation instance.
+    # (See Permutation#compose for an example.)
+    def invert
+        clone.invert!
+    end
+
+    alias -@ invert
+
+    # Compose this Permutation instance and the other to
+    # a new Permutation. Note that a permutation
+    # composed with it's inverted permutation yields
+    # the identity permutation, the permutation with rank 0.
+    #
+    # <b>Example:</b>
+    #  p1 = Permutation.new(5, 42)
+    #  # => #<Permutation:0x75370 @last=119, @rank=42, @size=5>
+    #  p2 = p1.invert
+    #  # => #<Permutation:0x653d0 @last=119, @rank=51, @size=5>
+    #  p1.compose(p2)
+    #  => #<Permutation:0x639a4 @last=119, @rank=0, @size=5>
+    # Or a little nicer to look at:
+    #  p1 * -p1
+    #  # => #<Permutation:0x62004 @last=119, @rank=0, @size=5>
+    def compose(other)
+        size == other.size or raise ArgumentError.new(
+            "permutations of unequal sizes cannot be composed!")
+        indices = self.value
+        composed = other.value.map { |i| indices[i] }
+        klon = clone
+        klon.rank = rank_indices(composed)
+        klon
+    end
+
+    alias * compose
+
+    # Returns the cycles representation of this Permutation instance.
+    # The return value of this method can be used to create a
+    # new Permutation instance with the Permutation.from_cycles method.
+    #
+    # <b>Example:</b>
+    #  perm = Permutation.new(7, 23)
+    #  # => #<Permutation:0x58541c @last=5039, @rank=23, @size=7>
+    #  perm.cycles
+    #  # => [[3, 6], [4, 5]]
+    def cycles
+        perm = value
+        result = [[]]
+        seen = {}
+        current = nil
+        until seen == perm.size
+            current or current = perm.find { |x| !seen[x] }
+            break unless current
+            if seen[current]
+                current = nil
+                result << []
+            else
+                seen[current] = true
+                result[-1] << current
+                current = perm[current]
+            end
+        end
+        result.pop
+        result.select { |c| c.size > 1 }.map do |c|
+            min_index = c.index(c.min)
+            c[min_index..-1] + c[0...min_index]
+        end
+    end
+
+    # Returns the signum of this Permutation instance.
+    # It's -1 if this permutation is odd and 1 if it's
+    # an even permutation.
+    #
+    # A permutation is odd if it can be represented by an odd number of
+    # transpositions (cycles of length 2), or even if it can be represented of
+    # an even number of transpositions.
+    def signum
+        s = 1
+        cycles.each do |c|
+            c.size % 2 == 0 and s *= -1
+        end
+        s
+    end
+
+    alias sgn signum
+
+    # Returns true if this permutation is even, false otherwise.
+    def even?
+        signum == 1
+    end
+
+    # Returns true if this permutation is odd, false otherwise.
+    def odd?
+        signum == -1
+    end
+
+    private
+
+    @@factorial_cache = {}
+
+    def factorial(n)
+        f = @@factorial_cache[n] and return f
+        f = 1
+        for i in 2..n do f *= i end
+        @@factorial_cache[n] = f
+    end
+
+    def rank_indices(p)
+        result = 0
+        for i in 0...size
+            result += p[i] * factorial(size - i - 1)
+            for j in (i + 1)...size
+                p[j] -= 1 if p[j] > p[i] 
+            end
+        end
+        result
+    end
+
+    def unrank_indices(m)
+        result = Array.new(size, 0)
+        for i in 0...size
+            f = factorial(i)
+            x = m % (f * (i + 1))
+            m -= x
+            x /= f
+            result[size - i - 1] = x
+            x -= 1
+            for j in (size - i)...size
+                result[j] += 1 if result[j] > x
+            end
+        end
+        result
+    end
+
+end
+    # vim: set et sw=4 ts=4:

data/make_doc.rb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+$outdir = 'doc/'
+puts "Creating documentation in '#$outdir'."
+system "rdoc -d -o #$outdir lib/permutation.rb"
+    # vim: set et sw=4 ts=4:

data/test/test.rb

@@ -0,0 +1,247 @@
+#!/usr/bin/env ruby
+
+require 'test/unit'
+require 'permutation'
+
+class TC_Permutation < Test::Unit::TestCase
+
+    def setup
+        @perms = (0..4).map { |i| Permutation.new(i) }
+        @perms_collections = [ "", "a", "ab", "abc", "abcd" ].map do |c|
+            Permutation.for(c)
+        end
+        @perms_each = [
+            [[]],
+            [[0]],
+            [[0, 1], [1, 0]],
+            [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]],
+            [[0, 1, 2, 3], [0, 1, 3, 2], [0, 2, 1, 3], [0, 2, 3, 1],
+                [0, 3, 1, 2], [0, 3, 2, 1], [1, 0, 2, 3], [1, 0, 3, 2],
+                [1, 2, 0, 3], [1, 2, 3, 0], [1, 3, 0, 2], [1, 3, 2, 0],
+                [2, 0, 1, 3], [2, 0, 3, 1], [2, 1, 0, 3], [2, 1, 3, 0],
+                [2, 3, 0, 1], [2, 3, 1, 0], [3, 0, 1, 2], [3, 0, 2, 1],
+                [3, 1, 0, 2], [3, 1, 2, 0], [3, 2, 0, 1], [3, 2, 1, 0]]
+        ]
+        @next_pred = [
+            [ [], [] ],
+            [ [ 0 ], [ 0 ] ],
+            [ [ 0, 1 ], [ 1, 0 ] ],
+            [ [ 1, 0 ], [ 0, 1 ] ],
+            [ [ 0, 1, 2 ], [ 0, 2, 1 ] ],
+            [ [ 0, 2, 1 ], [ 1, 0, 2 ] ],
+            [ [ 1, 0, 2 ], [ 1, 2, 0 ] ],
+            [ [ 1, 2, 0 ], [ 2, 0, 1 ] ],
+            [ [ 2, 0, 1 ], [ 2, 1, 0 ] ],
+            [ [ 2, 1, 0 ], [ 0, 1, 2 ] ],
+        ]
+        @projected = [
+            [ "" ],
+            [ "a" ],
+            [ "ab", "ba", ],
+            [ "abc", "acb", "bac", "bca", "cab", "cba" ],
+            [ "abcd", "abdc", "acbd", "acdb", "adbc", "adcb", "bacd",
+                "badc", "bcad", "bcda", "bdac", "bdca", "cabd", "cadb",
+                "cbad", "cbda", "cdab", "cdba", "dabc", "dacb", "dbac",
+                "dbca", "dcab", "dcba"]
+        ]
+        @products = [
+            {[0, 0]=>[]},
+            {[0, 0]=>[0]},
+            {[0, 0]=>[0, 1], [1, 1]=>[0, 1], [1, 0]=>[1, 0], [0, 1]=>[1, 0]},
+            {[2, 4]=>[2, 1, 0], [1, 2]=>[2, 0, 1], [0, 0]=>[0, 1, 2],
+                    [5, 4]=>[0, 2, 1], [3, 3]=>[2, 0, 1], [2, 1]=>[1, 2, 0],
+                    [0, 5]=>[2, 1, 0], [3, 5]=>[0, 2, 1], [1, 1]=>[0, 1, 2],
+                    [0, 3]=>[1, 2, 0], [5, 3]=>[1, 0, 2], [4, 1]=>[2, 1, 0],
+                    [3, 2]=>[2, 1, 0], [2, 0]=>[1, 0, 2], [0, 4]=>[2, 0, 1],
+                    [3, 4]=>[0, 1, 2], [1, 0]=>[0, 2, 1], [0, 2]=>[1, 0, 2],
+                    [5, 2]=>[1, 2, 0], [4, 0]=>[2, 0, 1], [3, 1]=>[1, 0, 2],
+                    [2, 3]=>[0, 2, 1], [1, 5]=>[1, 2, 0], [4, 5]=>[1, 0, 2],
+                    [5, 1]=>[2, 0, 1], [4, 3]=>[0, 1, 2], [3, 0]=>[1, 2, 0],
+                    [2, 2]=>[0, 1, 2], [1, 4]=>[1, 0, 2], [4, 4]=>[1, 2, 0],
+                    [5, 0]=>[2, 1, 0], [4, 2]=>[0, 2, 1], [2, 5]=>[2, 0, 1],
+                    [1, 3]=>[2, 1, 0], [0, 1]=>[0, 2, 1], [5, 5]=>[0, 1, 2]}
+        ]
+        @cycles = [
+            [[]],
+            [[]],
+            [[], [[0, 1]]],
+            [[], [[1, 2]], [[0, 1]], [[0, 1, 2]], [[0, 2, 1]], [[0, 2]]],
+            [[], [[2, 3]], [[1, 2]], [[1, 2, 3]], [[1, 3, 2]], [[1, 3]],
+                [[0, 1]], [[0, 1], [2, 3]], [[0, 1, 2]], [[0, 1, 2, 3]],
+                [[0, 1, 3, 2]], [[0, 1, 3]], [[0, 2, 1]], [[0, 2, 3, 1]],
+                [[0, 2]], [[0, 2, 3]], [[0, 2], [1, 3]], [[0, 2, 1, 3]],
+                [[0, 3, 2, 1]], [[0, 3, 1]], [[0, 3, 2]], [[0, 3]],
+                [[0, 3, 1, 2]], [[0, 3], [1, 2]]]
+        ]
+        @signum = [
+            [1],
+            [1],
+            [1, -1],
+            [1, -1, -1, 1, 1, -1],
+            [1, -1, -1, 1, 1, -1, -1, 1, 1, -1, -1, 1, 1, -1, -1, 1, 1, -1,
+                -1, 1, 1, -1, -1, 1]
+        ]
+    end
+
+    def test_created
+        factorial = 1
+        @perms.each_with_index do |p, i|
+            assert_equal(i, p.size)
+            assert_equal(factorial - 1, p.last)
+            factorial *= (i + 1)
+        end
+    end
+
+    def test_rank_assign
+        perm = Permutation.new(3)
+        perms = [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1],
+                [2, 1, 0]]
+        (-5...0).each do |i|
+            perm.rank = i
+            assert_equal(perms[i + 5], perm.value)
+        end
+        (-10...-5).each do |i|
+            perm.rank = i
+            assert_equal(perms[i + 10], perm.value)
+        end
+        (0..5).each do |i|
+            perm.rank = i
+            assert_equal(perms[i], perm.value)
+        end
+        (6..10).each do |i|
+            perm.rank = i
+            assert_equal(perms[i - 5], perm.value)
+        end
+        (11..15).each do |i|
+            perm.rank = i
+            assert_equal(perms[i - 10], perm.value)
+        end
+    end
+
+    def test_compare
+        perm1 = Permutation.new(3)
+        perm2 = Permutation.new(3)
+        perm3 = perm1.dup
+        perm4 = Permutation.new(3, 1)
+        assert(!perm1.equal?(perm2))
+        assert(perm1 == perm2)
+        assert(perm1.eql?(perm2))
+        assert_equal(0, perm1 <=> perm2)
+        assert_equal(perm1.hash, perm2.hash)
+        assert(!perm1.equal?(perm3))
+        assert(perm1 == perm3)
+        assert(perm1.eql?(perm3))
+        assert_equal(0, perm1 <=> perm3)
+        assert_equal(perm1.hash, perm3.hash)
+        assert(!perm1.equal?(perm4))
+        assert(perm1 != perm4)
+        assert(!perm1.eql?(perm4))
+        assert_equal(-1, perm1 <=> perm4)
+        assert_equal(1, perm4 <=> perm1)
+        assert(perm1 < perm4)
+        assert(perm4 > perm1)
+        assert(perm1.hash != perm4.hash)
+        perms = perm1.to_a
+        perms[1..-1].each_with_index do |p, i|
+            assert(p > perms[i])
+            assert_equal(1, p <=> perms[i])
+            assert(perms[i] < p)
+            assert_equal(-1, perms[i] <=> p)
+        end
+    end
+
+    def test_random
+        @perms_each.each_with_index do |perms, i|
+            perm = Permutation.new(i)
+            24.times do
+                assert(perms.member?(perm.random.value))
+            end
+        end
+    end
+
+    def test_enumerable
+        @perms.each_with_index do |perm, i|
+            assert_equal(@perms_each[i], perm.map { |x| x.value })
+        end
+        @perms.each_with_index do |perm, i|
+            ary = []
+            old_rank = perm.rank
+            perm.each! { |x| ary << x.value }
+            assert_equal(@perms_each[i], ary)
+            assert_equal(old_rank, perm.rank)
+        end
+    end
+
+    def test_next
+        @next_pred.each do |before, after|
+            beforep = Permutation.from_value(before)
+            afterp = Permutation.from_value(after)
+            assert_equal(afterp, beforep.next)
+            assert_equal(beforep, afterp.pred)
+            assert_equal(afterp, beforep.succ)
+        end
+    end
+
+    def test_project
+        too_big = Array.new(10)
+        @perms.each_with_index do |perms, i|
+            assert_equal(@projected[i],
+                perms.map { |p| p.project(@projected[i][0]) })
+            assert_raises(ArgumentError) { perms.project }
+            assert_raises(ArgumentError) { perms.project(too_big) }
+        end
+        @perms_collections.each_with_index do |perms, i|
+            assert_equal(@projected[i], perms.map { |p| p.project })
+        end
+    end
+
+    def test_compose
+        too_big = Permutation.new(10)
+        @perms[0..3].each do |perm|
+            elements = perm.to_a
+            for i in 0...elements.size
+                for j in 0...elements.size
+                    assert_equal(@products[perm.size][[i, j]],
+                        (elements[i].compose(elements[j])).value)
+                    assert_equal(@products[perm.size][[i, j]],
+                        (elements[i] * elements[j]).value)
+                end
+                assert_raises(ArgumentError) { elements[i] * too_big }
+                assert_raises(ArgumentError) { elements[i].compose(too_big) }
+            end
+        end
+    end
+
+    def test_invert
+        @perms.each do |perm|
+            id = perm
+            perm.each do |p|
+                assert_equal(id.value, (p * p.invert).value)
+                assert_equal(id, p * p.invert)
+                assert_equal(id.value, (p * -p).value)
+                assert_equal(id, p * -p)
+            end
+        end
+    end
+
+    def test_cycles
+        @perms.each_with_index do |perm, i|
+            assert_equal(@cycles[i], perm.map { |p| p.cycles })
+            assert_equal(perm.to_a,
+                @cycles[i].map { |c| Permutation.from_cycles(c, i) })
+        end
+    end
+
+    def test_signum
+        @perms.each_with_index do |perm, i|
+            assert_equal(@signum[i], perm.map { |p| p.signum })
+            assert_equal(@signum[i], perm.map { |p| p.sgn })
+            assert_equal(@signum[i].map { |x| x == 1 },
+                perm.map { |p| p.even? })
+            assert_equal(@signum[i].map { |x| x == -1 },
+                perm.map { |p| p.odd? })
+        end
+    end
+
+end
+    # vim: set et sw=4 ts=4:

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: permutation
+version: !ruby/object:Gem::Version 
+  version: 0.1.3
+date: 2005-10-05 00:00:00 +02:00
+summary: Permutation library in pure Ruby
+require_paths: 
+  - lib
+email: flori@ping.de
+homepage: http://permutation.rubyforge.org
+rubyforge_project: permutation
+description: ''
+autorequire: permutation
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+  - Florian Frank
+files: 
+  - examples
+  - install.rb
+  - GPL
+  - test
+  - Rakefile
+  - VERSION
+  - CHANGES
+  - lib
+  - make_doc.rb
+  - README.en
+  - examples/tsp.rb
+  - test/test.rb
+  - lib/permutation.rb
+test_files: 
+  - test/test.rb
+rdoc_options: []
+extra_rdoc_files: []
+executables: []
+extensions: []
+requirements: []
+dependencies: []