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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
<HTML><HEAD>
<TITLE>Tcl API Reference -- ns_set</TITLE>
<LINK rel=Previous href="tapi-119.htm">
<LINK rel=ToC href="toc.htm">
<LINK rel=Index href="master.htm">
<LINK rel=Next href="tapi-121.htm">
</HEAD><BODY BGCOLOR="#ffffff"><A NAME="topofpage"></A>
<TABLE WIDTH=100%>
<TR>
<TD ALIGN=LEFT>
<A NAME="topofpage"></A> <IMG SRC="as-c-sm.gif">
</TD>
<TD ALIGN=RIGHT>
<A href="tapi-119.htm"><IMG BORDER="0" src=navbprev.gif alt="[ Previous ]"></A>
<A href=toc.htm> <IMG BORDER="0" src=navbhome.gif alt="[ Contents ]"></A>
<A href=master.htm> <IMG BORDER="0" src=navbhelp.gif alt="[ Index ]"></A>
<A href="tapi-121.htm"> <IMG BORDER="0" src=navbnext.gif alt="[ Next ]"></A>
<A name="7983"> </A>
</TD>
</TR>
</TABLE>
<a name="197598">
</a><h3>ns_set</h3>
<a name="4081">
</a><h4>Overview</h4>
<p><a name="4083">
</a>Manipulate sets of key-value pairs</p>
<a name="4085">
</a><h4>Syntax</h4>
<p><a name="82015">
</a><b>ns_set copy</b> -persist <i>setId</i></p>
<p><a name="83055">
</a><b>ns_set cput</b> <i>setId key value</i></p>
<p><a name="82021">
</a><b>ns_set create</b> -persist <i>name</i></p>
<p><a name="81996">
</a><b>ns_set delete</b> <i>setId fieldNumber</i></p>
<p><a name="81997">
</a><b>ns_set delkey</b> <i>setId key</i></p>
<p><a name="82023">
</a><b>ns_set find</b> <i>setId key</i></p>
<p><a name="82118">
</a><b>ns_set free</b> <i>setId</i></p>
<p><a name="81990">
</a><b>ns_set get </b><i>setId key</i></p>
<p><a name="83057">
</a><b>ns_set icput</b> <i>setId key value</i></p>
<p><a name="82001">
</a><b>ns_set idelkey</b> <i>setId key</i></p>
<p><a name="82025">
</a><b>ns_set ifind</b> <i>setId key</i></p>
<p><a name="81991">
</a><b>ns_set iget </b><i>setId key</i></p>
<p><a name="82027">
</a><b>ns_set isnull</b> <i>setId fieldNumber</i></p>
<p><a name="82028">
</a><b>ns_set iunique</b> <i>setId key</i></p>
<p><a name="81992">
</a><b>ns_set key</b> <i>setId fieldNumber</i></p>
<p><a name="82030">
</a><b>ns_set merge</b> <i>high low</i></p>
<p><a name="82032">
</a><b>ns_set move</b> <i>to from</i></p>
<p><a name="81982">
</a><b>ns_set name </b><i>setId</i></p>
<p><a name="82017">
</a><b>ns_set new</b> -persist <i>name</i></p>
<p><a name="133147">
</a><b>ns_set print</b> <i>setId</i></p>
<p><a name="82005">
</a><b>ns_set put</b> <i>setId key value</i></p>
<p><a name="4091">
</a><b>ns_set size </b><i>setId</i></p>
<p><a name="82019">
</a><b>ns_set split</b> -persist <i>setId</i> ?<i>splitChar</i>?</p>
<p><a name="82034">
</a><b>ns_set truncate</b> <i>setId size</i></p>
<p><a name="82036">
</a><b>ns_set unique</b> <i>setId key</i></p>
<p><a name="82037">
</a><b>ns_set update</b> <i>setId key value</i></p>
<p><a name="4097">
</a><b>ns_set value</b> <i>setId fieldNumber</i></p>
<a name="4107">
</a><h4>Description</h4>
<p><a name="82071">
</a><b>ns_set copy</b> returns a new set that has the same name and key value pairs as the passed-in set (<i>setId</i>). If -persist is specified, the new set will persist even after the current transaction ends, and you can free it later with <b>ns_set free</b>. If -persist is not specified, the new set is automatically freed when the transaction ends.</p>
<p><a name="83064">
</a><b>ns_set cput </b>appends a new field to the set with key <i>key</i> and value <i>value </i>if the field does not already exist in the set. The field number of the new field is returned.</p>
<p><a name="83062">
</a><b>ns_set create</b> (which is the same as <b>ns_set new</b>) allocates memory for a new set and returns the ID for the new set. If -persist is specified, the new set will persist even after the current transaction ends, and you can free it later with <b>ns_set free</b>. If -persist is not specified, the new set is automatically freed when the transaction ends.</p>
<p><a name="82047">
</a><b>ns_set delete</b> deletes the field in the set at field number fieldNumber.</p>
<p><a name="82048">
</a><b>ns_set delkey</b> removes the first field in the set whose key is key. Note that there could be multiple fields in the set with this key; this command only removes the first occurrence.</p>
<p><a name="82075">
</a><b>ns_set find</b> returns the index of the first field in the specified set whose key name matches the specified <i>key</i>. Zero (0) is the index of the first field. If no matching fields are found, <b>ns_set find</b> returns -1.</p>
<p><a name="82077">
</a><b>ns_set free</b> frees the specified set. Sets must be explicitly freed with <b>ns_set free</b> if the -persist option was used when creating the set. Otherwise, sets are automatically freed when the transaction ends.</p>
<p><a name="82039">
</a><b>ns_set get</b> returns the first value associated with the passed-in key. If the key is invalid, an empty string is returned.</p>
<p><a name="83071">
</a><b>ns_set icput</b> is the case-insensitive counterpart of <b>ns_set cput</b>.</p>
<p><a name="82056">
</a><b>ns_set idelkey</b> is the case-insensitive counterpart of <b>ns_set delkey</b>.</p>
<p><a name="82079">
</a><b>ns_set ifind</b> is the case-insensitive counterpart of <b>ns_set find</b>.</p>
<p><a name="82040">
</a><b>ns_set iget</b> is the case-insensitive counterpart of <b>ns_set get</b>.</p>
<p><a name="82081">
</a><b>ns_set isnull</b> returns 1 if the value of the field specified by <i>fieldNumber</i> is null and 0 if it is not. Note that an empty string is not the same as a null. <b>ns_set isnull</b> will return 0 for an empty string.</p>
<p><a name="82083">
</a><b>ns_set iunique</b> returns 1 if the specified key is unique in the specified set and 0 if it is not. The test for uniqueness is performed case-insensitively. <b>ns_set unique</b> is the case-sensitive version of this function.</p>
<p><a name="82084">
</a>For example, a client could send multiple "Accept:" headers which would end up in the header set for the connection. <b>ns_set iunique</b> would return 0 for the "Accept:" key, because there are multiple fields with the key "Accept:".</p>
<p><a name="82041">
</a><b>ns_set key</b> extracts the key of the set at field number fieldNumber. This command is useful when looping through all the key-value pairs in the set.</p>
<p><a name="82106">
</a><b>ns_set merge</b> merges two sets. Any fields in the <i>low</i> set are appended to the <i>high</i> set if a field with the same key name does not already exist in the <i>high</i> set.</p>
<p><a name="82107">
</a><b>ns_set move</b> moves all fields from the <i>from</i> set to the end of the <i>to</i> set, leaving the <i>from</i> set a valid, empty set.</p>
<p><a name="82052">
</a><b>ns_set name</b> returns the name of the set.</p>
<p><a name="82109">
</a><b>ns_set new</b> (which is the same as <b>ns_set create</b>) allocates memory for a new set and returns the ID for the new set. If -persist is specified, the new set will persist even after the current transaction ends, and you can free it later with <b>ns_set free</b>. If -persist is not specified, the new set is automatically freed when the transaction ends.</p>
<p><a name="133148">
</a><b>ns_set print</b> prints the specified set to stderr.</p>
<p><a name="82060">
</a><b>ns_set put</b> appends a new field to the set with key <i>key</i> and value <i>value</i>. Note that the field is appended so if a previous field has the same key as the new field, the previous field is returned by ns_set get command. The field number of the new field is returned.</p>
<p><a name="4113">
</a><b>ns_set size</b> returns the number of key-value pairs in the set.</p>
<p><a name="82111">
</a><b>ns_set split</b> splits one set into multiple sets based on the <i>splitChar</i> as described below and returns a Tcl list of the newly-allocated sets. It assumes that the keys in the specified set (<i>setId</i>) contain a specific character (<i>splitChar</i>) that can be used to separate the name of a new set and the key in the new set. The default <i>splitChar</i> is a period (.).</p>
<p><a name="82112">
</a>For example, if two fields in the original set have "dog.food" and "cat.food" as their key names and "Yummy dog food!" and "Yummy cat food!" as their values, <b>ns_set split</b> would return two new sets named "dog" and "cat". The dog set would have a single field whose key is "food" and whose value is "Yummy dog food!". The cat set would have a single field whose key is "food" and whose value is "Yummy cat food!".</p>
<p><a name="82114">
</a><b>ns_set truncate</b> reduces the set to the first <i>size</i> key-value pairs and frees the memory for the rest of the key-value pairs that may have been in the set.</p>
<p><a name="82115">
</a><b>ns_set unique</b> returns 1 if the specified key is unique in the specified set and 0 if it is not. The test for uniqueness is performed case-sensitively. <b>ns_set iunique</b> is the case-insensitive version of this function.</p>
<p><a name="82116">
</a><b>ns_set update</b> updates the first field in the specified set whose key is <i>key</i> and replaces its value with <i>value</i>. ns_set update is equivalent to <b>ns_set delkey</b> followed by <b>ns_set put</b>.</p>
<p><a name="4119">
</a><b>ns_set value</b> extracts the value of the set at field number fieldNumber. This command is useful when looping through all the key-value pairs in the set.</p>
<a name="4131">
</a><h4>Notes</h4>
<p><a name="147912">
</a>The fields in the set are ordered by number. The field numbers range from 0 to one less than the total number of fields. For example, if you have a set with 5 fields, you would use "ns_set key $setid 4" to extract the key of the last field in the set..</p>
<TABLE BORDER="2" CELLPADDING="1" width="100%">
<TR><TD COLSPAN=3><P ALIGN=Center>
<IMG SRC="bluebult.gif">
<A HREF="#topofpage">
<FONT SIZE=-1>Top of Page</FONT></A>
<IMG SRC="bluebult.gif">
</TD></TR>
<TR><TD COLSPAN=3><P ALIGN=Center>
<A href="tapi-119.htm">
<IMG BORDER="0" src=navbprev.gif alt="[ Previous ]"></A>
<A href=toc.htm>
<IMG BORDER="0" src=navbhome.gif alt="[ Contents ]"></A>
<A href=master.htm>
<IMG BORDER="0" src=navbhelp.gif alt="[ Index ]"></A>
<A href="tapi-121.htm">
<IMG BORDER="0" src=navbnext.gif alt="[ Next ]"></A>
<BR align=center>
<FONT size=-1>Copyright © 1998-99 America Online,
Inc.</FONT>
</TD></TR></TABLE></BODY></HTML>
|
