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 

    22 # Some strings for ctype-style character classification

    23 whitespace = ' \t\n\r\v\f'

    24 lowercase = 'abcdefghijklmnopqrstuvwxyz'

    25 uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'

    26 letters = lowercase + uppercase

    27 digits = '0123456789'

    28 hexdigits = digits + 'abcdef' + 'ABCDEF'

    29 octdigits = '01234567'

    30 

    31 # Case conversion helpers

    32 _idmap = ''

    33 for i in range(256): _idmap = _idmap + chr(i)

    34 del i

    35 

    36 # Backward compatible names for exceptions

    37 index_error = ValueError

    38 atoi_error = ValueError

    39 atof_error = ValueError

    40 atol_error = ValueError

    41 

    42 # convert UPPER CASE letters to lower case

    43 def lower(s):

    44     """lower(s) -> string

    45 

    46     Return a copy of the string s converted to lowercase.

    47 

    48     """

    49     return s.lower()

    50 

    51 # Convert lower case letters to UPPER CASE

    52 def upper(s):

    53     """upper(s) -> string

    54 

    55     Return a copy of the string s converted to uppercase.

    56 

    57     """

    58     return s.upper()

    59 

    60 # Swap lower case letters and UPPER CASE

    61 def swapcase(s):

    62     """swapcase(s) -> string

    63 

    64     Return a copy of the string s with upper case characters

    65     converted to lowercase and vice versa.

    66 

    67     """

    68     return s.swapcase()

    69 

    70 # Strip leading and trailing tabs and spaces

    71 def strip(s):

    72     """strip(s) -> string

    73 

    74     Return a copy of the string s with leading and trailing

    75     whitespace removed.

    76 

    77     """

    78     return s.strip()

    79 

    80 # Strip leading tabs and spaces

    81 def lstrip(s):

    82     """lstrip(s) -> string

    83 

    84     Return a copy of the string s with leading whitespace removed.

    85 

    86     """

    87     return s.lstrip()

    88 

    89 # Strip trailing tabs and spaces

    90 def rstrip(s):

    91     """rstrip(s) -> string

    92 

    93     Return a copy of the string s with trailing whitespace

    94     removed.

    95 

    96     """

    97     return s.rstrip()

    98 

    99 

   100 # Split a string into a list of space/tab-separated words

   101 def split(s, sep=None, maxsplit=0):

   102     """split(str [,sep [,maxsplit]]) -> list of strings

   103 

   104     Return a list of the words in the string s, using sep as the

   105     delimiter string.  If maxsplit is nonzero, splits into at most

   106     maxsplit words If sep is not specified, any whitespace string

   107     is a separator.  Maxsplit defaults to 0.

   108 

   109     (split and splitfields are synonymous)

   110 

   111     """

   112     return s.split(sep, maxsplit)

   113 splitfields = split

   114 

   115 # Join fields with optional separator

   116 def join(words, sep = ' '):

   117     """join(list [,sep]) -> string

   118 

   119     Return a string composed of the words in list, with

   120     intervening occurrences of sep.  The default separator is a

   121     single space.

   122 

   123     (joinfields and join are synonymous)

   124 

   125     """

   126     return sep.join(words)

   127 joinfields = join

   128 

   129 # for a little bit of speed

   130 _apply = apply

   131 

   132 # Find substring, raise exception if not found

   133 def index(s, *args):

   134     """index(s, sub [,start [,end]]) -> int

   135 

   136     Like find but raises ValueError when the substring is not found.

   137 

   138     """

   139     return _apply(s.index, args)

   140 

   141 # Find last substring, raise exception if not found

   142 def rindex(s, *args):

   143     """rindex(s, sub [,start [,end]]) -> int

   144 

   145     Like rfind but raises ValueError when the substring is not found.

   146 

   147     """

   148     return _apply(s.rindex, args)

   149 

   150 # Count non-overlapping occurrences of substring

   151 def count(s, *args):

   152     """count(s, sub[, start[,end]]) -> int

   153 

   154     Return the number of occurrences of substring sub in string

   155     s[start:end].  Optional arguments start and end are

   156     interpreted as in slice notation.

   157 

   158     """

   159     return _apply(s.count, args)

   160 

   161 # Find substring, return -1 if not found

   162 def find(s, *args):

   163     """find(s, sub [,start [,end]]) -> in

   164 

   165     Return the lowest index in s where substring sub is found,

   166     such that sub is contained within s[start,end].  Optional

   167     arguments start and end are interpreted as in slice notation.

   168 

   169     Return -1 on failure.

   170 

   171     """

   172     return _apply(s.find, args)

   173 

   174 # Find last substring, return -1 if not found

   175 def rfind(s, *args):

   176     """rfind(s, sub [,start [,end]]) -> int

   177 

   178     Return the highest index in s where substring sub is found,

   179     such that sub is contained within s[start,end].  Optional

   180     arguments start and end are interpreted as in slice notation.

   181 

   182     Return -1 on failure.

   183 

   184     """

   185     return _apply(s.rfind, args)

   186 

   187 # for a bit of speed

   188 _float = float

   189 _int = int

   190 _long = long

   191 _StringType = type('')

   192 

   193 # Convert string to float

   194 def atof(s):

   195     """atof(s) -> float

   196 

   197     Return the floating point number represented by the string s.

   198 

   199     """

   200     if type(s) == _StringType:

   201         return _float(s)

   202     else:

   203         raise TypeError('argument 1: expected string, %s found' %

   204                         type(s).__name__)

   205 

   206 # Convert string to integer

   207 def atoi(*args):

   208     """atoi(s [,base]) -> int

   209 

   210     Return the integer represented by the string s in the given

   211     base, which defaults to 10.  The string s must consist of one

   212     or more digits, possibly preceded by a sign.  If base is 0, it

   213     is chosen from the leading characters of s, 0 for octal, 0x or

   214     0X for hexadecimal.  If base is 16, a preceding 0x or 0X is

   215     accepted.

   216 

   217     """

   218     try:

   219         s = args[0]

   220     except IndexError:

   221         raise TypeError('function requires at least 1 argument: %d given' %

   222                         len(args))

   223     # Don't catch type error resulting from too many arguments to int().  The

   224     # error message isn't compatible but the error type is, and this function

   225     # is complicated enough already.

   226     if type(s) == _StringType:

   227         return _apply(_int, args)

   228     else:

   229         raise TypeError('argument 1: expected string, %s found' %

   230                         type(s).__name__)

   231 

   232 

   233 # Convert string to long integer

   234 def atol(*args):

   235     """atol(s [,base]) -> long

   236 

   237     Return the long integer represented by the string s in the

   238     given base, which defaults to 10.  The string s must consist

   239     of one or more digits, possibly preceded by a sign.  If base

   240     is 0, it is chosen from the leading characters of s, 0 for

   241     octal, 0x or 0X for hexadecimal.  If base is 16, a preceding

   242     0x or 0X is accepted.  A trailing L or l is not accepted,

   243     unless base is 0.

   244 

   245     """

   246     try:

   247         s = args[0]

   248     except IndexError:

   249         raise TypeError('function requires at least 1 argument: %d given' %

   250                         len(args))

   251     # Don't catch type error resulting from too many arguments to long().  The

   252     # error message isn't compatible but the error type is, and this function

   253     # is complicated enough already.

   254     if type(s) == _StringType:

   255         return _apply(_long, args)

   256     else:

   257         raise TypeError('argument 1: expected string, %s found' %

   258                         type(s).__name__)

   259 

   260 

   261 # Left-justify a string

   262 def ljust(s, width):

   263     """ljust(s, width) -> string

   264 

   265     Return a left-justified version of s, in a field of the

   266     specified width, padded with spaces as needed.  The string is

   267     never truncated.

   268 

   269     """

   270     n = width - len(s)

   271     if n <= 0: return s

   272     return s + ' '*n

   273 

   274 # Right-justify a string

   275 def rjust(s, width):

   276     """rjust(s, width) -> string

   277 

   278     Return a right-justified version of s, in a field of the

   279     specified width, padded with spaces as needed.  The string is

   280     never truncated.

   281 

   282     """

   283     n = width - len(s)

   284     if n <= 0: return s

   285     return ' '*n + s

   286 

   287 # Center a string

   288 def center(s, width):

   289     """center(s, width) -> string

   290 

   291     Return a center version of s, in a field of the specified

   292     width. padded with spaces as needed.  The string is never

   293     truncated.

   294 

   295     """

   296     n = width - len(s)

   297     if n <= 0: return s

   298     half = n/2

   299     if n%2 and width%2:

   300         # This ensures that center(center(s, i), j) = center(s, j)

   301         half = half+1

   302     return ' '*half +  s + ' '*(n-half)

   303 

   304 # Zero-fill a number, e.g., (12, 3) --> '012' and (-3, 3) --> '-03'

   305 # Decadent feature: the argument may be a string or a number

   306 # (Use of this is deprecated; it should be a string as with ljust c.s.)

   307 def zfill(x, width):

   308     """zfill(x, width) -> string

   309 

   310     Pad a numeric string x with zeros on the left, to fill a field

   311     of the specified width.  The string x is never truncated.

   312 

   313     """

   314     if type(x) == type(''): s = x

   315     else: s = repr(x)

   316     n = len(s)

   317     if n >= width: return s

   318     sign = ''

   319     if s[0] in ('-', '+'):

   320         sign, s = s[0], s[1:]

   321     return sign + '0'*(width-n) + s

   322 

   323 # Expand tabs in a string.

   324 # Doesn't take non-printing chars into account, but does understand \n.

   325 def expandtabs(s, tabsize=8):

   326     """expandtabs(s [,tabsize]) -> string

   327 

   328     Return a copy of the string s with all tab characters replaced

   329     by the appropriate number of spaces, depending on the current

   330     column, and the tabsize (default 8).

   331 

   332     """

   333     res = line = ''

   334     for c in s:

   335         if c == '\t':

   336             c = ' '*(tabsize - len(line) % tabsize)

   337         line = line + c

   338         if c == '\n':

   339             res = res + line

   340             line = ''

   341     return res + line

   342 

   343 # Character translation through look-up table.

   344 def translate(s, table, deletions=""):

   345     """translate(s,table [,deletechars]) -> string

   346 

   347     Return a copy of the string s, where all characters occurring

   348     in the optional argument deletechars are removed, and the

   349     remaining characters have been mapped through the given

   350     translation table, which must be a string of length 256.

   351 

   352     """

   353     return s.translate(table, deletions)

   354 

   355 # Capitalize a string, e.g. "aBc  dEf" -> "Abc  def".

   356 def capitalize(s):

   357     """capitalize(s) -> string

   358 

   359     Return a copy of the string s with only its first character

   360     capitalized.

   361 

   362     """

   363     return s.capitalize()

   364 

   365 # Capitalize the words in a string, e.g. " aBc  dEf " -> "Abc Def".

   366 def capwords(s, sep=None):

   367     """capwords(s, [sep]) -> string

   368 

   369     Split the argument into words using split, capitalize each

   370     word using capitalize, and join the capitalized words using

   371     join. Note that this replaces runs of whitespace characters by

   372     a single space.

   373 

   374     """

   375     return join(map(capitalize, s.split(sep)), sep or ' ')

   376 

   377 # Construct a translation string

   378 _idmapL = None

   379 def maketrans(fromstr, tostr):

   380     """maketrans(frm, to) -> string

   381 

   382     Return a translation table (a string of 256 bytes long)

   383     suitable for use in string.translate.  The strings frm and to

   384     must be of the same length.

   385 

   386     """

   387     if len(fromstr) != len(tostr):

   388         raise ValueError, "maketrans arguments must have same length"

   389     global _idmapL

   390     if not _idmapL:

   391         _idmapL = map(None, _idmap)

   392     L = _idmapL[:]

   393     fromstr = map(ord, fromstr)

   394     for i in range(len(fromstr)):

   395         L[fromstr[i]] = tostr[i]

   396     return join(L, "")

   397 

   398 # Substring replacement (global)

   399 def replace(s, old, new, maxsplit=0):

   400     """replace (str, old, new[, maxsplit]) -> string

   401 

   402     Return a copy of string str with all occurrences of substring

   403     old replaced by new. If the optional argument maxsplit is

   404     given, only the first maxsplit occurrences are replaced.

   405 

   406     """

   407     return s.replace(old, new, maxsplit)

   408 

   409 

   410 # XXX: transitional

   411 #

   412 # If string objects do not have methods, then we need to use the old string.py

   413 # library, which uses strop for many more things than just the few outlined

   414 # below.

   415 try:

   416     ''.upper

   417 except AttributeError:

   418     from stringold import *

   419 

   420 # Try importing optional built-in module "strop" -- if it exists,

   421 # it redefines some string operations that are 100-1000 times faster.

   422 # It also defines values for whitespace, lowercase and uppercase

   423 # that match <ctype.h>'s definitions.

   424 

   425 try:

   426     from strop import maketrans, lowercase, uppercase, whitespace

   427     letters = lowercase + uppercase

   428 except ImportError:

   429     pass                                          # Use the original versions