blob: c3e6f6f9ed49f5ac35e8d12e24e77103f8f8be98 [file] [log] [blame]
Guido van Rossumc6360141990-10-13 19:23:40 +00001# module 'string' -- A collection of string operations
2
Barry Warsaw226ae6c1999-10-12 19:54:53 +00003# 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.
Guido van Rossumc6360141990-10-13 19:23:40 +00007
Guido van Rossum20032041997-12-29 19:26:28 +00008"""Common string manipulations.
9
10Public module variables:
11
12whitespace -- a string containing all characters considered whitespace
13lowercase -- a string containing all characters considered lowercase letters
14uppercase -- a string containing all characters considered uppercase letters
15letters -- a string containing all characters considered letters
16digits -- a string containing all characters considered decimal digits
17hexdigits -- a string containing all characters considered hexadecimal digits
18octdigits -- a string containing all characters considered octal digits
19
20"""
21
Guido van Rossumc6360141990-10-13 19:23:40 +000022# Some strings for ctype-style character classification
Guido van Rossum8e2ec561993-07-29 09:37:38 +000023whitespace = ' \t\n\r\v\f'
Guido van Rossumc6360141990-10-13 19:23:40 +000024lowercase = 'abcdefghijklmnopqrstuvwxyz'
25uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
26letters = lowercase + uppercase
27digits = '0123456789'
28hexdigits = digits + 'abcdef' + 'ABCDEF'
29octdigits = '01234567'
30
31# Case conversion helpers
Guido van Rossuma61ff7b1992-01-14 18:31:29 +000032_idmap = ''
33for i in range(256): _idmap = _idmap + chr(i)
Guido van Rossumc6360141990-10-13 19:23:40 +000034del i
35
Guido van Rossum710c3521994-08-17 13:16:11 +000036# Backward compatible names for exceptions
37index_error = ValueError
38atoi_error = ValueError
39atof_error = ValueError
40atol_error = ValueError
41
Guido van Rossumc6360141990-10-13 19:23:40 +000042# convert UPPER CASE letters to lower case
43def lower(s):
Barry Warsaw226ae6c1999-10-12 19:54:53 +000044 """lower(s) -> string
Guido van Rossum20032041997-12-29 19:26:28 +000045
Barry Warsaw226ae6c1999-10-12 19:54:53 +000046 Return a copy of the string s converted to lowercase.
Guido van Rossum20032041997-12-29 19:26:28 +000047
Barry Warsaw226ae6c1999-10-12 19:54:53 +000048 """
49 return s.lower()
Guido van Rossumc6360141990-10-13 19:23:40 +000050
51# Convert lower case letters to UPPER CASE
52def upper(s):
Barry Warsaw226ae6c1999-10-12 19:54:53 +000053 """upper(s) -> string
Guido van Rossum20032041997-12-29 19:26:28 +000054
Barry Warsaw226ae6c1999-10-12 19:54:53 +000055 Return a copy of the string s converted to uppercase.
Guido van Rossum20032041997-12-29 19:26:28 +000056
Barry Warsaw226ae6c1999-10-12 19:54:53 +000057 """
58 return s.upper()
Guido van Rossumc6360141990-10-13 19:23:40 +000059
60# Swap lower case letters and UPPER CASE
61def swapcase(s):
Barry Warsaw226ae6c1999-10-12 19:54:53 +000062 """swapcase(s) -> string
Guido van Rossum20032041997-12-29 19:26:28 +000063
Barry Warsaw226ae6c1999-10-12 19:54:53 +000064 Return a copy of the string s with upper case characters
65 converted to lowercase and vice versa.
Guido van Rossum20032041997-12-29 19:26:28 +000066
Barry Warsaw226ae6c1999-10-12 19:54:53 +000067 """
68 return s.swapcase()
Guido van Rossumc6360141990-10-13 19:23:40 +000069
70# Strip leading and trailing tabs and spaces
71def strip(s):
Barry Warsaw226ae6c1999-10-12 19:54:53 +000072 """strip(s) -> string
Guido van Rossum20032041997-12-29 19:26:28 +000073
Barry Warsaw226ae6c1999-10-12 19:54:53 +000074 Return a copy of the string s with leading and trailing
75 whitespace removed.
Guido van Rossum20032041997-12-29 19:26:28 +000076
Barry Warsaw226ae6c1999-10-12 19:54:53 +000077 """
78 return s.strip()
Guido van Rossumc6360141990-10-13 19:23:40 +000079
Guido van Rossum306a8a61996-08-08 18:40:59 +000080# Strip leading tabs and spaces
81def lstrip(s):
Barry Warsaw226ae6c1999-10-12 19:54:53 +000082 """lstrip(s) -> string
Guido van Rossum20032041997-12-29 19:26:28 +000083
Barry Warsaw226ae6c1999-10-12 19:54:53 +000084 Return a copy of the string s with leading whitespace removed.
Guido van Rossum20032041997-12-29 19:26:28 +000085
Barry Warsaw226ae6c1999-10-12 19:54:53 +000086 """
87 return s.lstrip()
Guido van Rossum306a8a61996-08-08 18:40:59 +000088
89# Strip trailing tabs and spaces
90def rstrip(s):
Barry Warsaw226ae6c1999-10-12 19:54:53 +000091 """rstrip(s) -> string
Guido van Rossum20032041997-12-29 19:26:28 +000092
Barry Warsaw226ae6c1999-10-12 19:54:53 +000093 Return a copy of the string s with trailing whitespace
94 removed.
Guido van Rossum20032041997-12-29 19:26:28 +000095
Barry Warsaw226ae6c1999-10-12 19:54:53 +000096 """
97 return s.rstrip()
Guido van Rossum306a8a61996-08-08 18:40:59 +000098
99
Guido van Rossumc6360141990-10-13 19:23:40 +0000100# Split a string into a list of space/tab-separated words
101# NB: split(s) is NOT the same as splitfields(s, ' ')!
Guido van Rossum306a8a61996-08-08 18:40:59 +0000102def split(s, sep=None, maxsplit=0):
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000103 """split(str [,sep [,maxsplit]]) -> list of strings
Guido van Rossum20032041997-12-29 19:26:28 +0000104
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000105 Return a list of the words in the string s, using sep as the
106 delimiter string. If maxsplit is nonzero, splits into at most
107 maxsplit words If sep is not specified, any whitespace string
108 is a separator. Maxsplit defaults to 0.
Guido van Rossum20032041997-12-29 19:26:28 +0000109
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000110 (split and splitfields are synonymous)
Guido van Rossum20032041997-12-29 19:26:28 +0000111
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000112 """
113 return s.split(sep, maxsplit)
114splitfields = split
Guido van Rossumfac38b71991-04-07 13:42:19 +0000115
Guido van Rossum2ab19921995-06-22 18:58:00 +0000116# Join fields with optional separator
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000117def join(words, sep = ' '):
118 """join(list [,sep]) -> string
Guido van Rossum20032041997-12-29 19:26:28 +0000119
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000120 Return a string composed of the words in list, with
Thomas Wouters7e474022000-07-16 12:04:32 +0000121 intervening occurrences of sep. The default separator is a
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000122 single space.
Guido van Rossum20032041997-12-29 19:26:28 +0000123
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000124 (joinfields and join are synonymous)
Guido van Rossum20032041997-12-29 19:26:28 +0000125
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000126 """
127 return sep.join(words)
128joinfields = join
129
130# for a little bit of speed
131_apply = apply
Guido van Rossumfac38b71991-04-07 13:42:19 +0000132
Guido van Rossumd3166071993-05-24 14:16:22 +0000133# Find substring, raise exception if not found
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000134def index(s, *args):
135 """index(s, sub [,start [,end]]) -> int
Guido van Rossum20032041997-12-29 19:26:28 +0000136
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000137 Like find but raises ValueError when the substring is not found.
Guido van Rossum20032041997-12-29 19:26:28 +0000138
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000139 """
140 return _apply(s.index, args)
Guido van Rossumd3166071993-05-24 14:16:22 +0000141
Guido van Rossume65cce51993-11-08 15:05:21 +0000142# Find last substring, raise exception if not found
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000143def rindex(s, *args):
144 """rindex(s, sub [,start [,end]]) -> int
Guido van Rossum20032041997-12-29 19:26:28 +0000145
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000146 Like rfind but raises ValueError when the substring is not found.
Guido van Rossum20032041997-12-29 19:26:28 +0000147
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000148 """
149 return _apply(s.rindex, args)
Guido van Rossumb6775db1994-08-01 11:34:53 +0000150
151# Count non-overlapping occurrences of substring
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000152def count(s, *args):
153 """count(s, sub[, start[,end]]) -> int
Guido van Rossum20032041997-12-29 19:26:28 +0000154
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000155 Return the number of occurrences of substring sub in string
156 s[start:end]. Optional arguments start and end are
157 interpreted as in slice notation.
Guido van Rossum20032041997-12-29 19:26:28 +0000158
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000159 """
160 return _apply(s.count, args)
Guido van Rossume65cce51993-11-08 15:05:21 +0000161
Guido van Rossumd3166071993-05-24 14:16:22 +0000162# Find substring, return -1 if not found
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000163def find(s, *args):
164 """find(s, sub [,start [,end]]) -> in
Guido van Rossum20032041997-12-29 19:26:28 +0000165
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000166 Return the lowest index in s where substring sub is found,
167 such that sub is contained within s[start,end]. Optional
168 arguments start and end are interpreted as in slice notation.
Guido van Rossum20032041997-12-29 19:26:28 +0000169
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000170 Return -1 on failure.
Guido van Rossum20032041997-12-29 19:26:28 +0000171
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000172 """
173 return _apply(s.find, args)
Guido van Rossumc6360141990-10-13 19:23:40 +0000174
Guido van Rossume65cce51993-11-08 15:05:21 +0000175# Find last substring, return -1 if not found
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000176def rfind(s, *args):
177 """rfind(s, sub [,start [,end]]) -> int
Guido van Rossum20032041997-12-29 19:26:28 +0000178
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000179 Return the highest index in s where substring sub is found,
180 such that sub is contained within s[start,end]. Optional
181 arguments start and end are interpreted as in slice notation.
Guido van Rossum20032041997-12-29 19:26:28 +0000182
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000183 Return -1 on failure.
Guido van Rossum20032041997-12-29 19:26:28 +0000184
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000185 """
186 return _apply(s.rfind, args)
Guido van Rossume65cce51993-11-08 15:05:21 +0000187
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000188# for a bit of speed
189_float = float
190_int = int
191_long = long
192_StringType = type('')
Guido van Rossumd0753e21997-12-10 22:59:55 +0000193
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000194# Convert string to float
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000195def atof(s):
196 """atof(s) -> float
Guido van Rossum20032041997-12-29 19:26:28 +0000197
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000198 Return the floating point number represented by the string s.
Guido van Rossum20032041997-12-29 19:26:28 +0000199
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000200 """
201 if type(s) == _StringType:
Fred Drake13a2c272000-02-10 17:17:14 +0000202 return _float(s)
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000203 else:
Fred Drake13a2c272000-02-10 17:17:14 +0000204 raise TypeError('argument 1: expected string, %s found' %
205 type(s).__name__)
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000206
Guido van Rossumc6360141990-10-13 19:23:40 +0000207# Convert string to integer
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000208def atoi(*args):
209 """atoi(s [,base]) -> int
Guido van Rossum20032041997-12-29 19:26:28 +0000210
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000211 Return the integer represented by the string s in the given
212 base, which defaults to 10. The string s must consist of one
213 or more digits, possibly preceded by a sign. If base is 0, it
214 is chosen from the leading characters of s, 0 for octal, 0x or
215 0X for hexadecimal. If base is 16, a preceding 0x or 0X is
216 accepted.
Guido van Rossum20032041997-12-29 19:26:28 +0000217
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000218 """
219 try:
Fred Drake13a2c272000-02-10 17:17:14 +0000220 s = args[0]
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000221 except IndexError:
Fred Drake13a2c272000-02-10 17:17:14 +0000222 raise TypeError('function requires at least 1 argument: %d given' %
223 len(args))
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000224 # Don't catch type error resulting from too many arguments to int(). The
225 # error message isn't compatible but the error type is, and this function
226 # is complicated enough already.
227 if type(s) == _StringType:
Fred Drake13a2c272000-02-10 17:17:14 +0000228 return _apply(_int, args)
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000229 else:
Fred Drake13a2c272000-02-10 17:17:14 +0000230 raise TypeError('argument 1: expected string, %s found' %
231 type(s).__name__)
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000232
Guido van Rossumc6360141990-10-13 19:23:40 +0000233
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000234# Convert string to long integer
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000235def atol(*args):
236 """atol(s [,base]) -> long
Guido van Rossum20032041997-12-29 19:26:28 +0000237
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000238 Return the long integer represented by the string s in the
239 given base, which defaults to 10. The string s must consist
240 of one or more digits, possibly preceded by a sign. If base
241 is 0, it is chosen from the leading characters of s, 0 for
242 octal, 0x or 0X for hexadecimal. If base is 16, a preceding
243 0x or 0X is accepted. A trailing L or l is not accepted,
244 unless base is 0.
Guido van Rossum20032041997-12-29 19:26:28 +0000245
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000246 """
247 try:
Fred Drake13a2c272000-02-10 17:17:14 +0000248 s = args[0]
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000249 except IndexError:
Fred Drake13a2c272000-02-10 17:17:14 +0000250 raise TypeError('function requires at least 1 argument: %d given' %
251 len(args))
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000252 # Don't catch type error resulting from too many arguments to long(). The
253 # error message isn't compatible but the error type is, and this function
254 # is complicated enough already.
255 if type(s) == _StringType:
Fred Drake13a2c272000-02-10 17:17:14 +0000256 return _apply(_long, args)
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000257 else:
Fred Drake13a2c272000-02-10 17:17:14 +0000258 raise TypeError('argument 1: expected string, %s found' %
259 type(s).__name__)
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000260
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000261
Guido van Rossumc6360141990-10-13 19:23:40 +0000262# Left-justify a string
263def ljust(s, width):
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000264 """ljust(s, width) -> string
Guido van Rossum20032041997-12-29 19:26:28 +0000265
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000266 Return a left-justified version of s, in a field of the
267 specified width, padded with spaces as needed. The string is
268 never truncated.
Guido van Rossum20032041997-12-29 19:26:28 +0000269
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000270 """
271 n = width - len(s)
272 if n <= 0: return s
273 return s + ' '*n
Guido van Rossumc6360141990-10-13 19:23:40 +0000274
275# Right-justify a string
276def rjust(s, width):
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000277 """rjust(s, width) -> string
Guido van Rossum20032041997-12-29 19:26:28 +0000278
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000279 Return a right-justified version of s, in a field of the
280 specified width, padded with spaces as needed. The string is
281 never truncated.
Guido van Rossum20032041997-12-29 19:26:28 +0000282
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000283 """
284 n = width - len(s)
285 if n <= 0: return s
286 return ' '*n + s
Guido van Rossumc6360141990-10-13 19:23:40 +0000287
288# Center a string
289def center(s, width):
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000290 """center(s, width) -> string
Guido van Rossum20032041997-12-29 19:26:28 +0000291
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000292 Return a center version of s, in a field of the specified
293 width. padded with spaces as needed. The string is never
294 truncated.
Guido van Rossum20032041997-12-29 19:26:28 +0000295
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000296 """
297 n = width - len(s)
298 if n <= 0: return s
299 half = n/2
300 if n%2 and width%2:
Fred Drake13a2c272000-02-10 17:17:14 +0000301 # This ensures that center(center(s, i), j) = center(s, j)
302 half = half+1
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000303 return ' '*half + s + ' '*(n-half)
Guido van Rossumc6360141990-10-13 19:23:40 +0000304
305# Zero-fill a number, e.g., (12, 3) --> '012' and (-3, 3) --> '-03'
306# Decadent feature: the argument may be a string or a number
307# (Use of this is deprecated; it should be a string as with ljust c.s.)
308def zfill(x, width):
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000309 """zfill(x, width) -> string
Guido van Rossum20032041997-12-29 19:26:28 +0000310
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000311 Pad a numeric string x with zeros on the left, to fill a field
312 of the specified width. The string x is never truncated.
Guido van Rossum20032041997-12-29 19:26:28 +0000313
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000314 """
315 if type(x) == type(''): s = x
316 else: s = `x`
317 n = len(s)
318 if n >= width: return s
319 sign = ''
320 if s[0] in ('-', '+'):
Fred Drake13a2c272000-02-10 17:17:14 +0000321 sign, s = s[0], s[1:]
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000322 return sign + '0'*(width-n) + s
Guido van Rossum6ff2e901992-03-27 15:13:31 +0000323
324# Expand tabs in a string.
325# Doesn't take non-printing chars into account, but does understand \n.
Guido van Rossum894a7bb1995-08-10 19:42:05 +0000326def expandtabs(s, tabsize=8):
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000327 """expandtabs(s [,tabsize]) -> string
Guido van Rossum20032041997-12-29 19:26:28 +0000328
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000329 Return a copy of the string s with all tab characters replaced
330 by the appropriate number of spaces, depending on the current
331 column, and the tabsize (default 8).
Guido van Rossum20032041997-12-29 19:26:28 +0000332
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000333 """
334 res = line = ''
335 for c in s:
Fred Drake13a2c272000-02-10 17:17:14 +0000336 if c == '\t':
337 c = ' '*(tabsize - len(line) % tabsize)
338 line = line + c
339 if c == '\n':
340 res = res + line
341 line = ''
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000342 return res + line
Guido van Rossum2db91351992-10-18 17:09:59 +0000343
Guido van Rossum25395281996-05-28 23:08:45 +0000344# Character translation through look-up table.
Guido van Rossumed7253c1996-07-23 18:12:39 +0000345def translate(s, table, deletions=""):
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000346 """translate(s,table [,deletechars]) -> string
Guido van Rossum20032041997-12-29 19:26:28 +0000347
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000348 Return a copy of the string s, where all characters occurring
349 in the optional argument deletechars are removed, and the
350 remaining characters have been mapped through the given
351 translation table, which must be a string of length 256.
Guido van Rossum20032041997-12-29 19:26:28 +0000352
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000353 """
354 return s.translate(table, deletions)
Guido van Rossum2db91351992-10-18 17:09:59 +0000355
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000356# Capitalize a string, e.g. "aBc dEf" -> "Abc def".
357def capitalize(s):
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000358 """capitalize(s) -> string
Guido van Rossum20032041997-12-29 19:26:28 +0000359
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000360 Return a copy of the string s with only its first character
361 capitalized.
Guido van Rossum20032041997-12-29 19:26:28 +0000362
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000363 """
364 return s.capitalize()
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000365
366# Capitalize the words in a string, e.g. " aBc dEf " -> "Abc Def".
367# See also regsub.capwords().
Guido van Rossum34f17311996-08-20 20:25:41 +0000368def capwords(s, sep=None):
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000369 """capwords(s, [sep]) -> string
Guido van Rossum20032041997-12-29 19:26:28 +0000370
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000371 Split the argument into words using split, capitalize each
372 word using capitalize, and join the capitalized words using
373 join. Note that this replaces runs of whitespace characters by
374 a single space.
Guido van Rossum20032041997-12-29 19:26:28 +0000375
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000376 """
377 return join(map(capitalize, s.split(sep)), sep or ' ')
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000378
Guido van Rossumed7253c1996-07-23 18:12:39 +0000379# Construct a translation string
380_idmapL = None
381def maketrans(fromstr, tostr):
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000382 """maketrans(frm, to) -> string
Guido van Rossum20032041997-12-29 19:26:28 +0000383
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000384 Return a translation table (a string of 256 bytes long)
385 suitable for use in string.translate. The strings frm and to
386 must be of the same length.
Guido van Rossum20032041997-12-29 19:26:28 +0000387
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000388 """
389 if len(fromstr) != len(tostr):
Fred Drake13a2c272000-02-10 17:17:14 +0000390 raise ValueError, "maketrans arguments must have same length"
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000391 global _idmapL
392 if not _idmapL:
Fred Drake13a2c272000-02-10 17:17:14 +0000393 _idmapL = map(None, _idmap)
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000394 L = _idmapL[:]
395 fromstr = map(ord, fromstr)
396 for i in range(len(fromstr)):
Fred Drake13a2c272000-02-10 17:17:14 +0000397 L[fromstr[i]] = tostr[i]
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000398 return joinfields(L, "")
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000399
Guido van Rossum1eb9a811997-03-25 16:50:31 +0000400# Substring replacement (global)
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000401def replace(s, old, new, maxsplit=0):
402 """replace (str, old, new[, maxsplit]) -> string
Guido van Rossum20032041997-12-29 19:26:28 +0000403
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000404 Return a copy of string str with all occurrences of substring
405 old replaced by new. If the optional argument maxsplit is
406 given, only the first maxsplit occurrences are replaced.
Guido van Rossum20032041997-12-29 19:26:28 +0000407
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000408 """
409 return s.replace(old, new, maxsplit)
Guido van Rossum1eb9a811997-03-25 16:50:31 +0000410
411
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000412# XXX: transitional
413#
414# If string objects do not have methods, then we need to use the old string.py
415# library, which uses strop for many more things than just the few outlined
416# below.
417try:
418 ''.upper
419except AttributeError:
420 from stringold import *
421
Guido van Rossum2db91351992-10-18 17:09:59 +0000422# Try importing optional built-in module "strop" -- if it exists,
423# it redefines some string operations that are 100-1000 times faster.
Guido van Rossum8e2ec561993-07-29 09:37:38 +0000424# It also defines values for whitespace, lowercase and uppercase
425# that match <ctype.h>'s definitions.
Guido van Rossum2db91351992-10-18 17:09:59 +0000426
427try:
Barry Warsaw226ae6c1999-10-12 19:54:53 +0000428 from strop import maketrans, lowercase, uppercase, whitespace
429 letters = lowercase + uppercase
Guido van Rossumb6775db1994-08-01 11:34:53 +0000430except ImportError:
Fred Drake13a2c272000-02-10 17:17:14 +0000431 pass # Use the original versions