:TITLE: Introduction to dict: Modifying Dict Data
;#
;# RCSID: $Header: /home/cvs/TclTutor3/lesson/Tcl/TclLesson.dmy,v 1.1.1.1 2007/09/15 13:30:24 clif Exp $
;# Copyright (c) 1995 Clif Flynt
;# 9300 Fleming Rd.
;# Dexter, MI  48130
;# clif@cflynt.com
;# See file "NOTICE" for licensing terms.
;#
:LESSON_TEXT_START_LEVEL 0:

One of the interesting features of the dict datastructure is that it is
a dynamic structure.  Unlike a C struct, or an SQL table, you can add
new fields or modify field names inside an application.

Changing values or adding new key/value pairs  can be done with the
<CODE>dict set</CODE> command described previously.

A new dict with modified values can be created using the <CODE>dict
replace</CODE> command.  The <CODE>dict replace</CODE> command returns
a new dict with some values modified.  It will not modify any keys.

Syntax: <CODE>dict replace <I>dictValue key val ?key val?</I> </CODE>

The <CODE>dict update</CODE> provides access to all parts of a dict,
and can be used to access or modify the dict internals, including changing
keys.

Syntax: <CODE>dict update <I>dictVarName key varName ?key varName? body </I> </CODE>
<DL>
  <DT><CODE><I>dictVarName </I> </CODE>
  <DD>The name of a dict variable
  <DT><CODE><I>key varName ?key varName? </I> </CODE>
  <DD>Key is a toplevel key in this dict.  The variable <CODE>varName </CODE>
  will hold the value associated with that key.  If there are multiple 
  key/varName pairs, the script will be invoked multiple times, once for
  each key that is matched in the dict.  
  <P>
  If the key value is not in the
  dict, the associated <CODE>varName</CODE> will not exist.
  <P>  Any changes made to the contents of <CODE>varName</CODE> are reflected
  back into the dict.
  <DT><CODE><I> script</I> </CODE>
  <DD>A script to evaluate
</DL>
:TEXT_END:

:LESSON_TEXT_START_LEVEL 1:
:TEXT_END:

:LESSON_TEXT_START_LEVEL 2:
:TEXT_END:

:CODE_START:
set t1 [dict create a b c d]
puts "Start Dict is: $t1"

set t2 [dict replace $t1 a A]
puts "After Replace: $t2"

set t3 [dict replace $t1 a A b B c C]
puts "After Replace with unmatched key b: $t3"

dict update t1 a aa c cc {
  if {[info exists aa]} {set aa B}
  if {[info exists cc]} {set cc D}
}

puts "t1 after update: $t1"

set t1 {a b c d e f}
dict with t1  {
  puts "A: $a C: $c E: $e"
  puts "Does value exist? [info exists b] (0 = No)"
  set a AA
  set c CC
  set e EE
}

set t1 [dict create a {b c} d {e {f g}}]

# Look at first element:
puts "Contents of dict value for key=a: [dict with t1 a {puts $b}]"

puts "Contents of dict value for key=d: [dict with t1 d {puts $e}]"

puts "Contents of dict value for key=d/e: [dict with t1 d e {puts $f}]"

:TEXT_END:

	 
