1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
% Copyright The Numerical Algorithms Group Limited 1992-94. All rights reserved.
% !! DO NOT MODIFY THIS FILE BY HAND !! Created by ht.awk.
\newcommand{\KeyedAccessFileXmpTitle}{KeyedAccessFile}
\newcommand{\KeyedAccessFileXmpNumber}{9.38}
%
% =====================================================================
\begin{page}{KeyedAccessFileXmpPage}{9.38 KeyedAccessFile}
% =====================================================================
\beginscroll
The domain \spadtype{KeyedAccessFile(S)} provides files which can be used as
%-% \HDindex{file!keyed access}{KeyedAccessFileXmpPage}{9.38}{KeyedAccessFile}
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
\spadtype{StringTable(S)} domain.
The difference is that keyed access files reside in secondary storage while
string tables are kept in memory.
For more information on table-oriented operations, see the description of
\spadtype{Table}.
\xtc{
Before a keyed access file can be used, it must first be opened.
A new file can be created by opening it for output.
}{
\spadpaste{ey: KeyedAccessFile(Integer) := open("/tmp/editor.year", "output") \bound{ey}}
}
\xtc{
Just as for vectors, tables or lists, values are saved in a keyed access file
by setting elements.
}{
\spadpaste{ey."Char" := 1986 \free{ey}\bound{eya}}
}
\xtc{
}{
\spadpaste{ey."Caviness" := 1985 \free{ey}\bound{eyb}}
}
\xtc{
}{
\spadpaste{ey."Fitch" := 1984 \free{ey}\bound{eyc}}
}
\xtc{
Values are retrieved using application, in any of its syntactic forms.
}{
\spadpaste{ey."Char" \free{eya}}
}
\xtc{
}{
\spadpaste{ey("Char") \free{eya}}
}
\xtc{
}{
\spadpaste{ey "Char" \free{eya}}
}
\xtc{
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
\spadfunFrom{search}{KeyedAccessFile} operation.
}{
\spadpaste{search("Char", ey) \free{eya,eyb,eyc}\bound{eyaa}}
}
\xtc{
}{
\spadpaste{search("Smith", ey) \free{eyaa}}
}
\xtc{
When an entry is no longer needed, it can be removed from the file.
}{
\spadpaste{remove!("Char", ey) \free{eyaa}\bound{eybb}}
}
\xtc{
The \spadfunFrom{keys}{KeyedAccessFile} operation returns a list of all the
keys for a given file.
}{
\spadpaste{keys ey \free{eybb}}
}
\xtc{
The \spadfunFrom{\#}{KeyedAccessFile} operation gives the
number of entries.
}{
\spadpaste{\#ey \free{eybb}}
}
The table view of keyed access files provides safe operations.
That is, if the \Language{} 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.
\xtc{
Here we add several more items to the file, then check its contents.
}{
\spadpaste{KE := Record(key: String, entry: Integer) \bound{KE}}
}
\xtc{
}{
\spadpaste{reopen!(ey, "output") \free{eybb,KE}\bound{eycc}}
}
\xtc{
If many items are to be added to a file at the same time, then
it is more efficient to use the \spadfunFromX{write}{KeyedAccessFile} operation.
}{
\spadpaste{write!(ey, ["van Hulzen", 1983]\$KE) \bound{eyccA}\free{eycc}}
}
\xtc{
}{
\spadpaste{write!(ey, ["Calmet", 1982]\$KE) \bound{eyccB}\free{eycc}}
}
\xtc{
}{
\spadpaste{write!(ey, ["Wang", 1981]\$KE) \bound{eyccC}\free{eycc}}
}
\xtc{
}{
\spadpaste{close! ey \free{eyccA,eyccB,eyccC}\bound{eydd}}
}
\xtc{
The \spadfunFromX{read}{KeyedAccessFile} 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
\spadfunFrom{keys}{KeyedAccessFile} operation and to extract elements by
key.
}{
\spadpaste{keys ey \free{eydd}}
}
\xtc{
}{
\spadpaste{members ey \free{eydd}}
}
\noOutputXtc{
}{
\spadpaste{)system rm -r /tmp/editor.year \free{ey}}
}
For more information on related topics, see
\downlink{`File'}{FileXmpPage}\ignore{File},
\downlink{`TextFile'}{TextFileXmpPage}\ignore{TextFile}, and
\downlink{`Library'}{LibraryXmpPage}\ignore{Library}.
%
\showBlurb{KeyedAccessFile}
\endscroll
\autobuttons
\end{page}
%
|
