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)