facets 0.6.3

data/README

@@ -0,0 +1,130 @@
+= Ruby Facets
+
+=== Introduction Ruby's Atomic Library
+
+Ruby Facets, the Fantastic Atomic Core Extensions, is an growing
+collection of extension methods for Ruby's core and standard libs.
+It is an _atomic_ library in that the methods are, to the greatest
+degree reaonable, packaged individually so that each can be _required_
+independently. Facets is an open library and all are wlecome to
+contribute to it growth. The package currently contains over 200
+methods, spanning 26 classes and modules. Facets also includes a 
+repository for experimental works, called <tt>facet-dev</tt>. 
+This provideds a public location to develop and try nascent extensions,
+which may eventually make their way into Facets proper. 
+
+
+=== Calibre
+
+Ruby Facets is part of the Calibre project. You can learn more at:
+
+  http://calibre.rubyforge.com
+
+
+=== Installation
+
+To install untar the package and use the included setup.rb script.
+For example:
+  
+  > tar -xvzf facets-x.y.z.tar.gz
+  > cd facets-x.y.z
+  > sudo ruby setup.rb
+
+
+=== Usage
+
+There are quite a few methods spread out over numerous classes and methods.
+For detailed usage please refer to the API RDocs. Most methods are fairly well
+documented, but not all. Assistance in improving documentation is much appreciated.
+
+The general require statement is as follows: 
+
+  require 'facet/<class|module>/<method>'
+
+All lowercase. For example, perhaps a paricular application would be better
+served if the NilClass responded to the <tt>#empty?</tt> message.
+  
+  require 'facet/nil/empty?'
+
+And the <tt>#empty?</tt> method will then be only new method added.
+
+Almost every file is named for the method in contains. The only
+exceptions are for methods that are very tightly related. In these
+cases the file will be named either for the "core" method, or as
+a conjunction, like <tt>first&last.rb</tt>.
+
+There are also shortcuts for including selections in mass.
+In the future there will be more of these. For now there are only 
+the following two.
+
+If you wish to include all the methods consider fundemental "base" 
+methods:
+
+  require 'facet/all-base'
+
+This represents a group of about one to two dozen methods that are 
+considered likely to be included in future versions of Ruby itself.
+
+If you would like to include the "base" methods plus all the methods
+considered "common":
+
+  require 'facet/all-base-common'
+
+This is a large selection of methods that are considered the most 
+generally useful.
+
+All methods considered "uncommon" must be require individually.
+Since it is possible for a few of the uncommon methods to conflict
+with one another, there is no way to include _everything_.
+
+
+=== Contribute
+
+The project thrives on contribution. Please feel free to offer any
+extension you wish. The criteria for inclusion is fairly light:
+
+* Is it generally useful and/or highly interesting? 
+* Does it pass a basic testcase?
+
+If it meets these requirements then it will in all likelihood 
+be accepted into the main facets lib. Otherwise it may still find
+a place in the development library. Feel free to explore this
+facets-dev repository and, if so inclined, help develop what's 
+there. If you have an underdeveloped extension that you'd like 
+to see developed, please submit it and it can be placed into dev,
+where it can reside and worked on by the community at large.
+
+
+=== Mascot
+
+Does evey good project need a mascot? Well then, Facets
+has the Raspberry. Why the Raspberry? Because it is 
+Red and Faceted, of course. :)
+
+
+=== Authorship
+
+This collection was put together by, and largely written by Thomas Sawyer
+(aka T. Onoma). He can be reached via email at transami at runbox.com.
+
+Some parts of this collection were written and/or inspired by other
+persons. Fortunately nearly all were copyrighted under the same open
+license as this library. In the few excpetions I have included the
+copyright notice with the source code. In all cases, I have made every
+effort to give credit where credit is due. You will find these thanks
+and acknowledgements at the beginning of the source code.
+
+The collection as a whole is licensed as follows:
+
+  Ruby Facets, the Fantastic Atomic Core Extensions
+  Copyright (c) 2004 Thomas Sawyer
+  Ruby License
+
+The Ruby license is a dual license that also provides for use of the GPL.
+A copy of both licenses should accompany this document.
+
+
+=== Pitch
+
+  ALL YOUR BASE ARE BELONG TO RUBY
+

data/Reapfile

