1mNAME0m
       string - Manipulate strings

1mSYNOPSIS0m
       1mstring 4m22moption24m 4marg24m ?4marg24m 4m...?0m


1mDESCRIPTION0m
       Performs  one  of  several string operations, depending on 4moption24m.  The
       legal 4moption24ms (which may be abbreviated) are:

       1mstring bytelength 4m22mstring0m
              Returns a decimal string giving the number of bytes used to rep-
              resent  4mstring24m in memory.  Because UTF-8 uses one to three bytes
              to represent Unicode characters, the byte length will not be the
              same  as  the  character  length  in general.  The cases where a
              script cares about the byte length  are  rare.   In  almost  all
              cases, you should use the 1mstring length 22moperation.  Refer to the
              1mTcl_NumUtfChars 22mmanual entry for more details on the UTF-8  rep-
              resentation.

       1mstring compare 22m?1m-nocase22m? ?1m-length int22m? 4mstring124m 4mstring20m
              Perform  a  character-by-character comparison of strings 4mstring10m
              and 4mstring224m.  Returns -1, 0, or 1, depending on whether  4mstring10m
              is  lexicographically  less  than,  equal  to,  or  greater than
              4mstring224m.  If 1m-length 22mis specified, then only  the  first  4mlength0m
              characters  are used in the comparison.  If 1m-length 22mis negative,
              it is ignored.  If 1m-nocase 22mis specified, then  the  strings  are
              compared in a case-insensitive manner.

       1mstring equal 22m?1m-nocase22m? ?1m-length int22m? 4mstring124m 4mstring20m
              Perform  a  character-by-character comparison of strings 4mstring10m
              and 4mstring224m.  Returns 1 if 4mstring124m and 4mstring224m are identical, or
              0 when not.  If 1m-length 22mis specified, then only the first 4mlength0m
              characters are used in the comparison.  If 1m-length 22mis  negative,
              it  is  ignored.   If 1m-nocase 22mis specified, then the strings are
              compared in a case-insensitive manner.

       1mstring first 4m22mstring124m 4mstring224m ?4mstartIndex24m?
              Search 4mstring224m for a sequence of characters that  exactly  match
              the  characters  in  4mstring124m.  If found, return the index of the
              first character in the first such match within 4mstring224m.  If  not
              found,  return  -1.   If  4mstartIndex24m is specified (in any of the
              forms accepted by the 1mindex 22mmethod), then  the  search  is  con-
              strained to start with the character in 4mstring224m specified by the
              index.  For example,
                     1mstring first a 0a23456789abcdef 50m
              will return 1m1022m, but
                     1mstring first a 0123456789abcdef 110m
              will return 1m-122m.

       1mstring index 4m22mstring24m 4mcharIndex0m
              Returns the 4mcharIndex24m'th character of the  4mstring24m  argument.   A
              4mcharIndex24m of 0 corresponds to the first character of the string.
              4mcharIndex24m may be specified as follows:

              4minteger24m   The char specified at this integral index

              1mend       22mThe last char of the string.

              1mend-4m22minteger0m
                        The last char of the string minus the specified  inte-
                        ger  offset  (e.g.  1mend-1  22mwould  refer  to the "c" in
                        "abcd").

              If 4mcharIndex24m is less than 0 or greater  than  or  equal  to  the
              length of the string then an empty string is returned.

       1mstring is 4m22mclass24m ?1m-strict22m? ?1m-failindex 4m22mvarname24m? 4mstring0m
              Returns 1 if 4mstring24m is a valid member of the specified character
              class, otherwise returns 0.  If 1m-strict 22mis  specified,  then  an
              empty string returns 0, otherwise and empty string will return 1
              on any class.  If 1m-failindex 22mis specified, then if the  function
              returns 0, the index in the string where the class was no longer
              valid will be stored in the variable named 4mvarname24m.  The 4mvarname0m
              will  not be set if the function returns 1.  The following char-
              acter classes are recognized (the class  name  can  be  abbrevi-
              ated):

              1malnum     22mAny Unicode alphabet or digit character.

              1malpha     22mAny Unicode alphabet character.

              1mascii     22mAny  character  with  a  value less than \u0080 (those
                        that are in the 7-bit ascii range).

              1mboolean   22mAny of the forms allowed to 1mTcl_GetBoolean22m.

              1mcontrol   22mAny Unicode control character.

              1mdigit     22mAny Unicode digit character.  Note that this  includes
                        characters outside of the [0-9] range.

              1mdouble    22mAny  of  the  valid  forms  for  a double in Tcl, with
                        optional   surrounding   whitespace.    In   case   of
                        under/overflow  in  the  value,  0 is returned and the
                        4mvarname24m will contain -1.

              1mfalse     22mAny of the forms allowed to 1mTcl_GetBoolean  22mwhere  the
                        value is false.

              1mgraph     22mAny Unicode printing character, except space.

              1minteger   22mAny  of  the  valid  forms for an integer in Tcl, with
                        optional   surrounding   whitespace.    In   case   of
                        under/overflow  in  the  value,  0 is returned and the
                        4mvarname24m will contain -1.

              1mlower     22mAny Unicode lower case alphabet character.

              1mprint     22mAny Unicode printing character, including space.

              1mpunct     22mAny Unicode punctuation character.

              1mspace     22mAny Unicode space character.

              1mtrue      22mAny of the forms allowed to 1mTcl_GetBoolean  22mwhere  the
                        value is true.

              1mupper     22mAny upper case alphabet character in the Unicode char-
                        acter set.

              1mwordchar  22mAny Unicode word character.  That is any  alphanumeric
                        character, and any Unicode connector punctuation char-
                        acters (e.g. underscore).

              1mxdigit    22mAny hexadecimal digit character ([0-9A-Fa-f]).

              In the case of 1mboolean22m, 1mtrue 22mand 1mfalse22m,  if  the  function  will
              return  0,  then the 4mvarname24m will always be set to 0, due to the
              varied nature of a valid boolean value.

       1mstring last 4m22mstring124m 4mstring224m ?4mstartIndex24m?
              Search 4mstring224m for a sequence of characters that  exactly  match
              the  characters  in  4mstring124m.  If found, return the index of the
              first character in the last such match within 4mstring224m.  If there
              is no match, then return -1.  If 4mstartIndex24m is specified (in any
              of the forms accepted by the 1mindex 22mmethod), then only the  char-
              acters  in 4mstring224m at or before the specified 4mstartIndex24m will be
              considered by the search.  For example,
                     1mstring last a 0a23456789abcdef 150m
              will return 1m1022m, but
                     1mstring last a 0a23456789abcdef 90m
              will return 1m122m.

       1mstring length 4m22mstring0m
              Returns a decimal string giving  the  number  of  characters  in
              4mstring24m.   Note that this is not necessarily the same as the num-
              ber of bytes used to store the string.

       1mstring map 22m?1m-nocase22m? 4mcharMap24m 4mstring0m
              Replaces characters in 4mstring24m based on the  key-value  pairs  in
              4mcharMap24m.   4mcharMap24m  is  a list of 4mkey24m 4mvalue24m 4mkey24m 4mvalue24m ...  as in
              the form returned by 1marray get22m.  Each instance of a key  in  the
              string  will  be  replaced  with  its  corresponding  value.  If
              1m-nocase 22mis specified, then matching is done  without  regard  to
              case differences. Both 4mkey24m and 4mvalue24m may be multiple characters.
              Replacement is done in an ordered manner, so the  key  appearing
              first  in  the list will be checked first, and so on.  4mstring24m is
              only iterated over once, so earlier key replacements  will  have
              no affect for later key matches.  For example,
                     1mstring map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc0m
              will return the string 1m0132122122m.

       1mstring match 22m?1m-nocase22m? 4mpattern24m 4mstring0m
              See  if  4mpattern24m  matches  4mstring24m;  return 1 if it does, 0 if it
              doesn't.  If 1m-nocase 22mis specified, then the pattern attempts  to
              match  against the string in a case insensitive manner.  For the
              two strings to match, their contents must  be  identical  except
              that the following special sequences may appear in 4mpattern24m:

              1m*         22mMatches  any sequence of characters in 4mstring24m, includ-
                        ing a null string.

              1m?         22mMatches any single character in 4mstring24m.

              1m[4m22mchars24m1m]   22mMatches any character in the set given by 4mchars24m.  If a
                        sequence  of  the  form 4mx24m1m-4m22my24m appears in 4mchars24m, then any
                        character between 4mx24m  and  4my24m,  inclusive,  will  match.
                        When  used  with  1m-nocase22m, the end points of the range
                        are converted to lower case  first.   Whereas  {[A-z]}
                        matches  '_' when matching case-sensitively ('_' falls
                        between the 'Z' and 'a'), with 1m-nocase 22mthis is consid-
                        ered  like  {[A-Za-z]} (and probably what was meant in
                        the first place).

              1m\4m22mx24m        Matches the single character 4mx24m.  This provides  a  way
                        of  avoiding the special interpretation of the charac-
                        ters 1m*?[]\ 22min 4mpattern24m.

       1mstring range 4m22mstring24m 4mfirst24m 4mlast0m
              Returns a range of consecutive characters from 4mstring24m,  starting
              with  the  character  whose  index  is 4mfirst24m and ending with the
              character whose index is 4mlast24m. An index of 0 refers to the first
              character of the string.  4mfirst24m and 4mlast24m may be specified as for
              the 1mindex 22mmethod.  If 4mfirst24m is less than zero then it is treated
              as  if it were zero, and if 4mlast24m is greater than or equal to the
              length of the string then it is treated as if it were  1mend22m.   If
              4mfirst24m is greater than 4mlast24m then an empty string is returned.

       1mstring repeat 4m22mstring24m 4mcount0m
              Returns 4mstring24m repeated 4mcount24m number of times.

       1mstring replace 4m22mstring24m 4mfirst24m 4mlast24m ?4mnewstring24m?
              Removes  a range of consecutive characters from 4mstring24m, starting
              with the character whose index is  4mfirst24m  and  ending  with  the
              character  whose  index  is  4mlast24m.   An index of 0 refers to the
              first character of the string.  4mFirst24m and 4mlast24m may be  specified
              as  for the 1mindex 22mmethod.  If 4mnewstring24m is specified, then it is
              placed in the removed character range.  If 4mfirst24m  is  less  than
              zero  then  it  is  treated  as  if it were zero, and if 4mlast24m is
              greater than or equal to the length of the  string  then  it  is
              treated as if it were 1mend22m.  If 4mfirst24m is greater than 4mlast24m or the
              length of the initial string, or 4mlast24m is less than 0,  then  the
              initial string is returned untouched.

       1mstring tolower 4m22mstring24m ?4mfirst24m? ?4mlast24m?
              Returns a value equal to 4mstring24m except that all upper (or title)
              case letters have been converted to lower  case.   If  4mfirst24m  is
              specified,  it  refers  to the first char index in the string to
              start modifying.  If 4mlast24m is specified, it refers  to  the  char
              index  in the string to stop at (inclusive).  4mfirst24m and 4mlast24m may
              be specified as for the 1mindex 22mmethod.

       1mstring totitle 4m22mstring24m ?4mfirst24m? ?4mlast24m?
              Returns a value equal to 4mstring24m except that the first  character
              in  4mstring24m  is  converted  to its Unicode title case variant (or
              upper case if there is no title case variant) and  the  rest  of
              the  string  is converted to lower case.  If 4mfirst24m is specified,
              it refers to the first char index in the string to start modify-
              ing.   If  4mlast24m is specified, it refers to the char index in the
              string to stop at (inclusive).  4mfirst24m and 4mlast24m may be  specified
              as for the 1mindex 22mmethod.

       1mstring toupper 4m22mstring24m ?4mfirst24m? ?4mlast24m?
              Returns a value equal to 4mstring24m except that all lower (or title)
              case letters have been converted to upper  case.   If  4mfirst24m  is
              specified,  it  refers  to the first char index in the string to
              start modifying.  If 4mlast24m is specified, it refers  to  the  char
              index  in the string to stop at (inclusive).  4mfirst24m and 4mlast24m may
              be specified as for the 1mindex 22mmethod.

       1mstring trim 4m22mstring24m ?4mchars24m?
              Returns a value equal to  4mstring24m  except  that  any  leading  or
              trailing characters from the set given by 4mchars24m are removed.  If
              4mchars24m is not specified then  white  space  is  removed  (spaces,
              tabs, newlines, and carriage returns).

       1mstring trimleft 4m22mstring24m ?4mchars24m?
              Returns  a value equal to 4mstring24m except that any leading charac-
              ters from the set given by 4mchars24m are removed.  If 4mchars24m  is  not
              specified  then  white space is removed (spaces, tabs, newlines,
              and carriage returns).

       1mstring trimright 4m22mstring24m ?4mchars24m?
              Returns a value equal to 4mstring24m except that any trailing charac-
              ters  from  the set given by 4mchars24m are removed.  If 4mchars24m is not
              specified then white space is removed (spaces,  tabs,  newlines,
              and carriage returns).

       1mstring wordend 4m22mstring24m 4mcharIndex0m
              Returns  the  index  of the character just after the last one in
              the word containing character 4mcharIndex24m  of  4mstring24m.   4mcharIndex0m
              may  be specified as for the 1mindex 22mmethod.  A word is considered
              to be any contiguous range of alphanumeric (Unicode  letters  or
              decimal  digits)  or  underscore (Unicode connector punctuation)
              characters, or any single character other than these.

       1mstring wordstart 4m22mstring24m 4mcharIndex0m
              Returns the index of the first character in the word  containing
              character  4mcharIndex24m  of  4mstring24m.  4mcharIndex24m may be specified as
              for the 1mindex 22mmethod.  A word is considered to be any contiguous
              range  of  alphanumeric  (Unicode  letters or decimal digits) or
              underscore (Unicode connector punctuation)  characters,  or  any
              single character other than these.


1mSEE ALSO0m
       expr(n), list(n)


1mKEYWORDS0m
       case  conversion,  compare, index, match, pattern, string, word, equal,
