home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tcl7.0b1 / doc / string.n < prev    next >
Encoding:
Text File  |  1993-06-16  |  5.4 KB  |  132 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/string.n,v 1.1 93/06/16 16:48:24 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS string tcl
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. string \- Manipulate strings
  29. .SH SYNOPSIS
  30. \fBstring \fIoption arg \fR?\fIarg ...?\fR
  31. .BE
  32.  
  33. .SH DESCRIPTION
  34. .PP
  35. Performs one of several string operations, depending on \fIoption\fR.
  36. The legal \fIoption\fRs (which may be abbreviated) are:
  37. .TP
  38. \fBstring compare \fIstring1 string2\fR
  39. Perform a character-by-character comparison of strings \fIstring1\fR and
  40. \fIstring2\fR in the same way as the C \fBstrcmp\fR procedure.  Return
  41. \-1, 0, or 1, depending on whether \fIstring1\fR is lexicographically
  42. less than, equal to, or greater than \fIstring2\fR.
  43. .TP
  44. \fBstring first \fIstring1 string2\fR
  45. Search \fIstring2\fR for a sequence of characters that exactly match
  46. the characters in \fIstring1\fR.  If found, return the index of the
  47. first character in the first such match within \fIstring2\fR.  If not
  48. found, return \-1.
  49. .TP
  50. \fBstring index \fIstring charIndex\fR
  51. Returns the \fIcharIndex\fR'th character of the \fIstring\fR
  52. argument.  A \fIcharIndex\fR of 0 corresponds to the first
  53. character of the string.
  54. If \fIcharIndex\fR is less than 0 or greater than
  55. or equal to the length of the string then an empty string is
  56. returned.
  57. .TP
  58. \fBstring last \fIstring1 string2\fR
  59. Search \fIstring2\fR for a sequence of characters that exactly match
  60. the characters in \fIstring1\fR.  If found, return the index of the
  61. first character in the last such match within \fIstring2\fR.  If there
  62. is no match, then return \-1.
  63. .TP
  64. \fBstring length \fIstring\fR
  65. Returns a decimal string giving the number of characters in \fIstring\fR.
  66. .TP
  67. \fBstring match \fIpattern\fR \fIstring\fR
  68. See if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0
  69. if it doesn't.  Matching is done in a fashion similar to that
  70. used by the C-shell.  For the two strings to match, their contents
  71. must be identical except that the following special sequences
  72. may appear in \fIpattern\fR:
  73. .RS
  74. .IP \fB*\fR 10
  75. Matches any sequence of characters in \fIstring\fR,
  76. including a null string.
  77. .IP \fB?\fR 10
  78. Matches any single character in \fIstring\fR.
  79. .IP \fB[\fIchars\fB]\fR 10
  80. Matches any character in the set given by \fIchars\fR.  If a sequence
  81. of the form
  82. \fIx\fB\-\fIy\fR appears in \fIchars\fR, then any character
  83. between \fIx\fR and \fIy\fR, inclusive, will match.
  84. .IP \fB\e\fIx\fR 10
  85. Matches the single character \fIx\fR.  This provides a way of
  86. avoiding the special interpretation of the characters
  87. \fB*?[]\e\fR in \fIpattern\fR.
  88. .RE
  89. .TP
  90. \fBstring range \fIstring first last\fR
  91. Returns a range of consecutive characters from \fIstring\fR, starting
  92. with the character whose index is \fIfirst\fR and ending with the
  93. character whose index is \fIlast\fR.  An index of 0 refers to the
  94. first character of the string.  \fILast\fR may be \fBend\fR (or any
  95. abbreviation of it) to refer to the last character of the string.
  96. If \fIfirst\fR is less than zero then it is treated as if it were zero, and
  97. if \fIlast\fR is greater than or equal to the length of the string then
  98. it is treated as if it were \fBend\fR.  If \fIfirst\fR is greater than
  99. \fIlast\fR then an empty string is returned.
  100. .TP
  101. \fBstring tolower \fIstring\fR
  102. Returns a value equal to \fIstring\fR except that all upper case
  103. letters have been converted to lower case.
  104. .TP
  105. \fBstring toupper \fIstring\fR
  106. Returns a value equal to \fIstring\fR except that all lower case
  107. letters have been converted to upper case.
  108. .TP
  109. \fBstring trim \fIstring\fR ?\fIchars\fR?
  110. Returns a value equal to \fIstring\fR except that any leading
  111. or trailing characters from the set given by \fIchars\fR are
  112. removed.
  113. If \fIchars\fR is not specified then white space is removed
  114. (spaces, tabs, newlines, and carriage returns).
  115. .TP
  116. \fBstring trimleft \fIstring\fR ?\fIchars\fR?
  117. Returns a value equal to \fIstring\fR except that any
  118. leading characters from the set given by \fIchars\fR are
  119. removed.
  120. If \fIchars\fR is not specified then white space is removed
  121. (spaces, tabs, newlines, and carriage returns).
  122. .TP
  123. \fBstring trimright \fIstring\fR ?\fIchars\fR?
  124. Returns a value equal to \fIstring\fR except that any
  125. trailing characters from the set given by \fIchars\fR are
  126. removed.
  127. If \fIchars\fR is not specified then white space is removed
  128. (spaces, tabs, newlines, and carriage returns).
  129.  
  130. .SH KEYWORDS
  131. case conversion, compare, index, match, pattern, string
  132.