@@ -0,0 +1,74 @@
+--- %YAML:1.0
+
+TITLE: &title Ruby Facets
+NAME: &pkg facets
+VERSION: '0.6.3'
+AUTHOR: Trans
+EMAIL: transfire@gmail.com
+HOMEPAGE: "http://calibre.rubyforge.org"
+
+SUMMARY: Fantastic Atomic Core Extensions
+
+DESCRIPTION: >
+  Ruby Facets is a cornicopia of core extensions for
+  the Ruby programming language. It is unique by virtue
+  of the atomicity of its design. Methods are stored
+  in their own files, allowing for extremely granular
+  control of requirements. Ruby Facets is a subproject
+  of Ruby Calibre.
+
+RUBYFORGE:
+  PROJECT: 'calibre'
+  USERNAME: transami
+
+TEST:
+  FILES:
+    - 'test/**/tc_*.rb'
+  OPTIONS: ~
+
+RDOC:
+  TITLE: *title
+  DIR: 'doc'
+  TEMPLATE: html #ruby-red
+  OPTIONS: ['--merge', '--promiscuous', '--all']
+  MAIN: README
+  INCLUDE:
+    - 'README'
+    - 'LICEN*'
+    - 'lib/facet/**/*.rb'
+  EXCLUDE: []
+
+PACKAGE:
+  DIR: pkg
+  INCLUDE:
+    - 'lib/**/*'
+    - 'bench/**/*'
+    - 'test/**/*'
+    - 'rdoc/**/*'
+    - 'doc/**/*'
+    - 'pub/**/*'
+    - 'demo/**/*'
+    - 'samples/**/*'
+    - 'examples/**/*'
+    - 'setup.rb'
+    - '[A-Z]*'
+  EXCLUDE:
+    - InstalledFiles
+  ZIP: true
+  GZIP: true
+  BZIP2: true
+  GEM: true
+
+ANNOUNCE:
+  TO: transfire@gmail.com #ruby-talk@ruby-lang.org
+  FROM: transfire@gmail.com
+  DOMAIN: jupiterzeus.net
+  SERVER: smtp.gmail.com
+  PORT: 25
+  ACCOUNT: transfire@gmail.com
+  AUTHTYPE: login  #cram_md5 #plain
+  FILE: ANN
+  SLOGAN: ALL YOUR BASE ARE BELONG TO RUBY!
+  INFO:
+    - http://calibre.rubyforge.org
+

data/TODO

@@ -0,0 +1,42 @@
+IT IS ALWAYS A GOOD IDEA TO WRITE A TEST!
+AND ITS ALWAYS A FINE THING TO IMPROVE DOCUMENTATION!
+
+* hash/invert: What about letting Hash#invert take a block that specifies
+what to do when a collision occurs?
+
+* hash/at_rand: allow for a _number_ of values, keys and pairs to be returned.
+
+* > Yep. Gone. But I may replace with a version that deletes only the first 
+  > matching element. Thoughts?
+If you don't want to do that I would rather add an option hash to .delete and
+use :once => true or something similar. (More expressive)
+
+* numeric/bound_by: Numeric includes Comparable. Maybe drop this, but 
+might it be reasonable for Numeric but no other comparables?
+
+* nil/[]: Why should nil respond to [], but not to .each? I don't think 
+nil should be treated as a container.
+nil/length: See above.
+
+* nil/method_missing: I'm not so sure about this. There is a lot of 
+libraries depending on nil raising exceptions on failed method access. I 
+also think that this could make programming errors very hard to find.
+
+* fileutils/head&tail: Hm, I think the block forms ought to be equivalent to 
+tail -f and so on. Then the block forms should also return all lines by default
+instead of only the first 10.
+
+* fileutils/which: Should probably be based on fileutils/where_is as they have 
+lots of common code. The two methods should probably also use RUBY_PLATFORM instead
+of checking for ALT_SEPARATOR.
+
+* module/memoize: Should the main memoize method be defined as it is? 
+(see bottom of file).
+
+* kernel/demo: It can be implemented as demo "1+1"  using Binding.of_caller. 
+Using only the block is possibly with SCRIPT_LINES__ or File access and is quite ugly.
+
+* hash/weave: Document how does it compare to Hash#merge?
+
+* Could use a better String#word_wrap method.
+

data/VERSION

@@ -0,0 +1,7 @@
+0.6.1 Florian's Mixes
+0.6.0 Florian's Onslaught
+0.5.0 First Release
+0.4.0 Raspberry
+0.3.0 ABC
+0.2.0 Succ
+0.1.0 TomsLib

data/doc/classes/Array.html

