:TITLE: Introduction to dict: Basics
;#
;# RCSID: $Header: /home/cvs/TclTutor3/lesson/Tcl_English/Tcl_English44.lsn,v 1.2 2010/12/22 15:53:19 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:
The <CODE>dict</CODE> commands implement a paired list data structure
in which a key and value are guaranteed to maintain their relationship, 
and order is maintained.
<P>
This is like a merger of an associative array (key/value pairs) and
the list (ordered data) structures.
<P>
The <CODE>dict</CODE> command has several subcommands.  The critical
ones are:
<DL>

  <BR><DT><CODE>dict create <I>?key val? ?key val?</I></CODE>
  <DD>Create a new dict and return values to be assigned to a variable.

  <BR><DT><CODE>dict set <I>dictName key val </I></CODE>
  <DD>Assign a new key/value pair to the dictionary named <CODE><I>dictName</I></CODE>.<BR>
  You can only assign values to a single key at a time.  If there are
  multiple key/value pairs, you must be creating a new index, and the
  values will be treated as nested dicts.  See the lesson on nested dicts
  for more information.

  <BR><DT><CODE>dict get<I> $dictName key</I></CODE>
  <DD>Return the value associated with the key in the dictionary.

  <BR><DT><CODE>dict size<I> $dictName </I></CODE>
  <DD>Return the number of key/value pairs in the dictionary.

  <BR><DT><CODE>dict keys<I> $dictName ?pattern?</I></CODE>
  <DD>Return a list of the keys in the dictionary.  Optionally, only the 
      keys that match a pattern.

  <BR><DT><CODE>dict values<I> $dictName</I></CODE>
  <DD>Return a list of the patterns in a dictionary.  Optionally, only the 
      values that match a pattern.
</DL>
<P>
  Note that like the <CODE>set</CODE> command, the <CODE>dict set</CODE>
takes the name of a dictionary, not the contents of a dictionary.  The
other commands use the contents of a dictionary, and are invoked with
a <CODE>$dictName</CODE> argument.
:TEXT_END:

:LESSON_TEXT_START_LEVEL 1:
The <CODE>dict</CODE> commands implement a paired list data structure
in which a key and value are guaranteed to maintain their relationship
and order of the indices is maintained.

<P> 

This is like a merger of an associative array (key/value pairs) and
the list (ordered data) structures.  An associative array guarantees
that the value associated with a given index won't change (unless an
application changes it) but doesn't guarantee the order of indices.  A
list guarantees that the elements won't change order (again unless 
your code changes things) but doesn't show how one value is related
to another.

<P>
The <CODE>dict</CODE> command has several subcommands.  The critical
ones are:
<DL>
  <BR><DT><CODE>dict create <I>?key val? ?key val?</I></CODE>
  <DD>Create a new dict and return values to be assigned to a variable.<BR>
  You may have zero or more <CODE>key</CODE> and <CODE>value</CODE>
  pairs, but the every key must have a value.
  
  <BR><DT><CODE>dict set <I>dictName key val </I></CODE>
  <DD>Assign a new key/value pair to the dictionary named <CODE><I>dictName</I></CODE>.<BR>
  You can only assign values to a single key at a time.  If there are
  multiple key/value pairs, you must be creating a new index, and the
  values will be treated as nested dicts.  See the lesson on nested dicts
  for more information.
  Note that <CODE>set</CODE> uses a variable name, not the value.

  <BR><DT><CODE>dict get<I> $dictName key</I></CODE>
  <DD>Return the value associated with the key in the dictionary.<BR>
  Only one key can be queried at a time.

  <BR><DT><CODE>dict size<I> $dictName </I></CODE>
  <DD>Return the number of key/value pairs in the dictionary.

  <BR><DT><CODE>dict keys<I> $dictName ?pattern?</I></CODE>
  <DD>Return a list of the keys in the dictionary.  Optionally, only the 
      keys that match a pattern.

  <BR><DT><CODE>dict values<I> $dictName</I></CODE>
  <DD>Return a list of the patterns in a dictionary.  Optionally, only the 
      values that match a pattern.
</DL>
<P>
  Note that like the <CODE>set</CODE> command, the <CODE>dict set</CODE>
takes the name of a dictionary, not the contents of a dictionary.  The
other commands use the contents of a dictionary, and are invoked with
a <CODE>$dictName</CODE> argument.
<P>
The <CODE>dict keys</CODE> command makes it easy to write foreach loops 
to process the data in a dictionary, similar to processing data in an
associative array .
:TEXT_END:

