Added django.contrib.humanize, a set of template tags for adding a 'human touch' to data. They're documented in add_ons.txt.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@3076 bcc190cf-cafb-0310-a4f2-bffc1f526a37

5 files changed, 125 insertions, 0 deletions

diff --git a/django/contrib/humanize/__init__.py b/django/contrib/humanize/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/django/contrib/humanize/__init__.py
diff --git a/django/contrib/humanize/templatetags/__init__.py b/django/contrib/humanize/templatetags/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/django/contrib/humanize/templatetags/__init__.py
diff --git a/django/contrib/humanize/templatetags/humanize.py b/django/contrib/humanize/templatetags/humanize.py
new file mode 100644
index 0000000000..d3170f3116
--- /dev/null
+++ b/django/contrib/humanize/templatetags/humanize.py
@@ -0,0 +1,50 @@
+from django import template
+import re
+
+register = template.Library()
+
+def ordinal(value):
+    """
+    Converts an integer to its ordinal as a string. 1 is '1st', 2 is '2nd',
+    3 is '3rd', etc. Works for any integer.
+    """
+    try:
+        value = int(value)
+    except ValueError:
+        return value
+    t = ('th', 'st', 'nd', 'rd', 'th', 'th', 'th', 'th', 'th', 'th')
+    if value % 100 in (11, 12, 13): # special case
+        return '%dth' % value
+    return '%d%s' % (value, t[value % 10])
+register.filter(ordinal)
+
+def intcomma(value):
+    """
+    Converts an integer to a string containing commas every three digits.
+    For example, 3000 becomes '3,000' and 45000 becomes '45,000'.
+    """
+    orig = str(value)
+    new = re.sub("^(-?\d+)(\d{3})", '\g<1>,\g<2>', str(value))
+    if orig == new:
+        return new
+    else:
+        return intcomma(new)
+register.filter(intcomma)
+
+def intword(value):
+    """
+    Converts a large integer to a friendly text representation. Works best for
+    numbers over 1 million. For example, 1000000 becomes '1.0 million', 1200000
+    becomes '1.2 million' and '1200000000' becomes '1.2 billion'.
+    """
+    value = int(value)
+    if value < 1000000:
+        return value
+    if value < 1000000000:
+        return '%.1f million' % (value / 1000000.0)
+    if value < 1000000000000:
+        return '%.1f billion' % (value / 1000000000.0)
+    if value < 1000000000000000:
+        return '%.1f trillion' % (value / 1000000000000.0)
+    return value
+register.filter(intword)
diff --git a/docs/add_ons.txt b/docs/add_ons.txt
index f7b3056ef0..bcc2f50a7f 100644
--- a/docs/add_ons.txt
+++ b/docs/add_ons.txt
@@ -45,6 +45,57 @@ See the `csrf documentation`_.
 
 .. _csrf documentation: http://www.djangoproject.com/documentation/csrf/
 
+humanize
+========
+
+A set of Django template filters useful for adding a "human touch" to data.
+To activate these filters, add ``'django.contrib.english'`` to your
+``INSTALLED_APPS`` setting. Once you've done that, use ``{% load english %}``
+in a template, and you'll have access to these filters:
+
+ordinal
+-------
+
+Converts an integer to its ordinal as a string.
+
+Examples:
+
+    * ``1`` becomes ``'1st'``.
+    * ``2`` becomes ``'2nd'``.
+    * ``3`` becomes ``'3rd'``.
+
+You can pass in either an integer or a string representation of an integer.
+
+intcomma
+--------
+
+Converts an integer to a string containing commas every three digits.
+
+Examples:
+
+    * ``4500`` becomes ``'4,500'``.
+    * ``45000`` becomes ``'45,000'``.
+    * ``450000`` becomes ``'450,000'``.
+    * ``4500000`` becomes ``'4,500,000'``.
+
+You can pass in either an integer or a string representation of an integer.
+
+intword
+-------
+
+Converts a large integer to a friendly text representation. Works best for
+numbers over 1 million.
+
+Examples:
+
+    * ``1000000`` becomes ``'1.0 million'``.
+    * ``1200000`` becomes ``'1.2 million'``.
+    * ``1200000000`` becomes ``'1.2 billion'``.
+
+Values up to 1000000000000000 (one quadrillion) are supported.
+
+You can pass in either an integer or a string representation of an integer.
+
 flatpages
 =========
 
diff --git a/docs/templates.txt b/docs/templates.txt
index 8d5a383b8c..c191b409f4 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -1091,3 +1091,27 @@ Value       Argument                Outputs
 ``None``    ``"yeah,no"``           ``"no"`` (converts None to False
                                     if no mapping for None is given)
 ==========  ======================  ==================================
+
+Other tags and filter libraries
+===============================
+
+Django comes with a couple of other template-tag libraries that you have to
+enable explicitly in your ``INSTALLED_APPS`` setting and enable in your
+template with the ``{% load %}`` tag.
+
+django.contrib.humanize
+-----------------------
+
+A set of Django template filters useful for adding a "human touch" to data. See
+the `humanize documentation`_.
+
+.. _humanize documentation: http://www.djangoproject.com/documentation/add_ons/#humanize
+
+django.contrib.markup
+---------------------
+
+A collection of template filters that implement these common markup languages:
+
+    * Textile
+    * Markdown
+    * ReST (ReStructured Text)