@@ -0,0 +1,1267 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html 
+     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>Class: Array</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <meta http-equiv="Content-Script-Type" content="text/javascript" />
+  <link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
+  <script type="text/javascript">
+  // <![CDATA[
+
+  function popupCode( url ) {
+    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+  }
+
+  function toggleCode( id ) {
+    if ( document.getElementById )
+      elem = document.getElementById( id );
+    else if ( document.all )
+      elem = eval( "document.all." + id );
+    else
+      return false;
+
+    elemStyle = elem.style;
+    
+    if ( elemStyle.display != "block" ) {
+      elemStyle.display = "block"
+    } else {
+      elemStyle.display = "none"
+    }
+
+    return true;
+  }
+  
+  // Make codeblocks hidden by default
+  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
+  
+  // ]]>
+  </script>
+
+</head>
+<body>
+
+
+
+    <div id="classHeader">
+        <table class="header-table">
+        <tr class="top-aligned-row">
+          <td><strong>Class</strong></td>
+          <td class="class-name-in-header">Array</td>
+        </tr>
+        <tr class="top-aligned-row">
+            <td><strong>In:</strong></td>
+            <td>
+                <a href="../files/lib/facet/array/pull_rb.html">
+                lib/facet/array/pull.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/[]_rb.html">
+                lib/facet/array/[].rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/first&last_rb.html">
+                lib/facet/array/first&amp;last.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/head&tail_rb.html">
+                lib/facet/array/head&amp;tail.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/select!_rb.html">
+                lib/facet/array/select!.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/delete_values_rb.html">
+                lib/facet/array/delete_values.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/last_index_rb.html">
+                lib/facet/array/last_index.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/thru_rb.html">
+                lib/facet/array/thru.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/at_rand_rb.html">
+                lib/facet/array/at_rand.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/range_rb.html">
+                lib/facet/array/range.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/get_rb.html">
+                lib/facet/array/get.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/to_b_rb.html">
+                lib/facet/array/to_b.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/to_h_rb.html">
+                lib/facet/array/to_h.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/[[]]_rb.html">
+                lib/facet/array/[[]].rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/pos_rb.html">
+                lib/facet/array/pos.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/rotate_rb.html">
+                lib/facet/array/rotate.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/shuffle_rb.html">
+                lib/facet/array/shuffle.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/combinations_rb.html">
+                lib/facet/array/combinations.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/middle_rb.html">
+                lib/facet/array/middle.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/array/store_rb.html">
+                lib/facet/array/store.rb
+                </a>
+        <br />
+                <a href="../files/lib/facet/enumerable/each_slice_rb.html">
+                lib/facet/enumerable/each_slice.rb
+                </a>
+        <br />
+            </td>
+        </tr>
+
+        <tr class="top-aligned-row">
+            <td><strong>Parent:</strong></td>
+            <td>
+                <a href="Object.html">
+                Object
+               </a>
+            </td>
+        </tr>
+        </table>
+    </div>
+  <!-- banner header -->
+
+  <div id="bodyContent">
+
+
+
+  <div id="contextContent">
+
+
+
+   </div>
+
+    <div id="method-list">
+      <h3 class="section-bar">Methods</h3>
+
+      <div class="name-list">
+      <a href="#M000027">[]</a>&nbsp;&nbsp;
+      <a href="#M000049">[]</a>&nbsp;&nbsp;
+      <a href="#M000028">[]=</a>&nbsp;&nbsp;
+      <a href="#M000050">[]=</a>&nbsp;&nbsp;
+      <a href="#M000040">at_rand</a>&nbsp;&nbsp;
+      <a href="#M000042">at_rand!</a>&nbsp;&nbsp;
+      <a href="#M000033">body</a>&nbsp;&nbsp;
+      <a href="#M000056">combinations</a>&nbsp;&nbsp;
+      <a href="#M000036">delete_values</a>&nbsp;&nbsp;
+      <a href="#M000037">delete_values_at</a>&nbsp;&nbsp;
+      <a href="#M000062">each_by</a>&nbsp;&nbsp;
+      <a href="#M000057">each_combination</a>&nbsp;&nbsp;
+      <a href="#M000061">each_slice</a>&nbsp;&nbsp;
+      <a href="#M000058">each_unique_pair</a>&nbsp;&nbsp;
+      <a href="#M000029">first=</a>&nbsp;&nbsp;
+      <a href="#M000034">foot</a>&nbsp;&nbsp;
+      <a href="#M000046">get</a>&nbsp;&nbsp;
+      <a href="#M000031">head</a>&nbsp;&nbsp;
+      <a href="#M000045">index_range</a>&nbsp;&nbsp;
+      <a href="#M000030">last=</a>&nbsp;&nbsp;
+      <a href="#M000038">last_index</a>&nbsp;&nbsp;
+      <a href="#M000059">middle</a>&nbsp;&nbsp;
+      <a href="#M000043">pick</a>&nbsp;&nbsp;
+      <a href="#M000051">pos</a>&nbsp;&nbsp;
+      <a href="#M000041">rand_index</a>&nbsp;&nbsp;
+      <a href="#M000044">range</a>&nbsp;&nbsp;
+      <a href="#M000052">rotate</a>&nbsp;&nbsp;
+      <a href="#M000053">rotate!</a>&nbsp;&nbsp;
+      <a href="#M000035">select!</a>&nbsp;&nbsp;
+      <a href="#M000054">shuffle</a>&nbsp;&nbsp;
+      <a href="#M000055">shuffle!</a>&nbsp;&nbsp;
+      <a href="#M000060">store</a>&nbsp;&nbsp;
+      <a href="#M000032">tail</a>&nbsp;&nbsp;
+      <a href="#M000039">thru</a>&nbsp;&nbsp;
+      <a href="#M000047">to_b</a>&nbsp;&nbsp;
+      <a href="#M000048">to_h</a>&nbsp;&nbsp;
+      </div>
+    </div>
+
+  </div>
+
+
+    <!-- if includes -->
+
+    <div id="section">
+
+
+
+    <div id="aliases-list">
+      <h3 class="section-bar">External Aliases</h3>
+
+      <div class="name-list">
+                        <table summary="aliases">
+        <tr class="top-aligned-row context-row">
+          <td class="context-item-name">shift</td>
+          <td>-></td>
+          <td class="context-item-value">pull</td>
+        </tr>
+      <tr class="top-aligned-row context-row">
+        <td>&nbsp;</td>
+        <td colspan="2" class="context-item-desc">
+Alias for shift.
+
+<pre>
+  require 'facet/array/pull'
+
+  a=[1,2,3]
+  a.pull      #=&gt; 1
+  a           #=&gt; [2,3]
+</pre>
+</td>
+      </tr>
+        <tr class="top-aligned-row context-row">
+          <td class="context-item-name">unshift</td>
+          <td>-></td>
+          <td class="context-item-value">put</td>
+        </tr>
+      <tr class="top-aligned-row context-row">
+        <td>&nbsp;</td>
+        <td colspan="2" class="context-item-desc">
+Alias for unshift.
+
+<pre>
+  require 'facet/array/pull'
+
+  a=[1,2,3]
+  a.put(9)   #=&gt; [9,1,2,3]
+  a          #=&gt; [9,1,2,3]
+</pre>
+</td>
+      </tr>
+        <tr class="top-aligned-row context-row">
+          <td class="context-item-name">unshift</td>
+          <td>-></td>
+          <td class="context-item-value">first!</td>
+        </tr>
+      <tr class="top-aligned-row context-row">
+        <td>&nbsp;</td>
+        <td colspan="2" class="context-item-desc">
+Alias for unshift, which <em>pushes</em> an element onto the front of an
+array.
+
+<pre>
+  require 'facet/array/first&amp;last='
+
+  a = [&quot;a&quot;,&quot;y&quot;,&quot;z&quot;]
+  a.first! &quot;x&quot;
+  p a           #=&gt; [&quot;x&quot;,&quot;a&quot;,&quot;y&quot;,&quot;z&quot;]
+</pre>
+</td>
+      </tr>
+        <tr class="top-aligned-row context-row">
+          <td class="context-item-name">push</td>
+          <td>-></td>
+          <td class="context-item-value">last!</td>
+        </tr>
+      <tr class="top-aligned-row context-row">
+        <td>&nbsp;</td>
+        <td colspan="2" class="context-item-desc">
+Alias for push.
+
+<pre>
+  require 'facet/array/first&amp;last='
+
+  a = [1,2]
+  a.last! 3
+  p a           #=&gt; [1,2,3]
+</pre>
+</td>
+      </tr>
+                        </table>
+      </div>
+    </div>
+
+
+      
+
+
+    <!-- if method_list -->
+    <div id="methods">
+      <h3 class="section-bar">Public Class methods</h3>
+
+      <div id="method-M000056" class="method-detail">
+        <a name="M000056"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000056.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000056.html');return false;">
+          <span class="method-name">combinations</span><span class="method-args">(head, *rest)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Produces an array of arrays of all possible combinations of the given
+arrays in the position given. (Explain me better?)
+</p>
+<pre>
+  require 'facet/arrat/combinations'
+
+  a = %w|a b|
+  b = %w|a x|
+  c = %w|x y|
+  Array.combinations(a, b, c).each { |x| p x }
+</pre>
+<p>
+produces
+</p>
+<pre>
+ [&quot;a&quot;, &quot;a&quot;, &quot;x&quot;]
+ [&quot;a&quot;, &quot;a&quot;, &quot;y&quot;]
+ [&quot;a&quot;, &quot;x&quot;, &quot;x&quot;]
+ [&quot;a&quot;, &quot;x&quot;, &quot;y&quot;]
+ [&quot;b&quot;, &quot;a&quot;, &quot;x&quot;]
+ [&quot;b&quot;, &quot;a&quot;, &quot;y&quot;]
+ [&quot;b&quot;, &quot;x&quot;, &quot;x&quot;]
+ [&quot;b&quot;, &quot;x&quot;, &quot;y&quot;]
+</pre>
+        </div>
+      </div>
+
+      <h3 class="section-bar">Public Instance methods</h3>
+
+      <div id="method-M000027" class="method-detail">
+        <a name="M000027"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000027.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000027.html');return false;">
+          <span class="method-name">[]</span><span class="method-args">(*args)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Modifies #[] to accept a multiple indexes.
+</p>
+<pre>
+  require 'facet/array/[]'
+
+  a = ['a','b','c','d','e','f']
+
+  a[1]        #=&gt; 'b'
+  a[1,1]      #=&gt; ['b','b']
+  a[0,2,4]    #=&gt; ['a','c','e']
+  a[1,1,1]    #=&gt; ['b','b','b']
+</pre>
+<p>
+WARNING: Use with caution! This will cause other routines, which use the
+array[start,length] notation to no longer work. If you feel passinate about
+it, make sure all other routines use slice or facet&#8217;s own <a
+href="Array.html#M000046">get</a> method instead.
+</p>
+        </div>
+      </div>
+
+      <div id="method-M000049" class="method-detail">
+        <a name="M000049"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000049.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000049.html');return false;">
+          <span class="method-name">[]</span><span class="method-args">(*args)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Modifies #[] to accept an <a href="Array.html">Array</a> of indexes.
+</p>
+<pre>
+  require 'facet/array/[[]]'
+
+  a = ['a','b','c','d','e','f']
+
+  a[[1]]      #=&gt; ['b']
+  a[[1,1]]    #=&gt; ['b','b']
+  a[[1,-1]]   #=&gt; ['b','f']
+  a[[0,2,4]]  #=&gt; ['a','c','e']
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000028" class="method-detail">
+        <a name="M000028"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000028.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000028.html');return false;">
+          <span class="method-name">[]=</span><span class="method-args">(*args)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Add slicing to element assignment operator. If an <a
+href="Array.html">Array</a> is passed as the assignment then each element
+will be assigned to the corresponding index. The shorter of the two
+determine how many to assign.
+</p>
+<pre>
+  require &quot;facet/array/[]&quot;
+
+  h = [1,2,3]
+
+  h[0,1] = [10,11]       #=&gt; [10,11]
+  h                      #=&gt; [10,11,3]
+
+  h[0,1] = [12,13,14]    #=&gt; [12,13]
+  h                      #=&gt; [12,13,3]
+
+  h[0,1] = [15]          #=&gt; [15]
+  h                      #=&gt; [15,13,3]
+</pre>
+<p>
+If any other object is passed as assignment then all indexes will be
+assigned that same object.
+</p>
+<pre>
+  h[0,1] = 99            #=&gt; [99,99]
+  h                      #=&gt; [99,99,3]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000050" class="method-detail">
+        <a name="M000050"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000050.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000050.html');return false;">
+          <span class="method-name">[]=</span><span class="method-args">(*args)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Modifies #[]= to accept an <a href="Array.html">Array</a> of indexes for
+assignment.
+</p>
+<pre>
+  require 'facet/array/[[]]'
+
+  a = ['a','b','c','d']
+
+  a[[1]] = 'x'             #=&gt; ['x']
+  a                        #=&gt; ['a','x','c','d']
+
+  a[[1,-1]] = ['m','n']    #=&gt; ['m','n']
+  a                        #=&gt; ['a','m','c','n']
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000040" class="method-detail">
+        <a name="M000040"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000040.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000040.html');return false;">
+          <span class="method-name">at_rand</span><span class="method-args">( number=nil, exclusive=true )</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Return random <em>number</em> of value(s) from an <a
+href="Array.html">Array</a>. If the <em>number</em> of elements is not
+specified (or is <tt>nil</tt>) then returns a single element, otherwise
+returns a random array of elements. By defualt the values are exclusive of
+each other, but if <em>exclusive</em> is set to <tt>false</tt>, the same
+values can be choosen more than once.
+</p>
+<p>
+When <em>exclusive</em> is <tt>true</tt> (the default) and the
+<em>number</em> given is greater than the size of the array, then all
+values are returned.
+</p>
+<pre>
+  require 'facet/array/at_rand'
+
+  [1, 2, 3, 4].at_rand           #=&gt; 2
+  [1, 2, 3, 4].at_rand(1)        #=&gt; [2]
+  [1, 2, 3, 4].at_rand(2)        #=&gt; [1,4]
+  [1, 2, 3, 4].at_rand(3)        #=&gt; [4,3,2]
+  [1, 2, 3, 4].at_rand(3,false)  #=&gt; [4,4,2]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000042" class="method-detail">
+        <a name="M000042"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000042.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000042.html');return false;">
+          <span class="method-name">at_rand!</span><span class="method-args">(number=nil)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Same as <a href="Array.html#M000040">at_rand</a>, but acts in place
+removing the element from the array. This is necessarily exclusive.
+</p>
+<pre>
+  require 'facet/array/at_rand'
+
+  a = [1,2,3,4]
+  a.at_rand!       #=&gt; 2
+  a                #=&gt; [1,3,4]
+
+  a = [1,2,3,4]
+  a.at_rand!(2)    #=&gt; [2,1]
+  a                #=&gt; [3,4]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000033" class="method-detail">
+        <a name="M000033"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000033.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000033.html');return false;">
+          <span class="method-name">body</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns array of first element upto, but not including, the last element.
+</p>
+<pre>
+  [1,2,3].body  #=&gt; [1,2]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000036" class="method-detail">
+        <a name="M000036"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000036.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000036.html');return false;">
+          <span class="method-name">delete_values</span><span class="method-args">(*values)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Delete multiple values from array.
+</p>
+<pre>
+  require 'facet/array/delete_values'
+
+  a = [1,2,3,4]
+  a.delete_values(1,2)   #=&gt; [1,2]
+  a                      #=&gt; [3,4]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000037" class="method-detail">
+        <a name="M000037"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000037.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000037.html');return false;">
+          <span class="method-name">delete_values_at</span><span class="method-args">(*selectors)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Delete multiple values from array given indexes or index range.
+</p>
+<pre>
+  require 'facet/array/delete_values'
+
+  a = [1,2,3,4]
+  a.delete_values_at(1,2)   #=&gt; [2,3]
+  a                         #=&gt; [1,4]
+  a = [1,2,3,4]
+  a.delete_values_at(0..2)  #=&gt; [1,2,3]
+  a                         #=&gt; [4]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000062" class="method-detail">
+        <a name="M000062"></a>
+
+        <div class="method-heading">
+          <span class="method-name">each_by</span><span class="method-args">(n=nil, &amp;yld)</span>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Alias for <a href="Array.html#M000061">each_slice</a>
+</p>
+        </div>
+      </div>
+
+      <div id="method-M000057" class="method-detail">
+        <a name="M000057"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000057.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000057.html');return false;">
+          <span class="method-name">each_combination</span><span class="method-args">(k=2) {|self.values_at(*idx)| ...}</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Yields the block to each unique combination of <em>n</em> elements.
+</p>
+<pre>
+  a = %w|a b c d|
+  a.each_combination(3) do |c|
+    p c
+  end
+</pre>
+<p>
+produces
+</p>
+<pre>
+  [&quot;a&quot;, &quot;b&quot;, &quot;c&quot;]
+  [&quot;a&quot;, &quot;b&quot;, &quot;d&quot;]
+  [&quot;a&quot;, &quot;c&quot;, &quot;d&quot;]
+  [&quot;b&quot;, &quot;c&quot;, &quot;d&quot;]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000061" class="method-detail">
+        <a name="M000061"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000061.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000061.html');return false;">
+          <span class="method-name">each_slice</span><span class="method-args">(n=nil, &amp;yld)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Iterates over <tt>n</tt> elements at a time. If <tt>n</tt> is not given
+then the arity of the block determines the slicing quantity.
+</p>
+<pre>
+  require 'facet/array/each_slice'
+
+  [1, 2, 3, 4].each_slice(2){ |a,b| ... }
+</pre>
+<p>
+This is a specialized version <a
+href="Enumerable.html#M000360">Enumerable#each_slice</a> but optimized
+specifically for <a href="Array.html">Array</a>.
+</p>
+        </div>
+      </div>
+
+      <div id="method-M000058" class="method-detail">
+        <a name="M000058"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000058.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000058.html');return false;">
+          <span class="method-name">each_unique_pair</span><span class="method-args">(&amp;yld)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Processes each unique pair (of indices, not value) in the array by yielding
+them to the supplied block.
+</p>
+<pre>
+  a = [1,2,3,4]
+  a.each_unique_pair{ |a,b| puts a+','+b }
+</pre>
+<p>
+produces
+</p>
+<pre>
+  1,2
+  1,3
+  1,4
+  2,3
+  2,4
+  3,4
+</pre>
+<p>
+This does not guarantee the uniqueness of values. For example:
+</p>
+<pre>
+  a = [1,2,1]
+  a.each_unique_pair{ |a,b| puts a+','+b }
+</pre>
+<p>
+prduces
+</p>
+<pre>
+  1,2
+  1,1
+  2,1
+</pre>
+<p>
+This is equivalent to <tt><a
+href="Array.html#M000057">each_combination</a>(2){ &#8230; }</tt>.
+</p>
+        </div>
+      </div>
+
+      <div id="method-M000029" class="method-detail">
+        <a name="M000029"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000029.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000029.html');return false;">
+          <span class="method-name">first=</span><span class="method-args">(x)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Change the first element.
+</p>
+<pre>
+  require 'facet/array/first&amp;last='
+
+  a = [&quot;a&quot;,&quot;y&quot;,&quot;z&quot;]
+  a.first = &quot;x&quot;
+  p a           #=&gt; [&quot;x&quot;,&quot;y&quot;,&quot;z&quot;]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000034" class="method-detail">
+        <a name="M000034"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000034.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000034.html');return false;">
+          <span class="method-name">foot</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Like last but returns the last element in an array.
+</p>
+<pre>
+  [1,2,3].foot  #=&gt; [3]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000046" class="method-detail">
+        <a name="M000046"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000046.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000046.html');return false;">
+          <span class="method-name">get</span><span class="method-args">( start, len=1 )</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Fetch values given a start index and a length.
+</p>
+<pre>
+  require 'facet/array/get'
+
+  [1,2,3,4].get(0,2)  #=&gt; [1,2]
+  [1,2,3,4].get(2,2)  #=&gt; [3,4]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000031" class="method-detail">
+        <a name="M000031"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000031.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000031.html');return false;">
+          <span class="method-name">head</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Like first but returns the first element in an array.
+</p>
+<pre>
+  [1,2,3].head  #=&gt; [1]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000045" class="method-detail">
+        <a name="M000045"></a>
+
+        <div class="method-heading">
+          <span class="method-name">index_range</span><span class="method-args">(a=nil,z=nil)</span>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Alias for <a href="Array.html#M000044">range</a>
+</p>
+        </div>
+      </div>
+
+      <div id="method-M000030" class="method-detail">
+        <a name="M000030"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000030.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000030.html');return false;">
+          <span class="method-name">last=</span><span class="method-args">(x)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Change the last element.
+</p>
+<pre>
+  require 'facet/array/first&amp;last='
+
+  a = [1,2,5]
+  a.last = 3
+  p a           #=&gt; [1,2,3]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000038" class="method-detail">
+        <a name="M000038"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000038.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000038.html');return false;">
+          <span class="method-name">last_index</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns the last index of the array. Returns nil is array has no elements.
+</p>
+<pre>
+  require 'facet/array/last_index'
+
+  [1,2,3,4,5].last_index  #=&gt; 4
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000059" class="method-detail">
+        <a name="M000059"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000059.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000059.html');return false;">
+          <span class="method-name">middle</span><span class="method-args">(offset=0)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns the middle element of an array, or the element offset from middle
+if the parameter is given. Even-sized arrays, not having an exact middle,
+return the middle-right element.
+</p>
+<pre>
+  require 'facet/array/middle'
+
+  [1,2,3,4,5].middle        #=&gt; 3
+  [1,2,3,4,5,6].middle      #=&gt; 4
+  [1,2,3,4,5,6].middle(-1)  #=&gt; 3
+</pre>
+<p>
+In other words, If there are an even number of elements the higher-indexed
+of the two center elements is indexed as orgin (0).
+</p>
+        </div>
+      </div>
+
+      <div id="method-M000043" class="method-detail">
+        <a name="M000043"></a>
+
+        <div class="method-heading">
+          <span class="method-name">pick</span><span class="method-args">(number=nil)</span>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Alias for <a href="Array.html#M000042">at_rand!</a>
+</p>
+        </div>
+      </div>
+
+      <div id="method-M000051" class="method-detail">
+        <a name="M000051"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000051.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000051.html');return false;">
+          <span class="method-name">pos</span><span class="method-args">(i)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns positive index of an element based on cardinal positions 1 to n and
+n to -1.
+</p>
+<pre>
+  require 'facet/array/pos'
+
+  [1,2,3,4,5].pos(1)   #=&gt; 0
+  [1,2,3,4,5].pos(-1)  #=&gt; 4
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000041" class="method-detail">
+        <a name="M000041"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000041.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000041.html');return false;">
+          <span class="method-name">rand_index</span><span class="method-args">( number=nil, exclusive=true )</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Return random index(es) from an <a href="Array.html">Array</a>. If the
+<em>number</em> of elements is not specified (or is <tt>nil</tt>) then
+returns just a single index.
+</p>
+<p>
+When <em>exclusive</em> is <tt>true</tt> (the default) and the
+<em>number</em> given is greater than the size of the array, then all
+indexes are returned.
+</p>
+<pre>
+  require 'facet/array/at_rand'
+
+  [&quot;a&quot;, &quot;b&quot;, &quot;c&quot;, &quot;d&quot;].rand_index           #=&gt; 1
+  [&quot;a&quot;, &quot;b&quot;, &quot;c&quot;, &quot;d&quot;].rand_index           #=&gt; 2
+  [&quot;a&quot;, &quot;b&quot;, &quot;c&quot;, &quot;d&quot;].rand_index(2)        #=&gt; [2,1]
+  [&quot;a&quot;, &quot;b&quot;, &quot;c&quot;, &quot;d&quot;].rand_index(3)        #=&gt; [1,3,2]
+  [&quot;a&quot;, &quot;b&quot;, &quot;c&quot;, &quot;d&quot;].rand_index(3,false)  #=&gt; [4,3,4]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000044" class="method-detail">
+        <a name="M000044"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000044.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000044.html');return false;">
+          <span class="method-name">range</span><span class="method-args">(a=nil,z=nil)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns the index range between two elements. If no elements are given,
+returns the range from first to last.
+</p>
+<pre>
+  require 'facet/array/range'
+
+  ['a','b','c','d'].range            #=&gt; 0..3
+  ['a','b','c','d'].range('b','d')   #=&gt; 1..2
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000052" class="method-detail">
+        <a name="M000052"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000052.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000052.html');return false;">
+          <span class="method-name">rotate</span><span class="method-args">(n=1)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Rotates an array&#8217;s elements from back to front n times.
+</p>
+<pre>
+  require 'facet/array/rotate'
+
+  [1,2,3].rotate      #=&gt; [3,1,2]
+  [3,1,2].rotate      #=&gt; [2,3,1]
+  [3,1,2].rotate      #=&gt; [1,2,3]
+  [1,2,3].rotate(3)   #=&gt; [1,2,3]
+</pre>
+<p>
+A negative parameter reverses the order from front to back.
+</p>
+<pre>
+  [1,2,3].rotate(-1)  #=&gt; [2,3,1]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000053" class="method-detail">
+        <a name="M000053"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000053.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000053.html');return false;">
+          <span class="method-name">rotate!</span><span class="method-args">(n=1)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Same as <a href="Array.html#M000052">rotate</a>, but acts in place.
+</p>
+<pre>
+  require 'facet/array/rotate'
+
+  a = [1,2,3]
+  a.rotate
+  a  #=&gt; [3,1,2]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000035" class="method-detail">
+        <a name="M000035"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000035.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000035.html');return false;">
+          <span class="method-name">select!</span><span class="method-args">( {|| ...}</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+As with select but modifies the <a href="Array.html">Array</a> in place.
+</p>
+<pre>
+  require 'facet/array/select!'
+
+  a = [1,2,3,4,5,6,7,8,9,10]
+  a.select!{ |e| e % 2 == 0 }
+  a  #=&gt; [2,4,6,8,10]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000054" class="method-detail">
+        <a name="M000054"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000054.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000054.html');return false;">
+          <span class="method-name">shuffle</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Randomize the order of an array.
+</p>
+<pre>
+  require 'facet/array/shuffle'
+
+  [1,2,3,4].shuffle  #=&gt; [2,4,1,3]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000055" class="method-detail">
+        <a name="M000055"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000055.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000055.html');return false;">
+          <span class="method-name">shuffle!</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+As with <a href="Array.html#M000054">shuffle</a> but modifies the array in
+place. The algorithm used here is known as a Fisher-Yates shuffle.
+</p>
+<pre>
+  require 'facet/array/shuffle'
+
+  a = [1,2,3,4]
+  a.shuffle!
+  a  #=&gt; [2,4,1,3]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000060" class="method-detail">
+        <a name="M000060"></a>
+
+        <div class="method-heading">
+          <span class="method-name">store</span><span class="method-args">(*args)</span>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Alias for #[]=
+</p>
+        </div>
+      </div>
+
+      <div id="method-M000032" class="method-detail">
+        <a name="M000032"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000032.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000032.html');return false;">
+          <span class="method-name">tail</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Returns an array from second element to last element.
+</p>
+<pre>
+  [1,2,3].foot  #=&gt; [2,3]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000039" class="method-detail">
+        <a name="M000039"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000039.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000039.html');return false;">
+          <span class="method-name">thru</span><span class="method-args">( from, to )</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Fetch values from a start index thru an end index.
+</p>
+<pre>
+  require 'facet/array/upto'
+
+  [1,2,3,4,5].thru(0,2)  #=&gt; [1,2,3]
+  [1,2,3,4,5].thru(2,4)  #=&gt; [3,4,5]
+</pre>
+        </div>
+      </div>
+
+      <div id="method-M000047" class="method-detail">
+        <a name="M000047"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000047.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000047.html');return false;">
+          <span class="method-name">to_b</span><span class="method-args">()</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Boolean conversion for not empty?
+</p>
+        </div>
+      </div>
+
+      <div id="method-M000048" class="method-detail">
+        <a name="M000048"></a>
+
+        <div class="method-heading">
+          <a href="Array.src/M000048.html" target="Code" class="method-signature"
+            onclick="popupCode('Array.src/M000048.html');return false;">
+          <span class="method-name">to_h</span><span class="method-args">(values=nil)</span>
+          </a>
+        </div>
+      
+        <div class="method-description">
+          <p>
+Produces a hash for an <a href="Array.html">Array</a>, or two arrays.
+</p>
+<p>
+If no parameter is given, <a href="Array.html#M000048">to_h</a> expects the
+receiving array to be associative.
+</p>
+<pre>
+  require 'facet/array/to_h'
+
+  a1 = [ [:a,1], [:b,2] ]
+  a1.to_h  #=&gt; { :a=&gt;1, :b=&gt;2 }
+</pre>
+<p>
+If an array is given it is considered values and zipped with the receiver,
+to produce the hash.
+</p>
+<pre>
+  a1 = [ :a, :b ]
+  a2 = [ 1, 2 ]
+  a1.to_h(a2)  #=&gt; { :a=&gt;1, :b=&gt;2 }
+</pre>
+        </div>
+      </div>
+
+
+    </div>
+
+
+  </div>
+
+
+<div id="validator-badges">
+  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+</div>
+
+</body>
+</html>