string(3tcl)


NAME

   string - Manipulate strings

SYNOPSIS

   string option arg ?arg ...?
______________________________________________________________________________

DESCRIPTION

   Performs  one  of  several string operations, depending on option.  The
   legal options (which may be abbreviated) are:

   string compare ?-nocase? ?-length int? string1 string2
          Perform a character-by-character comparison of  strings  string1
          and  string2.  Returns -1, 0, or 1, depending on whether string1
          is lexicographically  less  than,  equal  to,  or  greater  than
          string2.   If  -length  is specified, then only the first length
          characters are used in the comparison.  If -length is  negative,
          it  is  ignored.   If -nocase is specified, then the strings are
          compared in a case-insensitive manner.

   string equal ?-nocase? ?-length int? string1 string2
          Perform a character-by-character comparison of  strings  string1
          and string2.  Returns 1 if string1 and string2 are identical, or
          0 when not.  If -length is specified, then only the first length
          characters  are used in the comparison.  If -length is negative,
          it is ignored.  If -nocase is specified, then  the  strings  are
          compared in a case-insensitive manner.

   string first needleString haystackString ?startIndex?
          Search  haystackString for a sequence of characters that exactly
          match the characters in  needleString.   If  found,  return  the
          index  of  the  first  character  in the first such match within
          haystackString.  If not found,  return  -1.   If  startIndex  is
          specified  (in  any  of the forms accepted by the index method),
          then the search is constrained to start with  the  character  in
          haystackString specified by the index.  For example,
                 string first a 0a23456789abcdef 5
          will return 10, but
                 string first a 0123456789abcdef 11
          will return -1.

   string index string charIndex
          Returns  the  charIndex'th  character of the string argument.  A
          charIndex of 0 corresponds to the first character of the string.
          charIndex may be specified as follows:                           

          integer                                                          
                    For  any  index  value  that  passes string is integer 
                    -strict, the char specified  at  this  integral  index 
                    (e.g. 2 would refer to the "c" in "abcd").             

          end                                                              
                    The  last  char of the string (e.g. end would refer to 
                    the "d" in "abcd").                                    

          end-N                                                            
                    The last  char  of  the  string  minus  the  specified 
                    integer offset N (e.g. end-1 would refer to the "c" in 
                    "abcd").                                               

          end+N                                                            
                    The last char of the string plus the specified integer 
                    offset  N  (e.g.  end+-1  would  refer  to  the "c" in 
                    "abcd").                                               

          M+N                                                              
                    The char specified at the integral index that  is  the 
                    sum of integer values M and N (e.g. 1+1 would refer to 
                    the "c" in "abcd").                                    

          M-N                                                              
                    The char specified at the integral index that  is  the 
                    difference  of  integer values M and N (e.g. 2-1 would 
                    refer to the "b" in "abcd").                           

          In the specifications above, the integer  value  M  contains  no 
          trailing  whitespace and the integer value N contains no leading 
          whitespace.                                                      

          If charIndex is less than 0 or greater  than  or  equal  to  the 
          length of the string then this command returns an empty string.  

   string is class ?-strict? ?-failindex varname? string
          Returns 1 if string is a valid member of the specified character
          class, otherwise returns 0.  If -strict is  specified,  then  an
          empty  string returns 0, otherwise an empty string will return 1
          on any class.  If -failindex is 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 varname.  The varname
          will not be set if string is returns 1.  The following character
          classes are recognized (the class name can be abbreviated):

          alnum       Any Unicode alphabet or digit character.

          alpha       Any Unicode alphabet character.

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

          boolean     Any of the forms allowed to Tcl_GetBoolean.

          control     Any Unicode control character.

          digit       Any   Unicode   digit  character.   Note  that  this
                      includes characters outside of the [0-9] range.

          double      Any 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
                      varname will contain -1.

          false       Any of the forms allowed to Tcl_GetBoolean where the
                      value is false.

          graph       Any Unicode printing character, except space.

          integer     Any of the valid string formats for a 32-bit integer
                      value  in Tcl, with optional surrounding whitespace.
                      In  case  of  under/overflow  in  the  value,  0  is
                      returned and the varname will contain -1.

          list        Any proper list structure, with optional surrounding
                      whitespace. In case of improper list structure, 0 is
                      returned  and  the varname will contain the index of
                      the "element" where the list parsing fails, or -1 if
                      this cannot be determined.

          lower       Any Unicode lower case alphabet character.

          print       Any Unicode printing character, including space.

          punct       Any Unicode punctuation character.

          space       Any  Unicode whitespace character or mongolian vowel
                      separator (U+180e), but not NEL/Next Line (U+0085).

          true        Any of the forms allowed to Tcl_GetBoolean where the
                      value is true.

          upper       Any  upper  case  alphabet  character in the Unicode
                      character set.                                       

          wideinteger                                                      
                      Any of the valid forms for a wide  integer  in  Tcl, 
                      with  optional  surrounding  whitespace.  In case of 
                      under/overflow in the value, 0 is returned  and  the 
                      varname will contain -1.

          wordchar    Any   Unicode   word   character.    That   is   any
                      alphanumeric character, and  any  Unicode  connector
                      punctuation characters (e.g. underscore).

          xdigit      Any hexadecimal digit character ([0-9A-Fa-f]).

          In  the  case  of  boolean, true and false, if the function will
          return 0, then the varname will always be set to 0, due  to  the
          varied nature of a valid boolean value.

   string last needleString haystackString ?lastIndex?
          Search  haystackString for a sequence of characters that exactly
          match the characters in  needleString.   If  found,  return  the
          index  of  the  first  character  in  the last such match within
          haystackString.  If there is  no  match,  then  return  -1.   If
          lastIndex  is  specified  (in  any  of the forms accepted by the
          index method), then only the characters in haystackString at  or
          before the specified lastIndex will be considered by the search.
          For example,
                 string last a 0a23456789abcdef 15
          will return 10, but
                 string last a 0a23456789abcdef 9
          will return 1.

   string length string
          Returns a decimal string giving  the  number  of  characters  in
          string.   Note  that  this  is  not  necessarily the same as the
          number 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.

   string map ?-nocase? mapping string
          Replaces  substrings  in  string based on the key-value pairs in
          mapping.  mapping is a list of key value key value  ...   as  in
          the  form  returned by array get.  Each instance of a key in the
          string will  be  replaced  with  its  corresponding  value.   If
          -nocase  is  specified,  then matching is done without regard to
          case differences. Both key and value 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.   string  is
          only  iterated  over once, so earlier key replacements will have
          no affect for later key matches.  For example,
                 string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc
          will return the string 01321221.

          Note that if an earlier key is a prefix of a later one, it  will
          completely  mask  the  later one.  So if the previous example is
          reordered like this,
                 string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc
          it will return the string 02c322c222c.

   string match ?-nocase? pattern string
          See if pattern matches string; return 1 if it does, 0 if it does
          not.   If  -nocase  is  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 pattern:

          *         Matches  any  sequence  of   characters   in   string,
                    including a null string.

          ?         Matches any single character in string.

          [chars]   Matches any character in the set given by chars.  If a
                    sequence of the form x-y appears in  chars,  then  any
                    character  between  x  and  y,  inclusive, will match.
                    When used with -nocase, the end points  of  the  range
                    are  converted  to  lower case first.  Whereas {[A-z]}
                    matches "_" when matching case-sensitively (since  "_"
                    falls  between  the "Z" and "a"), with -nocase this is
                    considered like  {[A-Za-z]}  (and  probably  what  was
                    meant in the first place).

          \x        Matches  the  single character x.  This provides a way
                    of  avoiding  the  special   interpretation   of   the
                    characters *?[]\ in pattern.

   string range string first last
          Returns  a range of consecutive characters from string, starting
          with the character whose index is  first  and  ending  with  the
          character whose index is last. An index of 0 refers to the first
          character of the string.  first and last may be specified as for
          the index method.  If first is less than zero then it is treated
          as if it were zero, and if last is greater than or equal to  the
          length  of  the string then it is treated as if it were end.  If
          first is greater than last then an empty string is returned.

   string repeat string count
          Returns string repeated count number of times.

   string replace string first last ?newstring?
          Removes a range of consecutive characters from string,  starting
          with  the  character  whose  index  is first and ending with the
          character whose index is last.  An index  of  0  refers  to  the
          first  character of the string.  First and last may be specified
          as for the index method.  If newstring is specified, then it  is
          placed  in  the  removed character range.  If first is less than
          zero then it is treated as if it  were  zero,  and  if  last  is
          greater  than  or  equal  to the length of the string then it is
          treated as if it were end.  If first is greater than last or the
          length  of  the initial string, or last is less than 0, then the
          initial string is returned untouched.                            

   string reverse string                                                   
          Returns a string that is the same length as string but with  its 
          characters in the reverse order.

   string tolower string ?first? ?last?
          Returns a value equal to string except that all upper (or title)
          case letters have been converted to lower  case.   If  first  is
          specified,  it  refers  to the first char index in the string to
          start modifying.  If last is specified, it refers  to  the  char
          index  in the string to stop at (inclusive).  first and last may
          be specified as for the index method.

   string totitle string ?first? ?last?
          Returns a value equal to string except that the first  character
          in  string  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 first is specified,
          it refers to the  first  char  index  in  the  string  to  start
          modifying.  If last is specified, it refers to the char index in
          the string to stop  at  (inclusive).   first  and  last  may  be
          specified as for the index method.

   string toupper string ?first? ?last?
          Returns a value equal to string except that all lower (or title)
          case letters have been converted to upper  case.   If  first  is
          specified,  it  refers  to the first char index in the string to
          start modifying.  If last is specified, it refers  to  the  char
          index  in the string to stop at (inclusive).  first and last may
          be specified as for the index method.

   string trim string ?chars?
          Returns a value equal to  string  except  that  any  leading  or
          trailing  characters  present  in  the string given by chars are
          removed.  If chars is not specified then white space is  removed
          (spaces, tabs, newlines, and carriage returns).

   string trimleft string ?chars?
          Returns  a  value  equal  to  string  except  that  any  leading
          characters present in the string given by chars are removed.  If
          chars  is  not  specified  then  white space is removed (spaces,
          tabs, newlines, and carriage returns).

   string trimright string ?chars?
          Returns a  value  equal  to  string  except  that  any  trailing
          characters present in the string given by chars are removed.  If
          chars is not specified then  white  space  is  removed  (spaces,
          tabs, newlines, and carriage returns).

OBSOLETE SUBCOMMANDS

   These subcommands are currently supported, but are likely to go away in
   a future release as their functionality is either virtually never  used
   or highly misleading.

   string bytelength string
          Returns  a  decimal  string  giving  the number of bytes used to
          represent string 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  string  length  operation  (including
          determining the length of a Tcl ByteArray object).  Refer to the
          Tcl_NumUtfChars manual entry  for  more  details  on  the  UTF-8
          representation.

   string wordend string charIndex
          Returns  the  index  of the character just after the last one in
          the word containing character charIndex  of  string.   charIndex
          may  be specified as for the index method.  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.

   string wordstart string charIndex
          Returns the index of the first character in the word  containing
          character  charIndex  of  string.  charIndex may be specified as
          for the index method.  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.

EXAMPLE

   Test  if the string in the variable string is a proper non-empty prefix
   of the string foobar.
          set length [string length $string]
          if {$length == 0} {
              set isPrefix 0
          } else {
              set isPrefix [string equal -length $length $string "foobar"]
          }

SEE ALSO

   expr(3tcl), list(3tcl)

KEYWORDS

   case conversion, compare, index, match, pattern, string,  word,  equal,
   ctype, character, reverse





Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.





Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.


Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.





Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.


Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.





Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.


Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.