blob: 8207a8ea97f6d7dd841427d35727c6e0d61c6fee [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
7# Some strings for ctype-style character classification
Guido van Rossum8e2ec561993-07-29 09:37:38 +00008whitespace = ' \t\n\r\v\f'
Guido van Rossumc6360141990-10-13 19:23:40 +00009lowercase = 'abcdefghijklmnopqrstuvwxyz'
10uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
11letters = lowercase + uppercase
12digits = '0123456789'
13hexdigits = digits + 'abcdef' + 'ABCDEF'
14octdigits = '01234567'
15
16# Case conversion helpers
Guido van Rossuma61ff7b1992-01-14 18:31:29 +000017_idmap = ''
18for i in range(256): _idmap = _idmap + chr(i)
19_lower = _idmap[:ord('A')] + lowercase + _idmap[ord('Z')+1:]
20_upper = _idmap[:ord('a')] + uppercase + _idmap[ord('z')+1:]
21_swapcase = _upper[:ord('A')] + lowercase + _upper[ord('Z')+1:]
Guido van Rossumc6360141990-10-13 19:23:40 +000022del i
23
Guido van Rossum710c3521994-08-17 13:16:11 +000024# Backward compatible names for exceptions
25index_error = ValueError
26atoi_error = ValueError
27atof_error = ValueError
28atol_error = ValueError
29
Guido van Rossumc6360141990-10-13 19:23:40 +000030# convert UPPER CASE letters to lower case
31def lower(s):
32 res = ''
33 for c in s:
Guido van Rossuma61ff7b1992-01-14 18:31:29 +000034 res = res + _lower[ord(c)]
Guido van Rossumc6360141990-10-13 19:23:40 +000035 return res
36
37# Convert lower case letters to UPPER CASE
38def upper(s):
39 res = ''
40 for c in s:
Guido van Rossuma61ff7b1992-01-14 18:31:29 +000041 res = res + _upper[ord(c)]
Guido van Rossumc6360141990-10-13 19:23:40 +000042 return res
43
44# Swap lower case letters and UPPER CASE
45def swapcase(s):
46 res = ''
47 for c in s:
Guido van Rossuma61ff7b1992-01-14 18:31:29 +000048 res = res + _swapcase[ord(c)]
Guido van Rossumc6360141990-10-13 19:23:40 +000049 return res
50
51# Strip leading and trailing tabs and spaces
52def strip(s):
53 i, j = 0, len(s)
54 while i < j and s[i] in whitespace: i = i+1
55 while i < j and s[j-1] in whitespace: j = j-1
56 return s[i:j]
57
Guido van Rossum306a8a61996-08-08 18:40:59 +000058# Strip leading tabs and spaces
59def lstrip(s):
60 i, j = 0, len(s)
61 while i < j and s[i] in whitespace: i = i+1
62 return s[i:j]
63
64# Strip trailing tabs and spaces
65def rstrip(s):
66 i, j = 0, len(s)
67 while i < j and s[j-1] in whitespace: j = j-1
68 return s[i:j]
69
70
Guido van Rossumc6360141990-10-13 19:23:40 +000071# Split a string into a list of space/tab-separated words
72# NB: split(s) is NOT the same as splitfields(s, ' ')!
Guido van Rossum306a8a61996-08-08 18:40:59 +000073def split(s, sep=None, maxsplit=0):
74 if sep is not None: return splitfields(s, sep, maxsplit)
Guido van Rossumc6360141990-10-13 19:23:40 +000075 res = []
76 i, n = 0, len(s)
77 while i < n:
78 while i < n and s[i] in whitespace: i = i+1
Guido van Rossumbdfcfcc1992-01-01 19:35:13 +000079 if i == n: break
Guido van Rossumc6360141990-10-13 19:23:40 +000080 j = i
81 while j < n and s[j] not in whitespace: j = j+1
82 res.append(s[i:j])
83 i = j
84 return res
85
86# Split a list into fields separated by a given string
87# NB: splitfields(s, ' ') is NOT the same as split(s)!
Guido van Rossum7a461e51992-09-20 21:41:09 +000088# splitfields(s, '') returns [s] (in analogy with split() in nawk)
Guido van Rossum306a8a61996-08-08 18:40:59 +000089def splitfields(s, sep=None, maxsplit=0):
90 if sep is None: return split(s, None, maxsplit)
Guido van Rossumc6360141990-10-13 19:23:40 +000091 res = []
Guido van Rossumc6360141990-10-13 19:23:40 +000092 nsep = len(sep)
Guido van Rossumae507a41992-08-19 16:49:58 +000093 if nsep == 0:
Guido van Rossum7a461e51992-09-20 21:41:09 +000094 return [s]
Guido van Rossumae507a41992-08-19 16:49:58 +000095 ns = len(s)
Guido van Rossumc6360141990-10-13 19:23:40 +000096 i = j = 0
Guido van Rossum306a8a61996-08-08 18:40:59 +000097 count = 0
Guido van Rossumc6360141990-10-13 19:23:40 +000098 while j+nsep <= ns:
Guido van Rossumbdfcfcc1992-01-01 19:35:13 +000099 if s[j:j+nsep] == sep:
Guido van Rossum306a8a61996-08-08 18:40:59 +0000100 count = count + 1
Guido van Rossumc6360141990-10-13 19:23:40 +0000101 res.append(s[i:j])
102 i = j = j + nsep
Guido van Rossum306a8a61996-08-08 18:40:59 +0000103 if (maxsplit and (count >= maxsplit)):
104 break
105
Guido van Rossumc6360141990-10-13 19:23:40 +0000106 else:
107 j = j + 1
108 res.append(s[i:])
109 return res
110
Guido van Rossumfac38b71991-04-07 13:42:19 +0000111# Join words with spaces between them
Guido van Rossum2ab19921995-06-22 18:58:00 +0000112def join(words, sep = ' '):
113 return joinfields(words, sep)
Guido van Rossumfac38b71991-04-07 13:42:19 +0000114
Guido van Rossum2ab19921995-06-22 18:58:00 +0000115# Join fields with optional separator
116def joinfields(words, sep = ' '):
Guido van Rossumfac38b71991-04-07 13:42:19 +0000117 res = ''
118 for w in words:
119 res = res + (sep + w)
120 return res[len(sep):]
121
Guido van Rossumd3166071993-05-24 14:16:22 +0000122# Find substring, raise exception if not found
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000123def index(s, sub, i = 0, last=None):
124 if last == None: last = len(s)
125 res = find(s, sub, i, last)
Guido van Rossum710c3521994-08-17 13:16:11 +0000126 if res < 0:
127 raise ValueError, 'substring not found in string.index'
128 return res
Guido van Rossumd3166071993-05-24 14:16:22 +0000129
Guido van Rossume65cce51993-11-08 15:05:21 +0000130# Find last substring, raise exception if not found
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000131def rindex(s, sub, i = 0, last=None):
132 if last == None: last = len(s)
133 res = rfind(s, sub, i, last)
Guido van Rossum710c3521994-08-17 13:16:11 +0000134 if res < 0:
135 raise ValueError, 'substring not found in string.index'
136 return res
Guido van Rossumb6775db1994-08-01 11:34:53 +0000137
138# Count non-overlapping occurrences of substring
139def count(s, sub, i = 0):
Guido van Rossum8c1688e1995-03-14 17:43:02 +0000140 if i < 0: i = max(0, i + len(s))
Guido van Rossumb6775db1994-08-01 11:34:53 +0000141 n = len(sub)
142 m = len(s) + 1 - n
143 if n == 0: return m-i
144 r = 0
145 while i < m:
146 if sub == s[i:i+n]:
147 r = r+1
148 i = i+n
149 else:
150 i = i+1
Guido van Rossume65cce51993-11-08 15:05:21 +0000151 return r
152
Guido van Rossumd3166071993-05-24 14:16:22 +0000153# Find substring, return -1 if not found
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000154def find(s, sub, i = 0, last=None):
155 Slen = len(s) # cache this value, for speed
156 if last == None:
157 last = Slen
158 elif last < 0:
159 last = max(0, last + Slen)
160 elif last > Slen:
161 last = Slen
162 if i < 0: i = max(0, i + Slen)
Guido van Rossum710c3521994-08-17 13:16:11 +0000163 n = len(sub)
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000164 m = last + 1 - n
Guido van Rossum710c3521994-08-17 13:16:11 +0000165 while i < m:
166 if sub == s[i:i+n]: return i
167 i = i+1
168 return -1
Guido van Rossumc6360141990-10-13 19:23:40 +0000169
Guido van Rossume65cce51993-11-08 15:05:21 +0000170# Find last substring, return -1 if not found
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000171def rfind(s, sub, i = 0, last=None):
172 Slen = len(s) # cache this value, for speed
173 if last == None:
174 last = Slen
175 elif last < 0:
176 last = max(0, last + Slen)
177 elif last > Slen:
178 last = Slen
179 if i < 0: i = max(0, i + Slen)
Guido van Rossum710c3521994-08-17 13:16:11 +0000180 n = len(sub)
Guido van Rossum7b7c5781997-03-14 04:13:56 +0000181 m = last + 1 - n
Guido van Rossum710c3521994-08-17 13:16:11 +0000182 r = -1
183 while i < m:
184 if sub == s[i:i+n]: r = i
185 i = i+1
186 return r
Guido van Rossume65cce51993-11-08 15:05:21 +0000187
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000188# Convert string to float
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000189def atof(str):
190 import regex
191 sign = ''
192 s = str
193 if s and s[0] in '+-':
194 sign = s[0]
195 s = s[1:]
Guido van Rossum710c3521994-08-17 13:16:11 +0000196 if not s:
197 raise ValueError, 'non-float argument to string.atof'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000198 while s[0] == '0' and len(s) > 1 and s[1] in digits: s = s[1:]
199 if regex.match('[0-9]*\(\.[0-9]*\)?\([eE][-+]?[0-9]+\)?', s) != len(s):
Guido van Rossum710c3521994-08-17 13:16:11 +0000200 raise ValueError, 'non-float argument to string.atof'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000201 try:
Guido van Rossumb6775db1994-08-01 11:34:53 +0000202 return float(eval(sign + s))
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000203 except SyntaxError:
Guido van Rossum710c3521994-08-17 13:16:11 +0000204 raise ValueError, 'non-float argument to string.atof'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000205
Guido van Rossumc6360141990-10-13 19:23:40 +0000206# Convert string to integer
Guido van Rossum8c1688e1995-03-14 17:43:02 +0000207def atoi(str, base=10):
208 if base != 10:
209 # We only get here if strop doesn't define atoi()
210 raise ValueError, "this string.atoi doesn't support base != 10"
Guido van Rossum2d4aa4f1992-08-06 22:33:41 +0000211 sign = ''
Guido van Rossumc6360141990-10-13 19:23:40 +0000212 s = str
Guido van Rossumc629d341992-11-05 10:43:02 +0000213 if s and s[0] in '+-':
Guido van Rossum2d4aa4f1992-08-06 22:33:41 +0000214 sign = s[0]
215 s = s[1:]
Guido van Rossum710c3521994-08-17 13:16:11 +0000216 if not s:
217 raise ValueError, 'non-integer argument to string.atoi'
Guido van Rossum2d4aa4f1992-08-06 22:33:41 +0000218 while s[0] == '0' and len(s) > 1: s = s[1:]
Guido van Rossumc6360141990-10-13 19:23:40 +0000219 for c in s:
Guido van Rossum710c3521994-08-17 13:16:11 +0000220 if c not in digits:
221 raise ValueError, 'non-integer argument to string.atoi'
Guido van Rossum2d4aa4f1992-08-06 22:33:41 +0000222 return eval(sign + s)
Guido van Rossumc6360141990-10-13 19:23:40 +0000223
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000224# Convert string to long integer
Guido van Rossum8c1688e1995-03-14 17:43:02 +0000225def atol(str, base=10):
226 if base != 10:
227 # We only get here if strop doesn't define atol()
228 raise ValueError, "this string.atol doesn't support base != 10"
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000229 sign = ''
230 s = str
231 if s and s[0] in '+-':
232 sign = s[0]
233 s = s[1:]
Guido van Rossum710c3521994-08-17 13:16:11 +0000234 if not s:
235 raise ValueError, 'non-integer argument to string.atol'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000236 while s[0] == '0' and len(s) > 1: s = s[1:]
237 for c in s:
Guido van Rossum710c3521994-08-17 13:16:11 +0000238 if c not in digits:
239 raise ValueError, 'non-integer argument to string.atol'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000240 return eval(sign + s + 'L')
241
Guido van Rossumc6360141990-10-13 19:23:40 +0000242# Left-justify a string
243def ljust(s, width):
Guido van Rossumfac38b71991-04-07 13:42:19 +0000244 n = width - len(s)
245 if n <= 0: return s
246 return s + ' '*n
Guido van Rossumc6360141990-10-13 19:23:40 +0000247
248# Right-justify a string
249def rjust(s, width):
Guido van Rossumfac38b71991-04-07 13:42:19 +0000250 n = width - len(s)
251 if n <= 0: return s
252 return ' '*n + s
Guido van Rossumc6360141990-10-13 19:23:40 +0000253
254# Center a string
255def center(s, width):
Guido van Rossumfac38b71991-04-07 13:42:19 +0000256 n = width - len(s)
257 if n <= 0: return s
258 half = n/2
259 if n%2 and width%2:
260 # This ensures that center(center(s, i), j) = center(s, j)
261 half = half+1
262 return ' '*half + s + ' '*(n-half)
Guido van Rossumc6360141990-10-13 19:23:40 +0000263
264# Zero-fill a number, e.g., (12, 3) --> '012' and (-3, 3) --> '-03'
265# Decadent feature: the argument may be a string or a number
266# (Use of this is deprecated; it should be a string as with ljust c.s.)
267def zfill(x, width):
Guido van Rossumbdfcfcc1992-01-01 19:35:13 +0000268 if type(x) == type(''): s = x
Guido van Rossumc6360141990-10-13 19:23:40 +0000269 else: s = `x`
270 n = len(s)
271 if n >= width: return s
272 sign = ''
Guido van Rossum333c2e01991-08-16 13:29:03 +0000273 if s[0] in ('-', '+'):
274 sign, s = s[0], s[1:]
Guido van Rossumc6360141990-10-13 19:23:40 +0000275 return sign + '0'*(width-n) + s
Guido van Rossum6ff2e901992-03-27 15:13:31 +0000276
277# Expand tabs in a string.
278# Doesn't take non-printing chars into account, but does understand \n.
Guido van Rossum894a7bb1995-08-10 19:42:05 +0000279def expandtabs(s, tabsize=8):
Guido van Rossum6ff2e901992-03-27 15:13:31 +0000280 res = line = ''
281 for c in s:
282 if c == '\t':
283 c = ' '*(tabsize - len(line)%tabsize)
284 line = line + c
285 if c == '\n':
286 res = res + line
287 line = ''
288 return res + line
Guido van Rossum2db91351992-10-18 17:09:59 +0000289
Guido van Rossum25395281996-05-28 23:08:45 +0000290# Character translation through look-up table.
Guido van Rossumed7253c1996-07-23 18:12:39 +0000291def translate(s, table, deletions=""):
292 if type(table) != type('') or len(table) != 256:
293 raise TypeError, "translation table must be 256 characters long"
294 res = ""
295 for c in s:
296 if c not in deletions:
297 res = res + table[ord(c)]
298 return res
Guido van Rossum2db91351992-10-18 17:09:59 +0000299
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000300# Capitalize a string, e.g. "aBc dEf" -> "Abc def".
301def capitalize(s):
Guido van Rossumed7253c1996-07-23 18:12:39 +0000302 return upper(s[:1]) + lower(s[1:])
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000303
304# Capitalize the words in a string, e.g. " aBc dEf " -> "Abc Def".
305# See also regsub.capwords().
Guido van Rossum34f17311996-08-20 20:25:41 +0000306def capwords(s, sep=None):
Guido van Rossumf480c671996-08-26 15:55:00 +0000307 return join(map(capitalize, split(s, sep)), sep or ' ')
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000308
Guido van Rossumed7253c1996-07-23 18:12:39 +0000309# Construct a translation string
310_idmapL = None
311def maketrans(fromstr, tostr):
312 if len(fromstr) != len(tostr):
313 raise ValueError, "maketrans arguments must have same length"
314 global _idmapL
315 if not _idmapL:
316 _idmapL = map(None, _idmap)
317 L = _idmapL[:]
318 fromstr = map(ord, fromstr)
319 for i in range(len(fromstr)):
320 L[fromstr[i]] = tostr[i]
321 return joinfields(L, "")
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000322
Guido van Rossum1eb9a811997-03-25 16:50:31 +0000323# Substring replacement (global)
324def replace(old, new, str):
325 return joinfields(splitfields(str, old), new)
326
327# Substring replacement (1st substring only)
328def replace1(old, new, str, i=0, last=None):
329 if last is None:
330 i = find(str, old, i)
331 else:
332 i = find(str, old, i, last)
333 if i >= 0:
334 str = str[:i] + new + str[i+len(old):]
335 return str
336
337
Guido van Rossum2db91351992-10-18 17:09:59 +0000338# Try importing optional built-in module "strop" -- if it exists,
339# it redefines some string operations that are 100-1000 times faster.
Guido van Rossum8e2ec561993-07-29 09:37:38 +0000340# It also defines values for whitespace, lowercase and uppercase
341# that match <ctype.h>'s definitions.
Guido van Rossum2db91351992-10-18 17:09:59 +0000342
343try:
344 from strop import *
Guido van Rossum8e2ec561993-07-29 09:37:38 +0000345 letters = lowercase + uppercase
Guido van Rossumb6775db1994-08-01 11:34:53 +0000346except ImportError:
347 pass # Use the original, slow versions