Permalink
Browse files

Document [string map]

Reported-by: Lorance Stinson <lorancestinson@gmail.com>
Signed-off-by: Steve Bennett <steveb@workware.net.au>
  • Loading branch information...
1 parent 2d6673b commit dfbde800afdabc83efc9ebe087b1aed6a90136d8 @msteveb committed Oct 5, 2011
Showing with 95 additions and 22 deletions.
  1. +63 −14 Tcl_shipped.html
  2. +32 −8 jim_tcl.txt
View
@@ -5688,6 +5688,15 @@ <h3 id="_string">string</h3>
</p>
</dd>
<dt class="hdlist1">
+<tt><strong>string byterange</strong> <em>string first last</em></tt>
+</dt>
+<dd>
+<p>
+ Like <a href="#_string"><strong><tt>string</tt></strong></a> <tt>range</tt> except works on bytes rather than characters.
+ These commands are identical if UTF-8 support is not enabled.
+</p>
+</dd>
+<dt class="hdlist1">
<tt><strong>string compare ?-nocase?</strong> <em>string1 string2</em></tt>
</dt>
<dd>
@@ -5920,6 +5929,55 @@ <h3 id="_string">string</h3>
</p>
</dd>
<dt class="hdlist1">
+<tt><strong>string map ?-nocase?</strong> <em>mapping string</em></tt>
+</dt>
+<dd>
+<p>
+ Replaces substrings in <tt><em>string</em></tt> based on the key-value pairs in
+ <tt><em>mapping</em></tt>, which is a list of <tt>key value key value ...</tt> as in the form
+ returned by <a href="#_array"><strong><tt>array</tt></strong></a> <tt>get</tt>. Each instance of a key in the string will be
+ replaced with its corresponding value. If <tt>-nocase</tt> 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. <tt><em>string</em></tt> is
+ only iterated over once, so earlier key replacements will have no affect for
+ later key matches. For example,
+</p>
+<div class="literalblock">
+<div class="content">
+<pre><tt>string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc</tt></pre>
+</div></div>
+</dd>
+<dt class="hdlist1">
+
+</dt>
+<dd>
+<p>
+ will return the string <tt>01321221</tt>.
+</p>
+</dd>
+<dt class="hdlist1">
+
+</dt>
+<dd>
+<p>
+ 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,
+</p>
+<div class="literalblock">
+<div class="content">
+<pre><tt>string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc</tt></pre>
+</div></div>
+</dd>
+<dt class="hdlist1">
+
+</dt>
+<dd>
+<p>
+ it will return the string <tt>02c322c222c</tt>.
+</p>
+</dd>
+<dt class="hdlist1">
<tt><strong>string match ?-nocase?</strong> <em>pattern string</em></tt>
</dt>
<dd>
@@ -5949,12 +6007,12 @@ <h3 id="_string">string</h3>
</p>
</dd>
<dt class="hdlist1">
-<tt>[</tt><em>chars</em><tt>]</tt>
+<tt>[<em>chars</em>]</tt>
</dt>
<dd>
<p>
Matches any character in the set given by <tt><em>chars</em></tt>.
- If a sequence of the form <tt><em>x</em></tt>-<tt><em>y</em></tt> appears in <tt><em>chars</em></tt>,
+ If a sequence of the form <tt><em>x-y</em></tt> appears in <tt><em>chars</em></tt>,
then any character between <tt><em>x</em></tt> and <tt><em>y</em></tt>, inclusive,
will match.
</p>
@@ -5965,8 +6023,8 @@ <h3 id="_string">string</h3>
<dd>
<p>
Matches the single character <tt><em>x</em></tt>. This provides a way of
- avoiding the special interpretation of the characters <tt>\*?[]\</tt>
- in <tt><em>'+pattern</tt></em>'+.
+ avoiding the special interpretation of the characters <tt>\*?[]</tt>
+ in <tt><em>pattern</em></tt>.
</p>
</dd>
</dl></div>
@@ -6010,15 +6068,6 @@ <h3 id="_string">string</h3>
</p>
</dd>
<dt class="hdlist1">
-<tt><strong>string byterange</strong> <em>string first last</em></tt>
-</dt>
-<dd>
-<p>
- Like <em>string range</em> except works on bytes rather than characters. These commands
- are identical if UTF-8 support is not enabled
-</p>
-</dd>
-<dt class="hdlist1">
<tt><strong>string repeat</strong> <em>string count</em></tt>
</dt>
<dd>
@@ -7637,7 +7686,7 @@ <h2 id="_licence">LICENCE</h2>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
-Last updated 2011-09-26 14:30:23 EST
+Last updated 2011-10-06 07:52:30 EST
</div>
</div>
</body>
View
@@ -3730,6 +3730,10 @@ The legal options (which may be abbreviated) are:
or if the string is composed entirely of ASCII characters.
See UTF-8 AND UNICODE.
++*string byterange* 'string first last'+::
+ Like `string range` except works on bytes rather than characters.
+ These commands are identical if UTF-8 support is not enabled.
+
+*string compare ?-nocase?* 'string1 string2'+::
Perform a character-by-character comparison of strings +'string1'+ and
+'string2'+ in the same way as the C 'strcmp' procedure. Return
@@ -3799,6 +3803,30 @@ The legal options (which may be abbreviated) are:
If UTF-8 support is enabled, this may be different than the number of bytes.
See UTF-8 AND UNICODE
++*string map ?-nocase?* 'mapping string'+::
+ Replaces substrings in +'string'+ based on the key-value pairs in
+ +'mapping'+, which 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 doesn't. Matching is done in a fashion similar to that
@@ -3813,16 +3841,16 @@ The legal options (which may be abbreviated) are:
+?+;;
Matches any single character in +'string'+.
- +[+'chars'+]+;;
+ +['chars']+;;
Matches any character in the set given by +'chars'+.
- If a sequence of the form +'x'+-+'y'+ appears in +'chars'+,
+ If a sequence of the form +'x-y'+ appears in +'chars'+,
then any character between +'x'+ and +'y'+, inclusive,
will match.
+{backslash}x+;;
Matches the single character +'x'+. This provides a way of
- avoiding the special interpretation of the characters \`\*?[]\`
- in +''+pattern+''+.
+ avoiding the special interpretation of the characters +{backslash}*?[]+
+ in +'pattern'+.
::
Performs a case-insensitive comparison if +-nocase+ is specified.
@@ -3839,10 +3867,6 @@ The legal options (which may be abbreviated) are:
it is treated as if it were +end+. If +'first'+ is greater than
+'last'+ then an empty string is returned.
-+*string byterange* 'string first last'+::
- Like 'string range' except works on bytes rather than characters. These commands
- are identical if UTF-8 support is not enabled
-
+*string repeat* 'string count'+::
Returns a new string consisting of +'string'+ repeated +'count'+ times.

0 comments on commit dfbde80

Please sign in to comment.