Lib/stringold.py

   1 # module 'string' -- A collection of string operations
   2
   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.
   7
   8 """Common string manipulations.
   9
  10 Public module variables:
  11
  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
  19
  20 """
  21 from warnings import warnpy3k
  22 warnpy3k("the stringold module has been removed in Python 3.0", stacklevel=2)
  23 del warnpy3k
  24
  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
  30 digits = '0123456789'
  31 hexdigits = digits + 'abcdef' + 'ABCDEF'
  32 octdigits = '01234567'
  33
  34 # Case conversion helpers
  35 _idmap = ''
  36 for i in range(256): _idmap = _idmap + chr(i)
  37 del i
  38
  39 # Backward compatible names for exceptions
  40 index_error = ValueError
  41 atoi_error = ValueError
  42 atof_error = ValueError
  43 atol_error = ValueError
  44
  45 # convert UPPER CASE letters to lower case
  46 def lower(s):
  47     """lower(s) -> string
  48
  49     Return a copy of the string s converted to lowercase.
  50
  51     """
  52     return s.lower()
  53
  54 # Convert lower case letters to UPPER CASE
  55 def upper(s):
  56     """upper(s) -> string
  57
  58     Return a copy of the string s converted to uppercase.
  59
  60     """
  61     return s.upper()
  62
  63 # Swap lower case letters and UPPER CASE
  64 def swapcase(s):
  65     """swapcase(s) -> string
  66
  67     Return a copy of the string s with upper case characters
  68     converted to lowercase and vice versa.
  69
  70     """
  71     return s.swapcase()
  72
  73 # Strip leading and trailing tabs and spaces
  74 def strip(s):
  75     """strip(s) -> string
  76
  77     Return a copy of the string s with leading and trailing
  78     whitespace removed.
  79
  80     """
  81     return s.strip()
  82
  83 # Strip leading tabs and spaces
  84 def lstrip(s):
  85     """lstrip(s) -> string
  86
  87     Return a copy of the string s with leading whitespace removed.
  88
  89     """
  90     return s.lstrip()
  91
  92 # Strip trailing tabs and spaces
  93 def rstrip(s):
  94     """rstrip(s) -> string
  95
  96     Return a copy of the string s with trailing whitespace
  97     removed.
  98
  99     """
 100     return s.rstrip()
 101
 102
 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
 106
 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.
 111
 112     (split and splitfields are synonymous)
 113
 114     """
 115     return s.split(sep, maxsplit)
 116 splitfields = split
 117
 118 # Join fields with optional separator
 119 def join(words, sep = ' '):
 120     """join(list [,sep]) -> string
 121
 122     Return a string composed of the words in list, with
 123     intervening occurrences of sep.  The default separator is a
 124     single space.
 125
 126     (joinfields and join are synonymous)
 127
 128     """
 129     return sep.join(words)
 130 joinfields = join
 131
 132 # for a little bit of speed
 133 _apply = apply
 134
 135 # Find substring, raise exception if not found
 136 def index(s, *args):
 137     """index(s, sub [,start [,end]]) -> int
 138
 139     Like find but raises ValueError when the substring is not found.
 140
 141     """
 142     return _apply(s.index, args)
 143
 144 # Find last substring, raise exception if not found
 145 def rindex(s, *args):
 146     """rindex(s, sub [,start [,end]]) -> int
 147
 148     Like rfind but raises ValueError when the substring is not found.
 149
 150     """
 151     return _apply(s.rindex, args)
 152
 153 # Count non-overlapping occurrences of substring
 154 def count(s, *args):
 155     """count(s, sub[, start[,end]]) -> int
 156
 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.
 160
 161     """
 162     return _apply(s.count, args)
 163
 164 # Find substring, return -1 if not found
 165 def find(s, *args):
 166     """find(s, sub [,start [,end]]) -> in
 167
 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.
 171
 172     Return -1 on failure.
 173
 174     """
 175     return _apply(s.find, args)
 176
 177 # Find last substring, return -1 if not found
 178 def rfind(s, *args):
 179     """rfind(s, sub [,start [,end]]) -> int
 180
 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.
 184
 185     Return -1 on failure.
 186
 187     """
 188     return _apply(s.rfind, args)
 189
 190 # for a bit of speed
 191 _float = float
 192 _int = int
 193 _long = long
 194 _StringType = type('')
 195
 196 # Convert string to float
 197 def atof(s):
 198     """atof(s) -> float
 199
 200     Return the floating point number represented by the string s.
 201
 202     """
 203     if type(s) == _StringType:
 204         return _float(s)
 205     else:
 206         raise TypeError('argument 1: expected string, %s found' %
 207                         type(s).__name__)
 208
 209 # Convert string to integer
 210 def atoi(*args):
 211     """atoi(s [,base]) -> int
 212
 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
 218     accepted.
 219
 220     """
 221     try:
 222         s = args[0]
 223     except IndexError:
 224         raise TypeError('function requires at least 1 argument: %d given' %
 225                         len(args))
 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)
 231     else:
 232         raise TypeError('argument 1: expected string, %s found' %
 233                         type(s).__name__)
 234
 235
 236 # Convert string to long integer
 237 def atol(*args):
 238     """atol(s [,base]) -> long
 239
 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,
 246     unless base is 0.
 247
 248     """
 249     try:
 250         s = args[0]
 251     except IndexError:
 252         raise TypeError('function requires at least 1 argument: %d given' %
 253                         len(args))
 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)
 259     else:
 260         raise TypeError('argument 1: expected string, %s found' %
 261                         type(s).__name__)
 262
 263
 264 # Left-justify a string
 265 def ljust(s, width):
 266     """ljust(s, width) -> string
 267
 268     Return a left-justified version of s, in a field of the
 269     specified width, padded with spaces as needed.  The string is
 270     never truncated.
 271
 272     """
 273     n = width - len(s)
 274     if n <= 0: return s
 275     return s + ' '*n
 276
 277 # Right-justify a string
 278 def rjust(s, width):
 279     """rjust(s, width) -> string
 280
 281     Return a right-justified version of s, in a field of the
 282     specified width, padded with spaces as needed.  The string is
 283     never truncated.
 284
 285     """
 286     n = width - len(s)
 287     if n <= 0: return s
 288     return ' '*n + s
 289
 290 # Center a string
 291 def center(s, width):
 292     """center(s, width) -> string
 293
 294     Return a center version of s, in a field of the specified
 295     width. padded with spaces as needed.  The string is never
 296     truncated.
 297
 298     """
 299     n = width - len(s)
 300     if n <= 0: return s
 301     half = n/2
 302     if n%2 and width%2:
 303         # This ensures that center(center(s, i), j) = center(s, j)
 304         half = half+1
 305     return ' '*half +  s + ' '*(n-half)
 306
 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.)
 310 def zfill(x, width):
 311     """zfill(x, width) -> string
 312
 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.
 315
 316     """
 317     if type(x) == type(''): s = x
 318     else: s = repr(x)
 319     n = len(s)
 320     if n >= width: return s
 321     sign = ''
 322     if s[0] in ('-', '+'):
 323         sign, s = s[0], s[1:]
 324     return sign + '0'*(width-n) + s
 325
 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
 330
 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).
 334
 335     """
 336     res = line = ''
 337     for c in s:
 338         if c == '\t':
 339             c = ' '*(tabsize - len(line) % tabsize)
 340         line = line + c
 341         if c == '\n':
 342             res = res + line
 343             line = ''
 344     return res + line
 345
 346 # Character translation through look-up table.
 347 def translate(s, table, deletions=""):
 348     """translate(s,table [,deletechars]) -> string
 349
 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.
 354
 355     """
 356     return s.translate(table, deletions)
 357
 358 # Capitalize a string, e.g. "aBc  dEf" -> "Abc  def".
 359 def capitalize(s):
 360     """capitalize(s) -> string
 361
 362     Return a copy of the string s with only its first character
 363     capitalized.
 364
 365     """
 366     return s.capitalize()
 367
 368 # Capitalize the words in a string, e.g. " aBc  dEf " -> "Abc Def".
 369 def capwords(s, sep=None):
 370     """capwords(s, [sep]) -> string
 371
 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
 375     a single space.
 376
 377     """
 378     return join(map(capitalize, s.split(sep)), sep or ' ')
 379
 380 # Construct a translation string
 381 _idmapL = None
 382 def maketrans(fromstr, tostr):
 383     """maketrans(frm, to) -> string
 384
 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.
 388
 389     """
 390     if len(fromstr) != len(tostr):
 391         raise ValueError, "maketrans arguments must have same length"
 392     global _idmapL
 393     if not _idmapL:
 394         _idmapL = list(_idmap)
 395     L = _idmapL[:]
 396     fromstr = map(ord, fromstr)
 397     for i in range(len(fromstr)):
 398         L[fromstr[i]] = tostr[i]
 399     return join(L, "")
 400
 401 # Substring replacement (global)
 402 def replace(s, old, new, maxsplit=0):
 403     """replace (str, old, new[, maxsplit]) -> string
 404
 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.
 408
 409     """
 410     return s.replace(old, new, maxsplit)
 411
 412
 413 # XXX: transitional
 414 #
 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
 417 # below.
 418 try:
 419     ''.upper
 420 except AttributeError:
 421     from stringold import *
 422
 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.
 427
 428 try:
 429     from strop import maketrans, lowercase, uppercase, whitespace
 430     letters = lowercase + uppercase
 431 except ImportError:
 432     pass                                          # Use the original versions