icemac.truncatetext 1.1.1
Nice, intelligent truncation of text.
License: MIT
Keywords: text truncate string intelligent

Nice, intelligent truncation of text.

.. image:: https://travis-ci.com/icemac/icemac.truncatetext.svg?branch=master
    :target: https://travis-ci.com/icemac/icemac.truncatetext

.. image:: https://coveralls.io/repos/github/icemac/icemac.truncatetext/badge.svg?branch=travis
    :target: https://coveralls.io/github/icemac/icemac.truncatetext?branch=travis

.. image:: https://img.shields.io/pypi/v/icemac.truncatetext.svg
        :target: https://pypi.org/project/icemac.truncatetext/
        :alt: Current version on PyPI

.. image:: https://img.shields.io/pypi/pyversions/icemac.truncatetext.svg
        :target: https://pypi.org/project/icemac.truncatetext/
        :alt: Supported Python versions


Fork me on: https://github.com/icemac/icemac.truncatetext


.. contents::

Nicely truncate text
====================

Intelligent truncation of text means that truncation does not take
place inside a word but only between words. So the required length is
only an approximation. The result text might be a bit longer than the
required length:

  >>> from icemac.truncatetext import truncate
  >>> 'I was here.'[:3]
  'I w'
  >>> truncate('I was here.', 3)
  'I was ...'

What can get truncated?
-----------------------

Only instances of ``basestring`` (``str`` on Python 3) can be truncated:

  >>> truncate(3, 3)
  Traceback (most recent call last):
  ValueError: 3 is no instance of basestring or None
  >>> print(truncate(u'Lorem ipsum', 5))
  Lorem ...

``None`` is handled nicely:

  >>> truncate(None, 4)
  ''

What is returned?
-----------------

Always at least one word is returned even when it is longer than the
required length:

  >>> truncate('Lorem ipsum', 1)
  'Lorem ...'

If the text contains only of one word which is longer than the desired
length it is returned without an ellipsis:

  >>> truncate('The-really-long-word', 5)
  'The-really-long-word'

If the text is shorter than the desired length it is returned without
the ellipsis, too:

  >>> truncate('Lorem ipsum', 11)
  'Lorem ipsum'

Where gets the text truncated?
------------------------------

Truncation also takes place at tabs and linebreaks:

  >>> truncate("I was here.\nNow I'm away", 11)
  'I was here. ...'
  >>> truncate("I was here.\rNow I'm away", 12)
  'I was here.\rNow ...'
  >>> truncate("I was here.\tNow I'm away", 11)
  'I was here. ...'

I do not want `...` as ellipsis.
--------------------------------

``truncate`` takes an optional argument which defines the ellipsis string:

  >>> print(truncate(u'Lorem ipsum', 5, ellipsis=u':::'))
  Lorem :::



Changelog
=========

1.1.1 (2018-11-16)
------------------

- Move repository to Github.


1.1 (2018-11-15)
----------------

- Add support for Python 3.7.


1.0.post1 (2017-06-22)
----------------------

- Fix the `description` so PyPI accepts it.


1.0 (2017-05-13)
----------------

- Add support for Python 3.4 up to 3.6, PyPy2 and PyPy3.

- Drop support for Python 2.5 and 2.6.

- Change license from ZPL to MIT.


0.3 (2012-11-13)
----------------

- Moved sources to bitbucket.org.

- Added Travis-CI.

- Dropped official support for Python 2.3 and Python 2.4. (Although these
  rather old Python versions still might be used with this release.)


0.2.1 (2011-07-28)
------------------

- Updated categories: Python 2.7 is supported, too.


0.2 (2009-09-26)
----------------

- Added ability pass a string used as ellipsis string.


0.1 (2009-01-31)
----------------

- Initial public release.



Hacking
=======

Fork me on `bitbucket.org`_ or put your issues to the `issue tracker`_.

.. .. image:: https://secure.travis-ci.org/icemac/icemac.truncatetext.png

.. _`bitbucket.org` : https://bitbucket.org/icemac/icemac.truncatetext
.. _`issue tracker` : https://bitbucket.org/icemac/icemac.truncatetext/issues