python/lib/django_1_4/docs/ref/contrib/humanize.txt

   1 ========================
   2 django.contrib.humanize
   3 ========================
   4
   5 .. module:: django.contrib.humanize
   6    :synopsis: A set of Django template filters useful for adding a "human
   7               touch" to data.
   8
   9 A set of Django template filters useful for adding a "human touch" to data.
  10
  11 To activate these filters, add ``'django.contrib.humanize'`` to your
  12 :setting:`INSTALLED_APPS` setting. Once you've done that, use
  13 ``{% load humanize %}`` in a template, and you'll have access to the following
  14 filters.
  15
  16 .. templatefilter:: apnumber
  17
  18 apnumber
  19 --------
  20
  21 For numbers 1-9, returns the number spelled out. Otherwise, returns the
  22 number. This follows Associated Press style.
  23
  24 Examples:
  25
  26 * ``1`` becomes ``one``.
  27 * ``2`` becomes ``two``.
  28 * ``10`` becomes ``10``.
  29
  30 You can pass in either an integer or a string representation of an integer.
  31
  32 .. templatefilter:: intcomma
  33
  34 intcomma
  35 --------
  36
  37 Converts an integer to a string containing commas every three digits.
  38
  39 Examples:
  40
  41 * ``4500`` becomes ``4,500``.
  42 * ``45000`` becomes ``45,000``.
  43 * ``450000`` becomes ``450,000``.
  44 * ``4500000`` becomes ``4,500,000``.
  45
  46 :ref:`Format localization <format-localization>` will be respected if enabled,
  47 e.g. with the ``'de'`` language:
  48
  49 * ``45000`` becomes ``'45.000'``.
  50 * ``450000`` becomes ``'450.000'``.
  51
  52 You can pass in either an integer or a string representation of an integer.
  53
  54 .. templatefilter:: intword
  55
  56 intword
  57 -------
  58
  59 Converts a large integer to a friendly text representation. Works best for
  60 numbers over 1 million.
  61
  62 Examples:
  63
  64 * ``1000000`` becomes ``1.0 million``.
  65 * ``1200000`` becomes ``1.2 million``.
  66 * ``1200000000`` becomes ``1.2 billion``.
  67
  68 Values up to 10^100 (Googol) are supported.
  69
  70 :ref:`Format localization <format-localization>` will be respected if enabled,
  71 e.g. with the ``'de'`` language:
  72
  73 * ``1000000`` becomes ``'1,0 Million'``.
  74 * ``1200000`` becomes ``'1,2 Million'``.
  75 * ``1200000000`` becomes ``'1,2 Milliarden'``.
  76
  77 You can pass in either an integer or a string representation of an integer.
  78
  79 .. templatefilter:: naturalday
  80
  81 naturalday
  82 ----------
  83
  84 For dates that are the current day or within one day, return "today",
  85 "tomorrow" or "yesterday", as appropriate. Otherwise, format the date using
  86 the passed in format string.
  87
  88 **Argument:** Date formatting string as described in the :tfilter:`date` tag.
  89
  90 Examples (when 'today' is 17 Feb 2007):
  91
  92 * ``16 Feb 2007`` becomes ``yesterday``.
  93 * ``17 Feb 2007`` becomes ``today``.
  94 * ``18 Feb 2007`` becomes ``tomorrow``.
  95 * Any other day is formatted according to given argument or the
  96   :setting:`DATE_FORMAT` setting if no argument is given.
  97
  98 .. templatefilter:: naturaltime
  99
 100 naturaltime
 101 -----------
 102
 103 .. versionadded:: 1.4
 104
 105 For datetime values, returns a string representing how many seconds,
 106 minutes or hours ago it was -- falling back to the :tfilter:`timesince`
 107 format if the value is more than a day old. In case the datetime value is in
 108 the future the return value will automatically use an appropriate phrase.
 109
 110 Examples (when 'now' is 17 Feb 2007 16:30:00):
 111
 112 * ``17 Feb 2007 16:30:00`` becomes ``now``.
 113 * ``17 Feb 2007 16:29:31`` becomes ``29 seconds ago``.
 114 * ``17 Feb 2007 16:29:00`` becomes ``a minute ago``.
 115 * ``17 Feb 2007 16:25:35`` becomes ``4 minutes ago``.
 116 * ``17 Feb 2007 15:30:29`` becomes ``an hour ago``.
 117 * ``17 Feb 2007 13:31:29`` becomes ``2 hours ago``.
 118 * ``16 Feb 2007 13:31:29`` becomes ``1 day, 3 hours ago``.
 119 * ``17 Feb 2007 16:30:30`` becomes ``29 seconds from now``.
 120 * ``17 Feb 2007 16:31:00`` becomes ``a minute from now``.
 121 * ``17 Feb 2007 16:34:35`` becomes ``4 minutes from now``.
 122 * ``17 Feb 2007 16:30:29`` becomes ``an hour from now``.
 123 * ``17 Feb 2007 18:31:29`` becomes ``2 hours from now``.
 124 * ``18 Feb 2007 16:31:29`` becomes ``1 day from now``.
 125 * ``26 Feb 2007 18:31:29`` becomes ``1 week, 2 days from now``.
 126
 127 .. templatefilter:: ordinal
 128
 129 ordinal
 130 -------
 131
 132 Converts an integer to its ordinal as a string.
 133
 134 Examples:
 135
 136 * ``1`` becomes ``1st``.
 137 * ``2`` becomes ``2nd``.
 138 * ``3`` becomes ``3rd``.
 139
 140 You can pass in either an integer or a string representation of an integer.