:LESSON_TEXT_START_LEVEL 2:
There are many ways to look at computer data.  Two of these are:
  <UL>
    <LI> Data comes in key/value pairs: John is 25 years, Marsha is
    24 years old.
    <P>
    You can work with this data using an associative array:
    <PRE><CODE>
      set age(john) 25
      set age(mary) 24
    </CODE></PRE>
    An associative array maintains the relationship between the 
    index and the value, but does not maintain the order of
    John coming before Mary.

    <P><LI> The order of the data is important: put on socks,
    then put on shoes
    <P>
    You can work with this data using a Tcl list:
    <PRE><CODE>
      set clothesList {socks shoes}
      foreach apparel $clothesList {
        put_on $apparel
      }
    </CODE></PRE>
    A list maintains the order, but has no key/value combinations.
  </UL>
<P>
  What do you do when you have data with a key/value pairs that
needs to be processed in a particular order?

<P>

In that case, you use the <CODE>dict</CODE> command.

<P>
The <CODE>dict</CODE> commands implement a paired list data structure
in which a key and value are guaranteed to maintain their relationship
and order of the indices is maintained.

<P> 

This is like a merger of an associative array (key/value pairs) and
the list (ordered data) structures.  An associative array guarantees
that the value associated with a given index won't change (unless an
application changes it) but doesn't guarantee the order of indices.  A
list guarantees that the elements won't change order (again unless 
your code changes things) but doesn't show how one value is related
to another.
<P>
The <CODE>dict</CODE> command is a family of several commands.  
<P>
The <CODE>dict</CODE> command has several subcommands.  The critical
ones are:
<DL>
  <BR><DT><CODE>dict create <I>?key val? ?key val?</I></CODE>
  <DD>Create a new dict and return values to be assigned to a variable.<BR>
  You may have zero or more <CODE>key</CODE> and <CODE>value</CODE>
  pairs, but the every key must have a value.
  
  <BR><DT><CODE>dict set <I>dictName key val </I></CODE>
  <DD>Assign a new key/value pair to the dictionary named <CODE><I>dictName</I></CODE>.<BR>
  You can only assign values to a single key at a time.  If there are
  multiple key/value pairs, you must be creating a new index, and the
  values will be treated as nested dicts.  See the lesson on nested dicts
  for more information.

  <BR>Note that <CODE>set</CODE> uses a variable name, not the value.

  <BR><DT><CODE>dict get<I> $dictName key</I></CODE>
  <DD>Return the value associated with the key in the dictionary.<BR>
  Only one key can be queried at a time.

  <BR><DT><CODE>dict size<I> $dictName </I></CODE>
  <DD>Return the number of key/value pairs in the dictionary.

  <BR><DT><CODE>dict keys<I> $dictName ?pattern?</I></CODE>
  <DD>Return a list of the keys in the dictionary.  Optionally, only the 
      keys that match a pattern.

  <BR><DT><CODE>dict values<I> $dictName</I></CODE>
  <DD>Return a list of the patterns in a dictionary.  Optionally, only the 
      values that match a pattern.
</DL>
<P>
  Note that like the <CODE>set</CODE> command, the <CODE>dict set</CODE>
takes the name of a dictionary, not the contents of a dictionary.  The
other commands use the contents of a dictionary, and are invoked with
a <CODE>$dictName</CODE> argument.
<P>
The <CODE>dict keys</CODE> command makes it easy to write foreach loops 
to process the data in a dictionary, similar to processing data in an
associative array .
:TEXT_END:

:CODE_START:
#Create a dict
set dict1 [dict create a 1 b 2]

# Assign a couple of key/value pairs.
dict set dict1 c 3
dict set dict1 d 4

# How many pairs are in this dict
puts "there are [dict size $dict1] pairs in dict1"

# What are the keys and values
puts "The keys are: [dict keys $dict1]"
puts "The values are: [dict values $dict1]"

puts "\nShow the key/value pairs using get"
foreach key [dict keys $dict1] {
  puts "The value associated with $key is [dict get $dict1 $key]"
}
puts "\nShow the key/value pairs using two loop variables."
foreach key [dict keys $dict1]  val [dict values $dict1] {
  puts "The value associated with $key is $val"
}
:TEXT_END:

