From a764de50add31b608bb634b11808e670229c61ad Mon Sep 17 00:00:00 2001
From: Jeremy Fincher <jemfinch@users.sourceforge.net>
Date: Wed, 3 Sep 2003 08:51:45 +0000
Subject: [PATCH] Added sortBy, which uses the decorate/sort/undecorate pattern
 to sort by a certain criteria.

---
 src/utils.py       | 17 +++++++++++++++++
 test/test_utils.py |  7 +++++++
 2 files changed, 24 insertions(+)

diff --git a/src/utils.py b/src/utils.py
index 4f1bd3518..081fd4ce0 100755
--- a/src/utils.py
+++ b/src/utils.py
@@ -265,6 +265,10 @@ def findBinaryInPath(s):
     return cmdLine
 
 def commaAndify(seq):
+    """Given a a sequence, returns an english clause for that sequence.
+
+    I.e., given [1, 2, 3], returns '1, 2, and 3'
+    """
     L = list(seq)
     if len(L) == 0:
         return ''
@@ -278,6 +282,7 @@ def commaAndify(seq):
 
 _unCommaTheRe = re.compile(r'(.*),\s*(the)$', re.I)
 def unCommaThe(s):
+    """Takes a string of the form 'foo, the' and turns it into 'the foo'."""
     m = _unCommaTheRe.match(s)
     if m is not None:
         return '%s %s' % (m.group(2), m.group(1))
@@ -285,6 +290,7 @@ def unCommaThe(s):
         return s
 
 def wrapLines(s):
+    """Word wraps several paragraphs in a string s."""
     L = []
     for line in s.splitlines():
         L.append(textwrap.fill(line))
@@ -292,6 +298,9 @@ def wrapLines(s):
 
 plurals = {}
 def pluralize(i, s):
+    """Returns the plural of s based on its number i.  Put any exceptions to
+    the general English rule of appending 's' in the plurals dictionary.
+    """
     if i == 1:
         return s
     else:
@@ -301,10 +310,18 @@ def pluralize(i, s):
             return s + 's'
 
 def be(i):
+    """Returns the form of the verb 'to be' based on the number i."""
     if i == 1:
         return 'is'
     else:
         return 'are'
 
+def sortBy(f, L, cmp=cmp):
+    """Uses the decorate-sort-undecorate pattern to sort L by function f."""
+    for (i, elt) in enumerate(L):
+        L[i] = (f(elt), elt)
+    L.sort(cmp)
+    for (i, elt) in enumerate(L):
+        L[i] = L[i][1]
 
 # vim:set shiftwidth=4 tabstop=8 expandtab textwidth=78:
diff --git a/test/test_utils.py b/test/test_utils.py
index a2ee147ed..3cc5531c1 100644
--- a/test/test_utils.py
+++ b/test/test_utils.py
@@ -162,6 +162,13 @@ class UtilsTest(unittest.TestCase):
         self.assertEqual(utils.normalizeWhitespace('foo   bar'), 'foo bar')
         self.assertEqual(utils.normalizeWhitespace('foo\nbar'), 'foo bar')
         self.assertEqual(utils.normalizeWhitespace('foo\tbar'), 'foo bar')
+
+    def testSortBy(self):
+        L = ['abc', 'z', 'AD']
+        utils.sortBy(len, L)
+        self.assertEqual(L, ['z', 'AD', 'abc'])
+        utils.sortBy(str.lower, L)
+        self.assertEqual(L, ['abc', 'AD', 'z'])
         
 # vim:set shiftwidth=4 tabstop=8 expandtab textwidth=78: