[tor-commits] [stem/master] Adding join() function to the str_tools module

[atagar at torproject.org]

commit 42f02bf3371f0b45f04ed47001f05a2d4effb7f7
Author: Damian Johnson <atagar at torproject.org>
Date:   Wed Sep 17 10:10:34 2014 -0700

    Adding join() function to the str_tools module
    
    Function to greatly simplify 'gimme this string joined just up to a given
    point'. Basic test coverage via its doctests.
---
 docs/change_log.rst    |    1 +
 stem/util/str_tools.py |   39 +++++++++++++++++++++++++++++++++++++++
 test/unit/doctest.py   |    1 +
 3 files changed, 41 insertions(+)

diff --git a/docs/change_log.rst b/docs/change_log.rst
index ff5b60d..c5867e4 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -58,6 +58,7 @@ The following are only available within Stem's `git repository
   * Added support for directories to :func:`stem.util.conf.Config.load`.
   * Changed :func:`stem.util.conf.uses_settings` to only provide a 'config' keyword arument if the decorated function would accept it.
   * Added :func:`stem.util.str_tools.crop`
+  * Added :func:`stem.util.str_tools.join`
   * Added :func:`stem.util.proc.file_descriptors_used`
   * Dropped the 'get_*' prefix from most function names. Old names will still work, but are a deprecated alias.
 
diff --git a/stem/util/str_tools.py b/stem/util/str_tools.py
index 16681d5..d669753 100644
--- a/stem/util/str_tools.py
+++ b/stem/util/str_tools.py
@@ -13,6 +13,7 @@ Toolkit for various string activity.
 ::
 
   crop - shortens string to a given length
+  join - joins a series of strings up to a given length
 
   size_label - human readable label for a number of bytes
   time_label - human readable label for a number of seconds
@@ -257,6 +258,44 @@ def crop(msg, size, min_word_length = 4, min_crop = 0, ending = Ending.ELLIPSE,
   return (return_msg, remainder) if get_remainder else return_msg
 
 
+def join(entries, joiner = ' ', size = None):
+  """
+  Joins a series of strings similar to str.join(), but only up to a given size.
+  This returns an empty string if none of the entries will fit. For example...
+
+    >>> join(['This', 'is', 'a', 'looooong', 'message'], size = 18)
+    'This is a looooong'
+
+    >>> join(['This', 'is', 'a', 'looooong', 'message'], size = 17)
+    'This is a'
+
+    >>> join(['This', 'is', 'a', 'looooong', 'message'], size = 2)
+    ''
+
+  :param list entries: strings to be joined
+  :param str joiner: strings to join the entries with
+  :param int size: maximum length the result can be, there's no length
+    limitation if **None**
+
+  :returns: **str** of the joined entries up to the given length
+  """
+
+  if size is None:
+    return joiner.join(entries)
+
+  result = ''
+
+  for entry in entries:
+    new_result = joiner.join((result, entry)) if result else entry
+
+    if len(new_result) > size:
+      break
+    else:
+      result = new_result
+
+  return result
+
+
 def size_label(byte_count, decimal = 0, is_long = False, is_bytes = True):
   """
   Converts a number of bytes into a human readable label in its most
diff --git a/test/unit/doctest.py b/test/unit/doctest.py
index e3e53d8..090b273 100644
--- a/test/unit/doctest.py
+++ b/test/unit/doctest.py
@@ -60,6 +60,7 @@ class TestDocumentation(unittest.TestCase):
         args['globs'] = {
           '_to_camel_case': stem.util.str_tools._to_camel_case,
           'crop': stem.util.str_tools.crop,
+          'join': stem.util.str_tools.join,
           'size_label': stem.util.str_tools.size_label,
           'time_label': stem.util.str_tools.time_label,
           'time_labels': stem.util.str_tools.time_labels,