blob: edf24a4e2f621ff49f8c7e42cb364331b1afbdec [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
58# Split a string into a list of space/tab-separated words
59# NB: split(s) is NOT the same as splitfields(s, ' ')!
Guido van Rossum2ab19921995-06-22 18:58:00 +000060def split(s, sep=None):
61 if sep is not None: return splitfields(s, sep)
Guido van Rossumc6360141990-10-13 19:23:40 +000062 res = []
63 i, n = 0, len(s)
64 while i < n:
65 while i < n and s[i] in whitespace: i = i+1
Guido van Rossumbdfcfcc1992-01-01 19:35:13 +000066 if i == n: break
Guido van Rossumc6360141990-10-13 19:23:40 +000067 j = i
68 while j < n and s[j] not in whitespace: j = j+1
69 res.append(s[i:j])
70 i = j
71 return res
72
73# Split a list into fields separated by a given string
74# NB: splitfields(s, ' ') is NOT the same as split(s)!
Guido van Rossum7a461e51992-09-20 21:41:09 +000075# splitfields(s, '') returns [s] (in analogy with split() in nawk)
Guido van Rossum2ab19921995-06-22 18:58:00 +000076def splitfields(s, sep=None):
77 if sep is None: return split(s)
Guido van Rossumc6360141990-10-13 19:23:40 +000078 res = []
Guido van Rossumc6360141990-10-13 19:23:40 +000079 nsep = len(sep)
Guido van Rossumae507a41992-08-19 16:49:58 +000080 if nsep == 0:
Guido van Rossum7a461e51992-09-20 21:41:09 +000081 return [s]
Guido van Rossumae507a41992-08-19 16:49:58 +000082 ns = len(s)
Guido van Rossumc6360141990-10-13 19:23:40 +000083 i = j = 0
84 while j+nsep <= ns:
Guido van Rossumbdfcfcc1992-01-01 19:35:13 +000085 if s[j:j+nsep] == sep:
Guido van Rossumc6360141990-10-13 19:23:40 +000086 res.append(s[i:j])
87 i = j = j + nsep
88 else:
89 j = j + 1
90 res.append(s[i:])
91 return res
92
Guido van Rossumfac38b71991-04-07 13:42:19 +000093# Join words with spaces between them
Guido van Rossum2ab19921995-06-22 18:58:00 +000094def join(words, sep = ' '):
95 return joinfields(words, sep)
Guido van Rossumfac38b71991-04-07 13:42:19 +000096
Guido van Rossum2ab19921995-06-22 18:58:00 +000097# Join fields with optional separator
98def joinfields(words, sep = ' '):
Guido van Rossumfac38b71991-04-07 13:42:19 +000099 res = ''
100 for w in words:
101 res = res + (sep + w)
102 return res[len(sep):]
103
Guido van Rossumd3166071993-05-24 14:16:22 +0000104# Find substring, raise exception if not found
Guido van Rossumb6775db1994-08-01 11:34:53 +0000105def index(s, sub, i = 0):
Guido van Rossum710c3521994-08-17 13:16:11 +0000106 res = find(s, sub, i)
107 if res < 0:
108 raise ValueError, 'substring not found in string.index'
109 return res
Guido van Rossumd3166071993-05-24 14:16:22 +0000110
Guido van Rossume65cce51993-11-08 15:05:21 +0000111# Find last substring, raise exception if not found
Guido van Rossumb6775db1994-08-01 11:34:53 +0000112def rindex(s, sub, i = 0):
Guido van Rossum710c3521994-08-17 13:16:11 +0000113 res = rfind(s, sub, i)
114 if res < 0:
115 raise ValueError, 'substring not found in string.index'
116 return res
Guido van Rossumb6775db1994-08-01 11:34:53 +0000117
118# Count non-overlapping occurrences of substring
119def count(s, sub, i = 0):
Guido van Rossum8c1688e1995-03-14 17:43:02 +0000120 if i < 0: i = max(0, i + len(s))
Guido van Rossumb6775db1994-08-01 11:34:53 +0000121 n = len(sub)
122 m = len(s) + 1 - n
123 if n == 0: return m-i
124 r = 0
125 while i < m:
126 if sub == s[i:i+n]:
127 r = r+1
128 i = i+n
129 else:
130 i = i+1
Guido van Rossume65cce51993-11-08 15:05:21 +0000131 return r
132
Guido van Rossumd3166071993-05-24 14:16:22 +0000133# Find substring, return -1 if not found
Guido van Rossumb6775db1994-08-01 11:34:53 +0000134def find(s, sub, i = 0):
Guido van Rossum8c1688e1995-03-14 17:43:02 +0000135 if i < 0: i = max(0, i + len(s))
Guido van Rossum710c3521994-08-17 13:16:11 +0000136 n = len(sub)
137 m = len(s) + 1 - n
138 while i < m:
139 if sub == s[i:i+n]: return i
140 i = i+1
141 return -1
Guido van Rossumc6360141990-10-13 19:23:40 +0000142
Guido van Rossume65cce51993-11-08 15:05:21 +0000143# Find last substring, return -1 if not found
Guido van Rossumb6775db1994-08-01 11:34:53 +0000144def rfind(s, sub, i = 0):
Guido van Rossum8c1688e1995-03-14 17:43:02 +0000145 if i < 0: i = max(0, i + len(s))
Guido van Rossum710c3521994-08-17 13:16:11 +0000146 n = len(sub)
147 m = len(s) + 1 - n
148 r = -1
149 while i < m:
150 if sub == s[i:i+n]: r = i
151 i = i+1
152 return r
Guido van Rossume65cce51993-11-08 15:05:21 +0000153
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000154# Convert string to float
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000155def atof(str):
156 import regex
157 sign = ''
158 s = str
159 if s and s[0] in '+-':
160 sign = s[0]
161 s = s[1:]
Guido van Rossum710c3521994-08-17 13:16:11 +0000162 if not s:
163 raise ValueError, 'non-float argument to string.atof'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000164 while s[0] == '0' and len(s) > 1 and s[1] in digits: s = s[1:]
165 if regex.match('[0-9]*\(\.[0-9]*\)?\([eE][-+]?[0-9]+\)?', s) != len(s):
Guido van Rossum710c3521994-08-17 13:16:11 +0000166 raise ValueError, 'non-float argument to string.atof'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000167 try:
Guido van Rossumb6775db1994-08-01 11:34:53 +0000168 return float(eval(sign + s))
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000169 except SyntaxError:
Guido van Rossum710c3521994-08-17 13:16:11 +0000170 raise ValueError, 'non-float argument to string.atof'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000171
Guido van Rossumc6360141990-10-13 19:23:40 +0000172# Convert string to integer
Guido van Rossum8c1688e1995-03-14 17:43:02 +0000173def atoi(str, base=10):
174 if base != 10:
175 # We only get here if strop doesn't define atoi()
176 raise ValueError, "this string.atoi doesn't support base != 10"
Guido van Rossum2d4aa4f1992-08-06 22:33:41 +0000177 sign = ''
Guido van Rossumc6360141990-10-13 19:23:40 +0000178 s = str
Guido van Rossumc629d341992-11-05 10:43:02 +0000179 if s and s[0] in '+-':
Guido van Rossum2d4aa4f1992-08-06 22:33:41 +0000180 sign = s[0]
181 s = s[1:]
Guido van Rossum710c3521994-08-17 13:16:11 +0000182 if not s:
183 raise ValueError, 'non-integer argument to string.atoi'
Guido van Rossum2d4aa4f1992-08-06 22:33:41 +0000184 while s[0] == '0' and len(s) > 1: s = s[1:]
Guido van Rossumc6360141990-10-13 19:23:40 +0000185 for c in s:
Guido van Rossum710c3521994-08-17 13:16:11 +0000186 if c not in digits:
187 raise ValueError, 'non-integer argument to string.atoi'
Guido van Rossum2d4aa4f1992-08-06 22:33:41 +0000188 return eval(sign + s)
Guido van Rossumc6360141990-10-13 19:23:40 +0000189
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000190# Convert string to long integer
Guido van Rossum8c1688e1995-03-14 17:43:02 +0000191def atol(str, base=10):
192 if base != 10:
193 # We only get here if strop doesn't define atol()
194 raise ValueError, "this string.atol doesn't support base != 10"
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000195 sign = ''
196 s = str
197 if s and s[0] in '+-':
198 sign = s[0]
199 s = s[1:]
Guido van Rossum710c3521994-08-17 13:16:11 +0000200 if not s:
201 raise ValueError, 'non-integer argument to string.atol'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000202 while s[0] == '0' and len(s) > 1: s = s[1:]
203 for c in s:
Guido van Rossum710c3521994-08-17 13:16:11 +0000204 if c not in digits:
205 raise ValueError, 'non-integer argument to string.atol'
Guido van Rossume61fa0a1993-10-22 13:56:35 +0000206 return eval(sign + s + 'L')
207
Guido van Rossumc6360141990-10-13 19:23:40 +0000208# Left-justify a string
209def ljust(s, width):
Guido van Rossumfac38b71991-04-07 13:42:19 +0000210 n = width - len(s)
211 if n <= 0: return s
212 return s + ' '*n
Guido van Rossumc6360141990-10-13 19:23:40 +0000213
214# Right-justify a string
215def rjust(s, width):
Guido van Rossumfac38b71991-04-07 13:42:19 +0000216 n = width - len(s)
217 if n <= 0: return s
218 return ' '*n + s
Guido van Rossumc6360141990-10-13 19:23:40 +0000219
220# Center a string
221def center(s, width):
Guido van Rossumfac38b71991-04-07 13:42:19 +0000222 n = width - len(s)
223 if n <= 0: return s
224 half = n/2
225 if n%2 and width%2:
226 # This ensures that center(center(s, i), j) = center(s, j)
227 half = half+1
228 return ' '*half + s + ' '*(n-half)
Guido van Rossumc6360141990-10-13 19:23:40 +0000229
230# Zero-fill a number, e.g., (12, 3) --> '012' and (-3, 3) --> '-03'
231# Decadent feature: the argument may be a string or a number
232# (Use of this is deprecated; it should be a string as with ljust c.s.)
233def zfill(x, width):
Guido van Rossumbdfcfcc1992-01-01 19:35:13 +0000234 if type(x) == type(''): s = x
Guido van Rossumc6360141990-10-13 19:23:40 +0000235 else: s = `x`
236 n = len(s)
237 if n >= width: return s
238 sign = ''
Guido van Rossum333c2e01991-08-16 13:29:03 +0000239 if s[0] in ('-', '+'):
240 sign, s = s[0], s[1:]
Guido van Rossumc6360141990-10-13 19:23:40 +0000241 return sign + '0'*(width-n) + s
Guido van Rossum6ff2e901992-03-27 15:13:31 +0000242
243# Expand tabs in a string.
244# Doesn't take non-printing chars into account, but does understand \n.
Guido van Rossum894a7bb1995-08-10 19:42:05 +0000245def expandtabs(s, tabsize=8):
Guido van Rossum6ff2e901992-03-27 15:13:31 +0000246 res = line = ''
247 for c in s:
248 if c == '\t':
249 c = ' '*(tabsize - len(line)%tabsize)
250 line = line + c
251 if c == '\n':
252 res = res + line
253 line = ''
254 return res + line
Guido van Rossum2db91351992-10-18 17:09:59 +0000255
Guido van Rossum25395281996-05-28 23:08:45 +0000256# Character translation through look-up table.
257def translate(s, table):
258 if type(table) != type('') or len(table) != 256:
259 raise TypeError, "translation table must be 256-char string"
260 res = ""
261 for c in s:
262 res = res + table[ord(c)]
263 return res
Guido van Rossum2db91351992-10-18 17:09:59 +0000264
Guido van Rossum8775d8b1996-06-11 18:43:00 +0000265# Capitalize a string, e.g. "aBc dEf" -> "Abc def".
266def capitalize(s):
267 return upper(s[:1]) + lower(s[1:])
268
269# Capitalize the words in a string, e.g. " aBc dEf " -> "Abc Def".
270# See also regsub.capwords().
271def capwords(s):
272 return join(map(capitalize, split(s)))
273
274
Guido van Rossum2db91351992-10-18 17:09:59 +0000275# Try importing optional built-in module "strop" -- if it exists,
276# it redefines some string operations that are 100-1000 times faster.
Guido van Rossum8e2ec561993-07-29 09:37:38 +0000277# It also defines values for whitespace, lowercase and uppercase
278# that match <ctype.h>'s definitions.
Guido van Rossum2db91351992-10-18 17:09:59 +0000279
280try:
281 from strop import *
Guido van Rossum8e2ec561993-07-29 09:37:38 +0000282 letters = lowercase + uppercase
Guido van Rossumb6775db1994-08-01 11:34:53 +0000283except ImportError:
284 pass # Use the original, slow versions