blob: b2563f99572d2f964d5b7ff73ba6635428a8adc4 [file] [log] [blame]
Guido van Rossumc6360141990-10-13 19:23:40 +00001# module 'string' -- A collection of string operations
2
Guido van Rossume7113b61993-03-29 11:30:50 +00003# Warning: most of the code you see here isn't normally used nowadays.
4# At the end of this file most functions are replaced by built-in
5# functions imported from built-in module "strop".
Guido van Rossumc6360141990-10-13 19:23:40 +00006
Guido van Rossum20032041997-12-29 19:26:28 +00007"""Common string manipulations.
8
9Public module variables:
10
11whitespace -- a string containing all characters considered whitespace
12lowercase -- a string containing all characters considered lowercase letters
13uppercase -- a string containing all characters considered uppercase letters
14letters -- a string containing all characters considered letters
15digits -- a string containing all characters considered decimal digits
16hexdigits -- a string containing all characters considered hexadecimal digits
17octdigits -- a string containing all characters considered octal digits
18
19"""
20
Guido van Rossumc6360141990-10-13 19:23:40 +000021# Some strings for ctype-style character classification
Guido van Rossum8e2ec561993-07-29 09:37:38 +000022whitespace = ' \t\n\r\v\f'
Guido van Rossumc6360141990-10-13 19:23:40 +000023lowercase = 'abcdefghijklmnopqrstuvwxyz'
24uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
25letters = lowercase + uppercase
26digits = '0123456789'
27hexdigits = digits + 'abcdef' + 'ABCDEF'
28octdigits = '01234567'
29
30# Case conversion helpers
Guido van Rossuma61ff7b1992-01-14 18:31:29 +000031_idmap = ''
32for i in range(256): _idmap = _idmap + chr(i)
33_lower = _idmap[:ord('A')] + lowercase + _idmap[ord('Z')+1:]
34_upper = _idmap[:ord('a')] + uppercase + _idmap[ord('z')+1:]
35_swapcase = _upper[:ord('A')] + lowercase + _upper[ord('Z')+1:]
Guido van Rossumc6360141990-10-13 19:23:40 +000036del i
37
Guido van Rossum710c3521994-08-17 13:16:11 +000038# Backward compatible names for exceptions
39index_error = ValueError
40atoi_error = ValueError
41atof_error = ValueError
42atol_error = ValueError
43
Guido van Rossumc6360141990-10-13 19:23:40 +000044# convert UPPER CASE letters to lower case
45def lower(s):
Guido van Rossum20032041997-12-29 19:26:28 +000046 """lower(s) -> string
47
Guido van Rossum23e21e71997-12-29 19:57:36 +000048 Return a copy of the string s converted to lowercase.
Guido van Rossum20032041997-12-29 19:26:28 +000049
50 """
Guido van Rossumc6360141990-10-13 19:23:40 +000051 res = ''
52 for c in s:
Guido van Rossuma61ff7b1992-01-14 18:31:29 +000053 res = res + _lower[ord(c)]
Guido van Rossumc6360141990-10-13 19:23:40 +000054 return res
55
56# Convert lower case letters to UPPER CASE
57def upper(s):
Guido van Rossum20032041997-12-29 19:26:28 +000058 """upper(s) -> string
59
Guido van Rossum23e21e71997-12-29 19:57:36 +000060 Return a copy of the string s converted to uppercase.
Guido van Rossum20032041997-12-29 19:26:28 +000061
62 """
Guido van Rossumc6360141990-10-13 19:23:40 +000063 res = ''
64 for c in s:
Guido van Rossuma61ff7b1992-01-14 18:31:29 +000065 res = res + _upper[ord(c)]
Guido van Rossumc6360141990-10-13 19:23:40 +000066 return res
67
68# Swap lower case letters and UPPER CASE
69def swapcase(s):
Guido van Rossum23e21e71997-12-29 19:57:36 +000070 """swapcase(s) -> string
Guido van Rossum20032041997-12-29 19:26:28 +000071
72 Return a copy of the string s with upper case characters
Guido van Rossum23e21e71997-12-29 19:57:36 +000073 converted to lowercase and vice versa.
Guido van Rossum20032041997-12-29 19:26:28 +000074
75 """
Guido van Rossumc6360141990-10-13 19:23:40 +000076 res = ''
77 for c in s:
Guido van Rossuma61ff7b1992-01-14 18:31:29 +000078 res = res + _swapcase[ord(c)]
Guido van Rossumc6360141990-10-13 19:23:40 +000079 return res
80
81# Strip leading and trailing tabs and spaces
82def strip(s):
Guido van Rossum20032041997-12-29 19:26:28 +000083 """strip(s) -> string
84
85 Return a copy of the string s with leading and trailing
Guido van Rossum23e21e71997-12-29 19:57:36 +000086 whitespace removed.
Guido van Rossum20032041997-12-29 19:26:28 +000087
88 """
Guido van Rossumc6360141990-10-13 19:23:40 +000089 i, j = 0, len(s)
90 while i < j and s[i] in whitespace: i = i+1
91 while i < j and s[j-1] in whitespace: j = j-1
92 return s[i:j]
93
Guido van Rossum306a8a61996-08-08 18:40:59 +000094# Strip leading tabs and spaces
95def lstrip(s):
Guido van Rossum20032041997-12-29 19:26:28 +000096 """lstrip(s) -> string
97
Guido van Rossum23e21e71997-12-29 19:57:36 +000098 Return a copy of the string s with leading whitespace removed.
Guido van Rossum20032041997-12-29 19:26:28 +000099
100 """
Guido van Rossum306a8a61996-08-08 18:40:59 +0000101 i, j = 0, len(s)
102 while i < j and s[i] in whitespace: i = i+1
103 return s[i:j]
104
105# Strip trailing tabs and spaces
106def rstrip(s):
Guido van Rossum20032041997-12-29 19:26:28 +0000107 """rstrip(s) -> string
108
Guido van Rossum23e21e71997-12-29 19:57:36 +0000109 Return a copy of the string s with trailing whitespace
110 removed.
Guido van Rossum20032041997-12-29 19:26:28 +0000111
112 """
Guido van Rossum306a8a61996-08-08 18:40:59 +0000113 i, j = 0, len(s)
114 while i < j and s[j-1] in whitespace: j = j-1
115 return s[i:j]
116
117
Guido van Rossumc6360141990-10-13 19:23:40 +0000118# Split a string into a list of space/tab-separated words
119# NB: split(s) is NOT the same as splitfields(s, ' ')!
Guido van Rossum306a8a61996-08-08 18:40:59 +0000120def split(s, sep=None, maxsplit=0):
Guido van Rossum20032041997-12-29 19:26:28 +0000121 """split(str [,sep [,maxsplit]]) -> list of strings
122
123 Return a list of the words in the string s, using sep as the
124 delimiter string. If maxsplit is nonzero, splits into at most
125 maxsplit words If sep is not specified, any whitespace string
126 is a separator. Maxsplit defaults to 0.
127
128 (split and splitfields are synonymous)
129
130 """
Guido van Rossum306a8a61996-08-08 18:40:59 +0000131 if sep is not None: return splitfields(s, sep, maxsplit)
Guido van Rossumc6360141990-10-13 19:23:40 +0000132 res = []
133 i, n = 0, len(s)
Guido van Rossum06ba34c1997-12-01 15:25:19 +0000134 if maxsplit <= 0: maxsplit = n
135 count = 0
Guido van Rossumc6360141990-10-13 19:23:40 +0000136 while i < n:
137 while i < n and s[i] in whitespace: i = i+1
Guido van Rossumbdfcfcc1992-01-01 19:35:13 +0000138 if i == n: break
Guido van Rossum06ba34c1997-12-01 15:25:19 +0000139 if count >= maxsplit:
140 res.append(s[i:])
141 break
Guido van Rossumc6360141990-10-13 19:23:40 +0000142 j = i
143 while j < n and s[j] not in whitespace: j = j+1
Guido van Rossum06ba34c1997-12-01 15:25:19 +0000144 count = count + 1
Guido van Rossumc6360141990-10-13 19:23:40 +0000145 res.append(s[i:j])
146 i = j
147 return res
148
149# Split a list into fields separated by a given string
150# NB: splitfields(s, ' ') is NOT the same as split(s)!
Guido van Rossum7a461e51992-09-20 21:41:09 +0000151# splitfields(s, '') returns [s] (in analogy with split() in nawk)
Guido van Rossum306a8a61996-08-08 18:40:59 +0000152def splitfields(s, sep=None, maxsplit=0):
Guido van Rossum20032041997-12-29 19:26:28 +0000153 """splitfields(str [,sep [,maxsplit]]) -> list of strings
154
155 Return a list of the words in the string s, using sep as the
156 delimiter string. If maxsplit is nonzero, splits into at most
157 maxsplit words If sep is not specified, any whitespace string
158 is a separator. Maxsplit defaults to 0.
159
160 (split and splitfields are synonymous)
161
162 """
Guido van Rossum306a8a61996-08-08 18:40:59 +0000163 if sep is None: return split(s, None, maxsplit)
Guido van Rossumc6360141990-10-13 19:23:40 +0000164 res = []
Guido van Rossumc6360141990-10-13 19:23:40 +0000165 nsep = len(sep)
Guido van Rossumae507a41992-08-19 16:49:58 +0000166 if nsep == 0:
Guido van Rossum7a461e51992-09-20 21:41:09 +0000167 return [s]
Guido van Rossumae507a41992-08-19 16:49:58 +0000168 ns = len(s)
Guido van Rossum06ba34c1997-12-01 15:25:19 +0000169 if maxsplit <= 0: maxsplit = ns
Guido van Rossumc6360141990-10-13 19:23:40 +0000170 i = j = 0
Guido van Rossum306a8a61996-08-08 18:40:59 +0000171 count = 0
Guido van Rossumc6360141990-10-13 19:23:40 +0000172 while j+nsep <= ns:
Guido van Rossumbdfcfcc1992-01-01 19:35:13 +0000173 if s[j:j+nsep] == sep:
Guido van Rossum306a8a61996-08-08 18:40:59 +0000174 count = count + 1
Guido van Rossumc6360141990-10-13 19:23:40 +0000175 res.append(s[i:j])
176 i = j = j + nsep
Guido van Rossum06ba34c1997-12-01 15:25:19 +0000177 if count >= maxsplit: break
Guido van Rossumc6360141990-10-13 19:23:40 +0000178 else:
179 j = j + 1
180 res.append(s[i:])
181 return res
182
Guido van Rossumfac38b71991-04-07 13:42:19 +0000183# Join words with spaces between them
Guido van Rossum2ab19921995-06-22 18:58:00 +0000184def join(words, sep = ' '):
Guido van Rossum20032041997-12-29 19:26:28 +0000185 """join(list [,sep]) -> string
186
187 Return a string composed of the words in list, with
Guido van Rossum23e21e71997-12-29 19:57:36 +0000188 intervening occurences of sep. Sep defaults to a single
189 space.
Guido van Rossum20032041997-12-29 19:26:28 +0000190
191 (joinfields and join are synonymous)
192
Guido van Rossum23e21e71997-12-29 19:57:36 +0000193 """
Guido van Rossum2ab19921995-06-22 18:58:00 +0000194 return joinfields(words, sep)
Guido van Rossumfac38b71991-04-07 13:42:19 +0000195
Guido van Rossum2ab19921995-06-22 18:58:00 +0000196# Join fields with optional separator
197def joinfields(words, sep = ' '):
Guido van Rossum20032041997-12-29 19:26:28 +0000198 """joinfields(list [,sep]) -> string
199
200 Return a string composed of the words in list, with
201 intervening occurences of sep. The default separator is a
202 single space.
203
204 (joinfields and join are synonymous)
205
206 """
Guido van Rossumfac38b71991-04-07 13:42:19 +0000207 res = ''
208 for w in words:
209 res = res + (sep + w)
210 return res[len(sep):]
211
Guido van Rossumd3166071993-05-24 14:16:22 +0000212# Find substring, raise exception if not found
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000213def index(s, sub, i = 0, last=None):
Guido van Rossum20032041997-12-29 19:26:28 +0000214 """index(s, sub [,start [,end]]) -> int
215
216 Return the lowest index in s where substring sub is found,
217 such that sub is contained within s[start,end]. Optional
218 arguments start and end are interpreted as in slice notation.
219
220 Raise ValueError if not found.
221
222 """
Guido van Rossum15105651997-10-20 23:31:15 +0000223 if last is None: last = len(s)
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000224 res = find(s, sub, i, last)
Guido van Rossum710c3521994-08-17 13:16:11 +0000225 if res < 0:
226 raise ValueError, 'substring not found in string.index'
227 return res
Guido van Rossumd3166071993-05-24 14:16:22 +0000228
Guido van Rossume65cce51993-11-08 15:05:21 +0000229# Find last substring, raise exception if not found
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000230def rindex(s, sub, i = 0, last=None):
Guido van Rossum20032041997-12-29 19:26:28 +0000231 """rindex(s, sub [,start [,end]]) -> int
232
233 Return the highest index in s where substring sub is found,
234 such that sub is contained within s[start,end]. Optional
235 arguments start and end are interpreted as in slice notation.
236
237 Raise ValueError if not found.
238
239 """
Guido van Rossum15105651997-10-20 23:31:15 +0000240 if last is None: last = len(s)
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000241 res = rfind(s, sub, i, last)
Guido van Rossum710c3521994-08-17 13:16:11 +0000242 if res < 0:
243 raise ValueError, 'substring not found in string.index'
244 return res
Guido van Rossumb6775db1994-08-01 11:34:53 +0000245
246# Count non-overlapping occurrences of substring
Guido van Rossum15105651997-10-20 23:31:15 +0000247def count(s, sub, i = 0, last=None):
Guido van Rossum20032041997-12-29 19:26:28 +0000248 """count(s, sub[, start[,end]]) -> int
249
250 Return the number of occurrences of substring sub in string
251 s[start:end]. Optional arguments start and end are
252 interpreted as in slice notation.
253
254 """
Guido van Rossum15105651997-10-20 23:31:15 +0000255 Slen = len(s) # cache this value, for speed
256 if last is None:
257 last = Slen
258 elif last < 0:
259 last = max(0, last + Slen)
260 elif last > Slen:
261 last = Slen
262 if i < 0: i = max(0, i + Slen)
Guido van Rossumb6775db1994-08-01 11:34:53 +0000263 n = len(sub)
Guido van Rossum15105651997-10-20 23:31:15 +0000264 m = last + 1 - n
Guido van Rossumb6775db1994-08-01 11:34:53 +0000265 if n == 0: return m-i
266 r = 0
267 while i < m:
268 if sub == s[i:i+n]:
269 r = r+1
270 i = i+n
271 else:
272 i = i+1
Guido van Rossume65cce51993-11-08 15:05:21 +0000273 return r
274
Guido van Rossumd3166071993-05-24 14:16:22 +0000275# Find substring, return -1 if not found
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000276def find(s, sub, i = 0, last=None):
Guido van Rossum20032041997-12-29 19:26:28 +0000277 """find(s, sub [,start [,end]]) -> in
278
279 Return the lowest index in s where substring sub is found,
280 such that sub is contained within s[start,end]. Optional
281 arguments start and end are interpreted as in slice notation.
282
283 Return -1 on failure.
284
285 """
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000286 Slen = len(s) # cache this value, for speed
Guido van Rossum15105651997-10-20 23:31:15 +0000287 if last is None:
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000288 last = Slen
289 elif last < 0:
290 last = max(0, last + Slen)
291 elif last > Slen:
292 last = Slen
293 if i < 0: i = max(0, i + Slen)
Guido van Rossum710c3521994-08-17 13:16:11 +0000294 n = len(sub)
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000295 m = last + 1 - n
Guido van Rossum710c3521994-08-17 13:16:11 +0000296 while i < m:
297 if sub == s[i:i+n]: return i
298 i = i+1
299 return -1
Guido van Rossumc6360141990-10-13 19:23:40 +0000300
Guido van Rossume65cce51993-11-08 15:05:21 +0000301# Find last substring, return -1 if not found
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000302def rfind(s, sub, i = 0, last=None):
Guido van Rossum20032041997-12-29 19:26:28 +0000303 """rfind(s, sub [,start [,end]]) -> int
304
305 Return the highest index in s where substring sub is found,
306 such that sub is contained within s[start,end]. Optional
307 arguments start and end are interpreted as in slice notation.
308
Guido van Rossum23e21e71997-12-29 19:57:36 +0000309 Return -1 on failure.
Guido van Rossum20032041997-12-29 19:26:28 +0000310
311 """
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000312 Slen = len(s) # cache this value, for speed
Guido van Rossum15105651997-10-20 23:31:15 +0000313 if last is None:
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000314 last = Slen
315 elif last < 0:
316 last = max(0, last + Slen)
317 elif last > Slen:
318 last = Slen
319 if i < 0: i = max(0, i + Slen)
Guido van Rossum710c3521994-08-17 13:16:11 +0000320 n = len(sub)
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000321 m = last + 1 - n
Guido van Rossum710c3521994-08-17 13:16:11 +0000322 r = -1
323 while i < m:
324 if sub == s[i:i+n]: r = i
325 i = i+1
326 return r
Guido van Rossume65cce51993-11-08 15:05:21 +0000327
Guido van Rossumd0753e21997-12-10 22:59:55 +0000328# "Safe" environment for eval()
329safe_env = {"__builtins__": {}}
330
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000331# Convert string to float
Guido van Rossum9694fca1997-10-22 21:00:49 +0000332re = None
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000333def atof(str):
Guido van Rossum20032041997-12-29 19:26:28 +0000334 """atof(s) -> float
335
336 Return the floating point number represented by the string s.
337
338 """
Guido van Rossum9694fca1997-10-22 21:00:49 +0000339 global re
340 if re is None:
Guido van Rossum90d62ab1997-12-10 22:35:02 +0000341 # Don't fail if re doesn't exist -- just skip the syntax check
342 try:
343 import re
344 except ImportError:
345 re = 0
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000346 sign = ''
Guido van Rossum9694fca1997-10-22 21:00:49 +0000347 s = strip(str)
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000348 if s and s[0] in '+-':
349 sign = s[0]
350 s = s[1:]
Guido van Rossum710c3521994-08-17 13:16:11 +0000351 if not s:
352 raise ValueError, 'non-float argument to string.atof'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000353 while s[0] == '0' and len(s) > 1 and s[1] in digits: s = s[1:]
Guido van Rossum90d62ab1997-12-10 22:35:02 +0000354 if re and not re.match('[0-9]*(\.[0-9]*)?([eE][-+]?[0-9]+)?$', s):
Guido van Rossum710c3521994-08-17 13:16:11 +0000355 raise ValueError, 'non-float argument to string.atof'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000356 try:
Guido van Rossumd0753e21997-12-10 22:59:55 +0000357 return float(eval(sign + s, safe_env))
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000358 except SyntaxError:
Guido van Rossum710c3521994-08-17 13:16:11 +0000359 raise ValueError, 'non-float argument to string.atof'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000360
Guido van Rossumc6360141990-10-13 19:23:40 +0000361# Convert string to integer
Guido van Rossum8c1688e1995-03-14 17:43:02 +0000362def atoi(str, base=10):
Guido van Rossum20032041997-12-29 19:26:28 +0000363 """atoi(s [,base]) -> int
364
365 Return the integer represented by the string s in the given
366 base, which defaults to 10. The string s must consist of one
367 or more digits, possibly preceded by a sign. If base is 0, it
368 is chosen from the leading characters of s, 0 for octal, 0x or
369 0X for hexadecimal. If base is 16, a preceding 0x or 0X is
370 accepted.
371
372 """
Guido van Rossum8c1688e1995-03-14 17:43:02 +0000373 if base != 10:
374 # We only get here if strop doesn't define atoi()
375 raise ValueError, "this string.atoi doesn't support base != 10"
Guido van Rossum2d4aa4f1992-08-06 22:33:41 +0000376 sign = ''
Guido van Rossumc6360141990-10-13 19:23:40 +0000377 s = str
Guido van Rossumc629d341992-11-05 10:43:02 +0000378 if s and s[0] in '+-':
Guido van Rossum2d4aa4f1992-08-06 22:33:41 +0000379 sign = s[0]
380 s = s[1:]
Guido van Rossum710c3521994-08-17 13:16:11 +0000381 if not s:
382 raise ValueError, 'non-integer argument to string.atoi'
Guido van Rossum2d4aa4f1992-08-06 22:33:41 +0000383 while s[0] == '0' and len(s) > 1: s = s[1:]
Guido van Rossumc6360141990-10-13 19:23:40 +0000384 for c in s:
Guido van Rossum710c3521994-08-17 13:16:11 +0000385 if c not in digits:
386 raise ValueError, 'non-integer argument to string.atoi'
Guido van Rossumd0753e21997-12-10 22:59:55 +0000387 return eval(sign + s, safe_env)
Guido van Rossumc6360141990-10-13 19:23:40 +0000388
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000389# Convert string to long integer
Guido van Rossum8c1688e1995-03-14 17:43:02 +0000390def atol(str, base=10):
Guido van Rossum20032041997-12-29 19:26:28 +0000391 """atol(s [,base]) -> long
392
393 Return the long integer represented by the string s in the
394 given base, which defaults to 10. The string s must consist
395 of one or more digits, possibly preceded by a sign. If base
396 is 0, it is chosen from the leading characters of s, 0 for
397 octal, 0x or 0X for hexadecimal. If base is 16, a preceding
398 0x or 0X is accepted. A trailing L or l is not accepted,
399 unless base is 0.
400
401 """
Guido van Rossum8c1688e1995-03-14 17:43:02 +0000402 if base != 10:
403 # We only get here if strop doesn't define atol()
404 raise ValueError, "this string.atol doesn't support base != 10"
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000405 sign = ''
406 s = str
407 if s and s[0] in '+-':
408 sign = s[0]
409 s = s[1:]
Guido van Rossum710c3521994-08-17 13:16:11 +0000410 if not s:
411 raise ValueError, 'non-integer argument to string.atol'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000412 while s[0] == '0' and len(s) > 1: s = s[1:]
413 for c in s:
Guido van Rossum710c3521994-08-17 13:16:11 +0000414 if c not in digits:
415 raise ValueError, 'non-integer argument to string.atol'
Guido van Rossumd0753e21997-12-10 22:59:55 +0000416 return eval(sign + s + 'L', safe_env)
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000417
Guido van Rossumc6360141990-10-13 19:23:40 +0000418# Left-justify a string
419def ljust(s, width):
Guido van Rossum20032041997-12-29 19:26:28 +0000420 """ljust(s, width) -> string
421
422 Return a left-justified version of s, in a field of the
423 specified width, padded with spaces as needed. The string is
424 never truncated.
425
426 """
Guido van Rossumfac38b71991-04-07 13:42:19 +0000427 n = width - len(s)
428 if n <= 0: return s
429 return s + ' '*n
Guido van Rossumc6360141990-10-13 19:23:40 +0000430
431# Right-justify a string
432def rjust(s, width):
Guido van Rossum20032041997-12-29 19:26:28 +0000433 """rjust(s, width) -> string
434
435 Return a right-justified version of s, in a field of the
436 specified width, padded with spaces as needed. The string is
437 never truncated.
438
439 """
Guido van Rossumfac38b71991-04-07 13:42:19 +0000440 n = width - len(s)
441 if n <= 0: return s
442 return ' '*n + s
Guido van Rossumc6360141990-10-13 19:23:40 +0000443
444# Center a string
445def center(s, width):
Guido van Rossum20032041997-12-29 19:26:28 +0000446 """center(s, width) -> string
447
448 Return a center version of s, in a field of the specified
449 width. padded with spaces as needed. The string is never
450 truncated.
451
452 """
Guido van Rossumfac38b71991-04-07 13:42:19 +0000453 n = width - len(s)
454 if n <= 0: return s
455 half = n/2
456 if n%2 and width%2:
457 # This ensures that center(center(s, i), j) = center(s, j)
458 half = half+1
459 return ' '*half + s + ' '*(n-half)
Guido van Rossumc6360141990-10-13 19:23:40 +0000460
461# Zero-fill a number, e.g., (12, 3) --> '012' and (-3, 3) --> '-03'
462# Decadent feature: the argument may be a string or a number
463# (Use of this is deprecated; it should be a string as with ljust c.s.)
464def zfill(x, width):
Guido van Rossum20032041997-12-29 19:26:28 +0000465 """zfill(x, width) -> string
466
467 Pad a numeric string x with zeros on the left, to fill a field
468 of the specified width. The string x is never truncated.
469
470 """
Guido van Rossumbdfcfcc1992-01-01 19:35:13 +0000471 if type(x) == type(''): s = x
Guido van Rossumc6360141990-10-13 19:23:40 +0000472 else: s = `x`
473 n = len(s)
474 if n >= width: return s
475 sign = ''
Guido van Rossum333c2e01991-08-16 13:29:03 +0000476 if s[0] in ('-', '+'):
477 sign, s = s[0], s[1:]
Guido van Rossumc6360141990-10-13 19:23:40 +0000478 return sign + '0'*(width-n) + s
Guido van Rossum6ff2e901992-03-27 15:13:31 +0000479
480# Expand tabs in a string.
481# Doesn't take non-printing chars into account, but does understand \n.
Guido van Rossum894a7bb1995-08-10 19:42:05 +0000482def expandtabs(s, tabsize=8):
Guido van Rossum20032041997-12-29 19:26:28 +0000483 """expandtabs(s [,tabsize]) -> string
484
485 Return a copy of the string s with all tab characters replaced
486 by the appropriate number of spaces, depending on the current
Guido van Rossum23e21e71997-12-29 19:57:36 +0000487 column, and the tabsize (default 8).
Guido van Rossum20032041997-12-29 19:26:28 +0000488
489 """
Guido van Rossum6ff2e901992-03-27 15:13:31 +0000490 res = line = ''
491 for c in s:
492 if c == '\t':
493 c = ' '*(tabsize - len(line)%tabsize)
494 line = line + c
495 if c == '\n':
496 res = res + line
497 line = ''
498 return res + line
Guido van Rossum2db91351992-10-18 17:09:59 +0000499
Guido van Rossum25395281996-05-28 23:08:45 +0000500# Character translation through look-up table.
Guido van Rossumed7253c1996-07-23 18:12:39 +0000501def translate(s, table, deletions=""):
Guido van Rossum20032041997-12-29 19:26:28 +0000502 """translate(s,table [,deletechars]) -> string
503
504 Return a copy of the string s, where all characters occurring
505 in the optional argument deletechars are removed, and the
506 remaining characters have been mapped through the given
507 translation table, which must be a string of length 256.
508
509 """
Guido van Rossumed7253c1996-07-23 18:12:39 +0000510 if type(table) != type('') or len(table) != 256:
511 raise TypeError, "translation table must be 256 characters long"
512 res = ""
513 for c in s:
514 if c not in deletions:
515 res = res + table[ord(c)]
516 return res
Guido van Rossum2db91351992-10-18 17:09:59 +0000517
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000518# Capitalize a string, e.g. "aBc dEf" -> "Abc def".
519def capitalize(s):
Guido van Rossum20032041997-12-29 19:26:28 +0000520 """capitalize(s) -> string
521
522 Return a copy of the string s with only its first character
523 capitalized.
524
525 """
Guido van Rossumed7253c1996-07-23 18:12:39 +0000526 return upper(s[:1]) + lower(s[1:])
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000527
528# Capitalize the words in a string, e.g. " aBc dEf " -> "Abc Def".
529# See also regsub.capwords().
Guido van Rossum34f17311996-08-20 20:25:41 +0000530def capwords(s, sep=None):
Guido van Rossum20032041997-12-29 19:26:28 +0000531 """capwords(s, [sep]) -> string
532
533 Split the argument into words using split, capitalize each
534 word using capitalize, and join the capitalized words using
535 join. Note that this replaces runs of whitespace characters by
536 a single space.
537
538 """
Guido van Rossumf480c671996-08-26 15:55:00 +0000539 return join(map(capitalize, split(s, sep)), sep or ' ')
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000540
Guido van Rossumed7253c1996-07-23 18:12:39 +0000541# Construct a translation string
542_idmapL = None
543def maketrans(fromstr, tostr):
Guido van Rossum20032041997-12-29 19:26:28 +0000544 """maketrans(frm, to) -> string
545
546 Return a translation table (a string of 256 bytes long)
547 suitable for use in string.translate. The strings frm and to
548 must be of the same length.
549
550 """
Guido van Rossumed7253c1996-07-23 18:12:39 +0000551 if len(fromstr) != len(tostr):
552 raise ValueError, "maketrans arguments must have same length"
553 global _idmapL
554 if not _idmapL:
555 _idmapL = map(None, _idmap)
556 L = _idmapL[:]
557 fromstr = map(ord, fromstr)
558 for i in range(len(fromstr)):
559 L[fromstr[i]] = tostr[i]
560 return joinfields(L, "")
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000561
Guido van Rossum1eb9a811997-03-25 16:50:31 +0000562# Substring replacement (global)
Guido van Rossum21aa0ef1997-04-02 05:49:46 +0000563def replace(str, old, new, maxsplit=0):
Guido van Rossum20032041997-12-29 19:26:28 +0000564 """replace (str, old, new[, maxsplit]) -> string
565
566 Return a copy of string str with all occurrences of substring
567 old replaced by new. If the optional argument maxsplit is
568 given, only the first maxsplit occurrences are replaced.
569
570 """
Guido van Rossum21aa0ef1997-04-02 05:49:46 +0000571 return joinfields(splitfields(str, old, maxsplit), new)
Guido van Rossum1eb9a811997-03-25 16:50:31 +0000572
573
Guido van Rossum2db91351992-10-18 17:09:59 +0000574# Try importing optional built-in module "strop" -- if it exists,
575# it redefines some string operations that are 100-1000 times faster.
Guido van Rossum8e2ec561993-07-29 09:37:38 +0000576# It also defines values for whitespace, lowercase and uppercase
577# that match <ctype.h>'s definitions.
Guido van Rossum2db91351992-10-18 17:09:59 +0000578
579try:
580 from strop import *
Guido van Rossum8e2ec561993-07-29 09:37:38 +0000581 letters = lowercase + uppercase
Guido van Rossumb6775db1994-08-01 11:34:53 +0000582except ImportError:
583 pass # Use the original, slow versions