1
# module 'string' -- A collection of string operations
3
# Warning: most of the code you see here isn't normally used nowadays. With
4
# Python 1.6, many of these functions are implemented as methods on the
5
# standard string object. They used to be implemented by a built-in module
6
# called strop, but strop is now obsolete itself.
8
"""Common string manipulations.
10
Public module variables:
12
whitespace -- a string containing all characters considered whitespace
13
lowercase -- a string containing all characters considered lowercase letters
14
uppercase -- a string containing all characters considered uppercase letters
15
letters -- a string containing all characters considered letters
16
digits -- a string containing all characters considered decimal digits
17
hexdigits -- a string containing all characters considered hexadecimal digits
18
octdigits -- a string containing all characters considered octal digits
21
from warnings import warnpy3k
22
warnpy3k("the stringold module has been removed in Python 3.0", stacklevel=2)
25
# Some strings for ctype-style character classification
26
whitespace = ' \t\n\r\v\f'
27
lowercase = 'abcdefghijklmnopqrstuvwxyz'
28
uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
29
letters = lowercase + uppercase
31
hexdigits = digits + 'abcdef' + 'ABCDEF'
32
octdigits = '01234567'
34
# Case conversion helpers
36
for i in range(256): _idmap = _idmap + chr(i)
39
# Backward compatible names for exceptions
40
index_error = ValueError
41
atoi_error = ValueError
42
atof_error = ValueError
43
atol_error = ValueError
45
# convert UPPER CASE letters to lower case
49
Return a copy of the string s converted to lowercase.
54
# Convert lower case letters to UPPER CASE
58
Return a copy of the string s converted to uppercase.
63
# Swap lower case letters and UPPER CASE
65
"""swapcase(s) -> string
67
Return a copy of the string s with upper case characters
68
converted to lowercase and vice versa.
73
# Strip leading and trailing tabs and spaces
77
Return a copy of the string s with leading and trailing
83
# Strip leading tabs and spaces
85
"""lstrip(s) -> string
87
Return a copy of the string s with leading whitespace removed.
92
# Strip trailing tabs and spaces
94
"""rstrip(s) -> string
96
Return a copy of the string s with trailing whitespace
103
# Split a string into a list of space/tab-separated words
104
def split(s, sep=None, maxsplit=0):
105
"""split(str [,sep [,maxsplit]]) -> list of strings
107
Return a list of the words in the string s, using sep as the
108
delimiter string. If maxsplit is nonzero, splits into at most
109
maxsplit words If sep is not specified, any whitespace string
110
is a separator. Maxsplit defaults to 0.
112
(split and splitfields are synonymous)
115
return s.split(sep, maxsplit)
118
# Join fields with optional separator
119
def join(words, sep = ' '):
120
"""join(list [,sep]) -> string
122
Return a string composed of the words in list, with
123
intervening occurrences of sep. The default separator is a
126
(joinfields and join are synonymous)
129
return sep.join(words)
132
# for a little bit of speed
135
# Find substring, raise exception if not found
137
"""index(s, sub [,start [,end]]) -> int
139
Like find but raises ValueError when the substring is not found.
142
return _apply(s.index, args)
144
# Find last substring, raise exception if not found
145
def rindex(s, *args):
146
"""rindex(s, sub [,start [,end]]) -> int
148
Like rfind but raises ValueError when the substring is not found.
151
return _apply(s.rindex, args)
153
# Count non-overlapping occurrences of substring
155
"""count(s, sub[, start[,end]]) -> int
157
Return the number of occurrences of substring sub in string
158
s[start:end]. Optional arguments start and end are
159
interpreted as in slice notation.
162
return _apply(s.count, args)
164
# Find substring, return -1 if not found
166
"""find(s, sub [,start [,end]]) -> in
168
Return the lowest index in s where substring sub is found,
169
such that sub is contained within s[start,end]. Optional
170
arguments start and end are interpreted as in slice notation.
172
Return -1 on failure.
175
return _apply(s.find, args)
177
# Find last substring, return -1 if not found
179
"""rfind(s, sub [,start [,end]]) -> int
181
Return the highest index in s where substring sub is found,
182
such that sub is contained within s[start,end]. Optional
183
arguments start and end are interpreted as in slice notation.
185
Return -1 on failure.
188
return _apply(s.rfind, args)
194
_StringType = type('')
196
# Convert string to float
200
Return the floating point number represented by the string s.
203
if type(s) == _StringType:
206
raise TypeError('argument 1: expected string, %s found' %
209
# Convert string to integer
211
"""atoi(s [,base]) -> int
213
Return the integer represented by the string s in the given
214
base, which defaults to 10. The string s must consist of one
215
or more digits, possibly preceded by a sign. If base is 0, it
216
is chosen from the leading characters of s, 0 for octal, 0x or
217
0X for hexadecimal. If base is 16, a preceding 0x or 0X is
224
raise TypeError('function requires at least 1 argument: %d given' %
226
# Don't catch type error resulting from too many arguments to int(). The
227
# error message isn't compatible but the error type is, and this function
228
# is complicated enough already.
229
if type(s) == _StringType:
230
return _apply(_int, args)
232
raise TypeError('argument 1: expected string, %s found' %
236
# Convert string to long integer
238
"""atol(s [,base]) -> long
240
Return the long integer represented by the string s in the
241
given base, which defaults to 10. The string s must consist
242
of one or more digits, possibly preceded by a sign. If base
243
is 0, it is chosen from the leading characters of s, 0 for
244
octal, 0x or 0X for hexadecimal. If base is 16, a preceding
245
0x or 0X is accepted. A trailing L or l is not accepted,
252
raise TypeError('function requires at least 1 argument: %d given' %
254
# Don't catch type error resulting from too many arguments to long(). The
255
# error message isn't compatible but the error type is, and this function
256
# is complicated enough already.
257
if type(s) == _StringType:
258
return _apply(_long, args)
260
raise TypeError('argument 1: expected string, %s found' %
264
# Left-justify a string
266
"""ljust(s, width) -> string
268
Return a left-justified version of s, in a field of the
269
specified width, padded with spaces as needed. The string is
277
# Right-justify a string
279
"""rjust(s, width) -> string
281
Return a right-justified version of s, in a field of the
282
specified width, padded with spaces as needed. The string is
291
def center(s, width):
292
"""center(s, width) -> string
294
Return a center version of s, in a field of the specified
295
width. padded with spaces as needed. The string is never
303
# This ensures that center(center(s, i), j) = center(s, j)
305
return ' '*half + s + ' '*(n-half)
307
# Zero-fill a number, e.g., (12, 3) --> '012' and (-3, 3) --> '-03'
308
# Decadent feature: the argument may be a string or a number
309
# (Use of this is deprecated; it should be a string as with ljust c.s.)
311
"""zfill(x, width) -> string
313
Pad a numeric string x with zeros on the left, to fill a field
314
of the specified width. The string x is never truncated.
317
if type(x) == type(''): s = x
320
if n >= width: return s
322
if s[0] in ('-', '+'):
323
sign, s = s[0], s[1:]
324
return sign + '0'*(width-n) + s
326
# Expand tabs in a string.
327
# Doesn't take non-printing chars into account, but does understand \n.
328
def expandtabs(s, tabsize=8):
329
"""expandtabs(s [,tabsize]) -> string
331
Return a copy of the string s with all tab characters replaced
332
by the appropriate number of spaces, depending on the current
333
column, and the tabsize (default 8).
339
c = ' '*(tabsize - len(line) % tabsize)
346
# Character translation through look-up table.
347
def translate(s, table, deletions=""):
348
"""translate(s,table [,deletechars]) -> string
350
Return a copy of the string s, where all characters occurring
351
in the optional argument deletechars are removed, and the
352
remaining characters have been mapped through the given
353
translation table, which must be a string of length 256.
356
return s.translate(table, deletions)
358
# Capitalize a string, e.g. "aBc dEf" -> "Abc def".
360
"""capitalize(s) -> string
362
Return a copy of the string s with only its first character
366
return s.capitalize()
368
# Capitalize the words in a string, e.g. " aBc dEf " -> "Abc Def".
369
def capwords(s, sep=None):
370
"""capwords(s, [sep]) -> string
372
Split the argument into words using split, capitalize each
373
word using capitalize, and join the capitalized words using
374
join. Note that this replaces runs of whitespace characters by
378
return join(map(capitalize, s.split(sep)), sep or ' ')
380
# Construct a translation string
382
def maketrans(fromstr, tostr):
383
"""maketrans(frm, to) -> string
385
Return a translation table (a string of 256 bytes long)
386
suitable for use in string.translate. The strings frm and to
387
must be of the same length.
390
if len(fromstr) != len(tostr):
391
raise ValueError, "maketrans arguments must have same length"
394
_idmapL = list(_idmap)
396
fromstr = map(ord, fromstr)
397
for i in range(len(fromstr)):
398
L[fromstr[i]] = tostr[i]
401
# Substring replacement (global)
402
def replace(s, old, new, maxsplit=0):
403
"""replace (str, old, new[, maxsplit]) -> string
405
Return a copy of string str with all occurrences of substring
406
old replaced by new. If the optional argument maxsplit is
407
given, only the first maxsplit occurrences are replaced.
410
return s.replace(old, new, maxsplit)
415
# If string objects do not have methods, then we need to use the old string.py
416
# library, which uses strop for many more things than just the few outlined
420
except AttributeError:
421
from stringold import *
423
# Try importing optional built-in module "strop" -- if it exists,
424
# it redefines some string operations that are 100-1000 times faster.
425
# It also defines values for whitespace, lowercase and uppercase
426
# that match <ctype.h>'s definitions.
429
from strop import maketrans, lowercase, uppercase, whitespace
430
letters = lowercase + uppercase
432
pass # Use the original versions