Debian Codegraph @

docs/ref/contrib/humanize.txt

raw
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 or float (or a string representation of either) to a string
38 containing commas every three digits.
39
40 Examples:
41
42 * ``4500`` becomes ``4,500``.
43 * ``4500.2`` becomes ``4,500.2``.
44 * ``45000`` becomes ``45,000``.
45 * ``450000`` becomes ``450,000``.
46 * ``4500000`` becomes ``4,500,000``.
47
48 :doc:`/topics/i18n/formatting` will be respected if enabled,
49 e.g. with the ``'de'`` language:
50
51 * ``45000`` becomes ``'45.000'``.
52 * ``450000`` becomes ``'450.000'``.
53
54 .. templatefilter:: intword
55
56 ``intword``
57 ===========
58
59 Converts a large integer (or a string representation of an integer) to a
60 friendly text representation. Translates ``1.0`` as a singular phrase and all
61 other numeric values as plural, this may be incorrect for some languages. Works
62 best for numbers over 1 million.
63
64 Examples:
65
66 * ``1000000`` becomes ``1.0 million``.
67 * ``1200000`` becomes ``1.2 million``.
68 * ``1200000000`` becomes ``1.2 billion``.
69 * ``-1200000000`` becomes ``-1.2 billion``.
70
71 Values up to 10^100 (Googol) are supported.
72
73 :doc:`/topics/i18n/formatting` will be respected if enabled,
74 e.g. with the ``'de'`` language:
75
76 * ``1000000`` becomes ``'1,0 Million'``.
77 * ``1200000`` becomes ``'1,2 Millionen'``.
78 * ``1200000000`` becomes ``'1,2 Milliarden'``.
79 * ``-1200000000`` becomes ``'-1,2 Milliarden'``.
80
81 .. templatefilter:: naturalday
82
83 ``naturalday``
84 ==============
85
86 For dates that are the current day or within one day, return "today",
87 "tomorrow" or "yesterday", as appropriate. Otherwise, format the date using
88 the passed in format string.
89
90 **Argument:** Date formatting string as described in the :tfilter:`date` tag.
91
92 Examples (when 'today' is 17 Feb 2007):
93
94 * ``16 Feb 2007`` becomes ``yesterday``.
95 * ``17 Feb 2007`` becomes ``today``.
96 * ``18 Feb 2007`` becomes ``tomorrow``.
97 * Any other day is formatted according to given argument or the
98 :setting:`DATE_FORMAT` setting if no argument is given.
99
100 .. templatefilter:: naturaltime
101
102 ``naturaltime``
103 ===============
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 ``59 minutes ago``.
117 * ``17 Feb 2007 15:30:01`` becomes ``59 minutes ago``.
118 * ``17 Feb 2007 15:30:00`` becomes ``an hour ago``.
119 * ``17 Feb 2007 13:31:29`` becomes ``2 hours ago``.
120 * ``16 Feb 2007 13:31:29`` becomes ``1 day, 2 hours ago``.
121 * ``16 Feb 2007 13:30:01`` becomes ``1 day, 2 hours ago``.
122 * ``16 Feb 2007 13:30:00`` becomes ``1 day, 3 hours ago``.
123 * ``17 Feb 2007 16:30:30`` becomes ``30 seconds from now``.
124 * ``17 Feb 2007 16:30:29`` becomes ``29 seconds from now``.
125 * ``17 Feb 2007 16:31:00`` becomes ``a minute from now``.
126 * ``17 Feb 2007 16:34:35`` becomes ``4 minutes from now``.
127 * ``17 Feb 2007 17:30:29`` becomes ``an hour from now``.
128 * ``17 Feb 2007 18:31:29`` becomes ``2 hours from now``.
129 * ``18 Feb 2007 16:31:29`` becomes ``1 day from now``.
130 * ``26 Feb 2007 18:31:29`` becomes ``1 week, 2 days from now``.
131
132 .. templatefilter:: ordinal
133
134 ``ordinal``
135 ===========
136
137 Converts an integer to its ordinal as a string.
138
139 Examples:
140
141 * ``1`` becomes ``1st``.
142 * ``2`` becomes ``2nd``.
143 * ``3`` becomes ``3rd``.
144
145 You can pass in either an integer or a string representation of an integer.
146 Negative integers are returned unchanged.