Add function to truncate strings.

Author: domdfcoding

doc-source/api/words.rst

@@ -112,9 +112,9 @@ Functions
 .. autofunction:: domdf_python_tools.words.get_words_list
 .. autofunction:: domdf_python_tools.words.get_random_word
 .. autofunction:: domdf_python_tools.words.word_join
-
-
 .. latex:clearpage::
+.. autofunction:: domdf_python_tools.words.truncate_string
+
 
 Classes
 -------------

domdf_python_tools/words.py

@@ -76,6 +76,7 @@
 		"LF",
 		"Plural",
 		"PluralPhrase",
+		"truncate_string",
 		]
 
 ascii_digits = "0123456789"
@@ -685,3 +686,30 @@ def __call__(self, n: int) -> str:  # noqa: TYP004  # TODO
 
 		plural_words = [x(n) for x in self.words]
 		return self.template.format(*plural_words, n=n)
+
+
+@functools.lru_cache()
+def _slice_end(max_length: int, ending: str = "...") -> slice:
+	slice_end = max_length - len(ending)
+	return slice(slice_end)
+
+
+def truncate_string(string: str, max_length: int, ending: str = "...") -> str:
+	"""
+	Truncate a string to ``max_length`` characters, and put ``ending`` on the end.
+
+	The truncated string is further truncated by the length of ``ending`` so the returned string is no more then ``max_length``.
+
+	.. versionadded:: 3.3.0
+
+	:param string:
+	:param max_length:
+	:param ending:
+	"""
+
+	string_length = len(string)
+
+	if string_length > max_length:
+		return string[_slice_end(max_length, ending)] + ending
+	else:
+		return string

tests/test_words.py

@@ -18,7 +18,8 @@
 		PluralPhrase,
 		alpha_sort,
 		get_random_word,
-		get_words_list
+		get_words_list,
+		truncate_string
 		)
 
 
@@ -208,3 +209,11 @@ def test_pluralphrase():
 	assert repr(phrase3) == phrase3_repr
 	phrase4_repr = "PluralPhrase(template='The farmer has {n} {0}. The {0} {1} brown.', words=(Plural('cow', 'cows'), Plural('is', 'are')))"
 	assert repr(phrase4) == phrase4_repr
+
+
+def test_truncate():
+	message = "hello world this is a very long sentance with no point"
+	assert truncate_string(message, 20) == "hello world this ..."
+	assert truncate_string(message, 30) == "hello world this is a very ..."
+	assert truncate_string(message, 30, '…') == "hello world this is a very lo…"
+	assert truncate_string(message, 200, '…') == message