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