====================================================================
KeyedAccessFile examples
====================================================================

The domain KeyedAccessFile(S) provides files which can be used
as associative tables.  Data values are stored in these files and can
be retrieved according to their keys.  The keys must be strings so
this type behaves very much like the StringTable(S) domain.  The
difference is that keyed access files reside in secondary storage
while string tables are kept in memory.  

Before a keyed access file can be used, it must first be opened.
A new file can be created by opening it for output.

  ey: KeyedAccessFile(Integer) := open("editor.year", "output")

Just as for vectors, tables or lists, values are saved in a keyed
access file by setting elements.

  ey."Char":= 1986

  ey."Caviness" := 1985

  ey."Fitch"    := 1984

Values are retrieved using application, in any of its syntactic forms.

  ey."Char"

  ey("Char")

  ey "Char"

Attempting to retrieve a non-existent element in this way causes an
error.  If it is not known whether a key exists, you should use the
search operation.

  search("Char", ey)

  search("Smith", ey)

When an entry is no longer needed, it can be removed from the file.

  remove!("Char", ey)

The keys operation returns a list of all the keys for a given file.

  keys ey

The # operation gives the number of entries.

  #ey

The table view of keyed access files provides safe operations.  That
is, if the FriCAS program is terminated between file operations, the
file is left in a consistent, current state.  This means, however,
that the operations are somewhat costly.  For example, after each
update the file is closed.

Here we add several more items to the file, then check its contents.

  KE := Record(key: String, entry: Integer)

  reopen!(ey, "output")

If many items are to be added to a file at the same time, then it is
more efficient to use the write operation.

  write!(ey, ["van Hulzen", 1983]$KE)

  write!(ey, ["Calmet", 1982]$KE)

  write!(ey, ["Wang", 1981]$KE)

  close! ey

The read operation is also available from the file view, but it
returns elements in a random order.  It is generally clearer and more
efficient to use the keys operation and to extract elements by key.

  keys ey

  members ey

  )system rm -r editor.year

See Also:
o )help Table
o )help StringTable
o )help File
o )help TextFile
o )help Library
o )show KeyedAccessFile

