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 (including
              determining the length of a Tcl ByteArray object).  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  ordinary  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
                          character set.

              1mwordchar    22mAny  Unicode  word  character.  That is any alphanu-
                          meric character, and any Unicode connector  punctua-
                          tion characters (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 ?4mlastIndex24m?
              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 4mlastIndex24m is specified (in  any
              of  the forms accepted by the 1mindex 22mmethod), then only the char-
              acters in 4mstring224m at or before the specified 4mlastIndex24m  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.  If the object is a
              ByteArray object (such as those returned from reading  a  binary
              encoded  channel),  then this will return the actual byte length
              of the object.

       1mstring map 22m?1m-nocase22m? 4mmapping24m 4mstring0m
              Replaces substrings in 4mstring24m based on the  key-value  pairs  in
              4mmapping24m.   4mmapping24m  is  a list of 4mkey24m 4mvalue24m 4mkey24m 4mvalue24m 4m...24m  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.

              Note  that if an earlier 4mkey24m is a prefix of a later one, it will
              completely mask the later one.  So if the  previous  example  is
              reordered like this,
                     1mstring map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc0m
              it will return the string 1m02c322c222c22m.

       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.

1mEXAMPLE0m
       Test  if the string in the variable 4mstring24m is a proper non-empty prefix
       of the string 1mfoobar22m.
              set length [1mstring length 22m$string]
              if {$length == 0} {
                 set isPrefix 0
              } else {
                 set isPrefix [1mstring equal 22m-length $string $string "foobar"]
              }


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


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