From fb537e177d7d304d6642ee6005258a82584a8032 Mon Sep 17 00:00:00 2001
From: Adrian Holovaty <adrian@holovaty.com>
Date: Sun, 4 Jun 2006 00:58:39 +0000
Subject: [PATCH] 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
---
django/contrib/humanize/__init__.py | 0
.../contrib/humanize/templatetags/__init__.py | 0
.../contrib/humanize/templatetags/humanize.py | 50 ++++++++++++++++++
docs/add_ons.txt | 51 +++++++++++++++++++
docs/templates.txt | 24 +++++++++
5 files changed, 125 insertions(+)
create mode 100644 django/contrib/humanize/__init__.py
create mode 100644 django/contrib/humanize/templatetags/__init__.py
create mode 100644 django/contrib/humanize/templatetags/humanize.py
diff --git a/django/contrib/humanize/__init__.py b/django/contrib/humanize/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/django/contrib/humanize/templatetags/__init__.py b/django/contrib/humanize/templatetags/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
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)