From 2261616ddbbf824bbb6b7edafe1269baf0ce0f94 Mon Sep 17 00:00:00 2001
From: hobbs <hobbs>
Date: Mon, 7 Jul 2003 20:36:32 +0000
Subject: doc/array.n: add examples from Welton

---
 ChangeLog   |  4 ++++
 doc/array.n | 30 +++++++++++++++++++++++++++---
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 21103fb..1d70982 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2003-07-07  Jeff Hobbs  <jeffh@ActiveState.com>
+
+	* doc/array.n: add examples from Welton
+
 2003-06-23  Vince Darley  <vincentdarley@users.sourceforge.net>
 
 	* doc/file.n: clarification of 'file tail' behaviour [Bug 737977]
diff --git a/doc/array.n b/doc/array.n
index b04c89f..4759dd7 100644
--- a/doc/array.n
+++ b/doc/array.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: array.n,v 1.8 2000/09/07 14:27:45 poenitz Exp $
+'\" RCS: @(#) $Id: array.n,v 1.9 2003/07/07 20:36:32 hobbs Exp $
 '\" 
 .so man.macros
 .TH array n 8.3 Tcl "Tcl Built-In Commands"
@@ -114,7 +114,9 @@ command should be invoked.
 The return value is a
 search identifier that must be used in \fBarray nextelement\fR
 and \fBarray donesearch\fR commands; it allows multiple
-searches to be underway simultaneously for the same array.
+searches to be underway simultaneously for the same array.  Unless
+dealing with a very large array, it is probably easier to use the
+\fBarray get\fR command to loop through an array, as in the examples below.
 .VS 8.4
 .TP
 \fBarray statistics \fIarrayName\fR
@@ -134,8 +136,30 @@ an array variable, then the command unsets the entire array.
 The command always returns an empty string.
 .VE 8.3
 
+.SH EXAMPLES
+
+.CS
+array set colorcount {red 1 green 5 blue 4 white 9}
+
+foreach {color count} [array get colorcount] {
+    puts "Color: $color Count: $count"
+}
+ => Color: blue Count: 4
+    Color: white Count: 9
+    Color: green Count: 5
+    Color: red Count: 1
+
+foreach color [array names colorcount] {
+    puts "Color: $color Count: $colorcount($color)"
+}
+ => Color: blue Count: 4
+    Color: white Count: 9
+    Color: green Count: 5
+    Color: red Count: 1
+.CE
+
 .SH "SEE ALSO"
-list(n), string(n), variable(n), trace(n)
+list(n), string(n), variable(n), trace(n), foreach(n)
 
 .SH KEYWORDS
 array, element names, search
-- 
cgit v0.12