← Back to branch summary

~ubuntu-branches/ubuntu/lucid/python2.6/lucid

« back to all changes in this revision

Viewing changes to Doc/library/string.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-04-08 02:29:05 UTC
  • mto: (10.1.3 experimental)
  • mto: This revision was merged to the branch mainline in revision 23.
  • Revision ID: james.westby@ubuntu.com-20090408022905-xa5zbe8821m2o77o
Tags: upstream-2.6.2~rc1
Import upstream version 2.6.2~rc1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/string.rst
62
62
.. data:: lowercase
63
63
 
64
64
   A string containing all the characters that are considered lowercase letters.
65
 
   On most systems this is the string ``'abcdefghijklmnopqrstuvwxyz'``.  Do not
66
 
   change its definition --- the effect on the routines :func:`upper` and
67
 
   :func:`swapcase` is undefined.  The specific value is locale-dependent, and will
68
 
   be updated when :func:`locale.setlocale` is called.
 
65
   On most systems this is the string ``'abcdefghijklmnopqrstuvwxyz'``.  The
 
66
   specific value is locale-dependent, and will be updated when
 
67
   :func:`locale.setlocale` is called.
69
68
 
70
69
 
71
70
.. data:: octdigits
89
88
.. data:: uppercase
90
89
 
91
90
   A string containing all the characters that are considered uppercase letters.
92
 
   On most systems this is the string ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``.  Do not
93
 
   change its definition --- the effect on the routines :func:`lower` and
94
 
   :func:`swapcase` is undefined.  The specific value is locale-dependent, and will
95
 
   be updated when :func:`locale.setlocale` is called.
 
91
   On most systems this is the string ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``.  The
 
92
   specific value is locale-dependent, and will be updated when
 
93
   :func:`locale.setlocale` is called.
96
94
 
97
95
 
98
96
.. data:: whitespace
99
97
 
100
98
   A string containing all characters that are considered whitespace. On most
101
99
   systems this includes the characters space, tab, linefeed, return, formfeed, and
102
 
   vertical tab.  Do not change its definition --- the effect on the routines
103
 
   :func:`strip` and :func:`split` is undefined.
 
100
   vertical tab.
104
101
 
105
102
 
106
103
.. _new-string-formatting:
126
123
      :meth:`format` is just a wrapper that calls :meth:`vformat`.
127
124
 
128
125
   .. method:: vformat(format_string, args, kwargs)
129
 
   
 
126
 
130
127
      This function does the actual work of formatting.  It is exposed as a
131
128
      separate function for cases where you want to pass in a predefined
132
129
      dictionary of arguments, rather than unpacking and repacking the
139
136
   intended to be replaced by subclasses:
140
137
 
141
138
   .. method:: parse(format_string)
142
 
   
 
139
 
143
140
      Loop over the format_string and return an iterable of tuples
144
141
      (*literal_text*, *field_name*, *format_spec*, *conversion*).  This is used
145
142
      by :meth:`vformat` to break the string in to either literal text, or
146
143
      replacement fields.
147
 
      
 
144
 
148
145
      The values in the tuple conceptually represent a span of literal text
149
146
      followed by a single replacement field.  If there is no literal text
150
147
      (which can happen if two replacement fields occur consecutively), then
162
159
      *key* parameter to :meth:`get_value`.
163
160
 
164
161
   .. method:: get_value(key, args, kwargs)
165
 
   
 
162
 
166
163
      Retrieve a given field value.  The *key* argument will be either an
167
164
      integer or a string.  If it is an integer, it represents the index of the
168
165
      positional argument in *args*; if it is a string, then it represents a
200
197
      method is provided so that subclasses can override it.
201
198
 
202
199
   .. method:: convert_field(value, conversion)
203
 
   
 
200
 
204
201
      Converts the value (returned by :meth:`get_field`) given a conversion type
205
202
      (as in the tuple returned by the :meth:`parse` method.)  The default
206
203
      version understands 'r' (repr) and 's' (str) conversion types.
224
221
 
225
222
   .. productionlist:: sf
226
223
      replacement_field: "{" `field_name` ["!" `conversion`] [":" `format_spec`] "}"
227
 
      field_name: (`identifier` | `integer`) ("." `attribute_name` | "[" element_index "]")*
 
224
      field_name: (`identifier` | `integer`) ("." `attribute_name` | "[" `element_index` "]")*
228
225
      attribute_name: `identifier`
229
226
      element_index: `integer`
230
227
      conversion: "r" | "s"
231
228
      format_spec: <described in the next section>
232
 
      
 
229
 
233
230
In less formal terms, the replacement field starts with a *field_name*, which
234
231
can either be a number (for a positional argument), or an identifier (for
235
232
keyword arguments).  Following this is an optional *conversion* field, which is
249
246
   "My quest is {name}"             # References keyword argument 'name'
250
247
   "Weight in tons {0.weight}"      # 'weight' attribute of first positional arg
251
248
   "Units destroyed: {players[0]}"  # First element of keyword argument 'players'.
252
 
   
 
249
 
253
250
The *conversion* field causes a type coercion before formatting.  Normally, the
254
251
job of formatting a value is done by the :meth:`__format__` method of the value
255
252
itself.  However, in some cases it is desirable to force a type to be formatted
292
289
Then the outer replacement field would be evaluated, producing::
293
290
 
294
291
   "noses     "
295
 
   
 
292
 
296
293
Which is substituted into the string, yielding::
297
 
   
 
294
 
298
295
   "A man with two noses     "
299
 
   
 
296
 
300
297
(The extra space is because we specified a field width of 10, and because left
301
298
alignment is the default for strings.)
302
299
 
328
325
   width: `integer`
329
326
   precision: `integer`
330
327
   type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "x" | "X" | "%"
331
 
   
 
328
 
332
329
The *fill* character can be any character other than '}' (which signifies the
333
330
end of the field).  The presence of a fill character is signaled by the *next*
334
331
character, which must be one of the alignment options. If the second character
421
418
   +---------+----------------------------------------------------------+
422
419
   | None    | The same as ``'d'``.                                     |
423
420
   +---------+----------------------------------------------------------+
424
 
                                                                         
 
421
 
425
422
The available presentation types for floating point and decimal values are:
426
 
                                                                         
 
423
 
427
424
   +---------+----------------------------------------------------------+
428
425
   | Type    | Meaning                                                  |
429
426
   +=========+==========================================================+
599
596
 
600
597
      Don't use strings derived from :const:`lowercase` and :const:`uppercase` as
601
598
      arguments; in some locales, these don't have the same length.  For case
602
 
      conversions, always use :func:`lower` and :func:`upper`.
 
599
      conversions, always use :meth:`str.lower` and :meth:`str.upper`.
603
600
 
604
601
 
605
602
Deprecated string functions