ns_set - Manipulate sets of key-value pairs
This command is used to manipulate sets of key-value pairs or "fields". The fields in the set are ordered by number. The field numbers start at zero and increase by one, up to the total number of fields. An ns_set is actually a multiset - in other words, the same key can appear multiple times in the same set. This data structure is particularly useful for things like HTTP headers which have this same property. The allowed options (which may be abbreviated) are:
Returns the contents of the setId in a string representation similar to Tcl's array get format. This is useful for converting an ns_set to an array or for iterating over the key-value pairs with foreach. Since ns_sets can contain the same key multiple times, converting an ns_set to an array can result in an array that is not exactly the same as the original ns_set as keys in an array are unique.
Frees all sets in the current interp. This command is autoamtically executed by ns_cleanup, which runs after every request, freeing all sets created via ns_set.
Returns a new set that has the same name and contents as the set referenced in setId. The new set is automatically freed when the transaction ends.
Appends a new field to the set with key and value, if the field does not already exist in the set (conditional put). If the field already exists in the set, the set is unchanged. Returns the field number of the new field, or the field number of the existing field if it already exists in the set.
Allocates memory for a new set and returns the setId for the new set. The new set is automatically freed when the transaction ends.
Deletes the field in the set at field number fieldNumber.
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.
Returns the index of the first field in the specified setId whose key matches the specified key. Indexing starts at zero. If no matching fields are found, ns_set find returns -1.
Frees the specified set. Sets are automatically freed when the transaction ends, but for loops with many iterations it might be useful to free sets manually.
Returns the first value associated with key. If key isn't in the set, the default or an empty string is returned.
Case-insensitive counterpart of ns_set cput.
Case-insensitive counterpart of ns_set delkey.
Case-insensitive counterpart of ns_set find.
Case-insensitive counterpart of ns_set get.
Merges two sets. This is the case insensitive version of ns_set merge.
Returns 1 if the value of the field specified by fieldNumber is null and 0 if it is not. Note that an empty string is not the same as a null. ns_set isnull will return 0 if the value is an empty string.
Case-insensitive counterpart of ns_set unique.
Case-insensitive counterpart of ns_set update.
Returns the key for the field numbered fieldNumber. This command is useful when looping through all the key-value pairs in the set in order.
Returns a list of all keys in the given ns_set. If a pattern is supplied, only those keys that match it (according to the Tcl rules of string match) will be returned.
Returns the list of all ns_sets.
Merges two sets. Any fields in the low set are appended to the high set if a field with the same key name does not already exist in the high set.
Moves all fields from the from set to the end of the to set, leaving the from set a valid, empty set.
Returns the name of the set. Returns an empty string if no name has been set.
Prints the specified set to stderr which should go to the server log. This is useful for debugging, but ns_set array may be more useful in actual code.
Appends a new field to the set with key and value. Note that the field is appended so if a previous field has the same key as the new field, the previous field will be returned by ns_set get. The field number of the new field is returned.
Returns the number of fields in the set.
Splits one set into multiple sets based on the splitChar as described below, and returns a Tcl list of IDs for the newly-allocated sets. It assumes that the keys in the source setId contain a specific character (splitChar) that can be used to separate the name of a new set and the key in the new set. The default splitChar is a period ".".
Removes any fields with index fieldNumber or greater and frees any memory allocated for them.
Returns 1 if the specified key is unique in the specified set and 0 if it is not. For example, a web browser could send multiple "Accept:" headers which would end up in the header set for the connection. ns_set unique would return 0 for the "Accept:" key, because there are multiple fields with the key "Accept:". The test for uniqueness is performed case-sensitively.
Updates the first field in the specified set whose key is key and replaces its value with value. This is roughly equivalent to ns_set delkey followed by ns_set put. Only the first occurrence of the named field is updated.
Returns the value of the set at field number fieldNumber. This command is useful when looping through all the key-value pairs in the set.
Returns a list of all values in the given ns_set. If a pattern is supplied, only those values that match it (according to the Tcl rules of string match) will be returned.
% set mySet [ns_set create mySetName a b c d e f A Joe B John C Jeff] d0
% ns_set size $mySet 6
% ns_set name $mySet mySetName
% ns_set array $mySet a b c d e f A Joe B John C Jeff
% ns_set keys $mySet a c e A B C
% ns_set values $mySet b d f Joe John Jeff
% ns_set get $mySet A Joe
% ns_set iget $mySet a b
% ns_set unique $mySet a 1
% ns_set iunique $mySet a 0
% ns_set truncate $mySet 3
% ns_set print $mySet
mySetName:
a = b
c = d
e = f
% ns_set update $mySet c "Hello World!" 2
% ns_set print $mySet
mySetName:
a = b
e = f
c = Hello World!
% ns_set find $mySet c 2
% ns_set find $mySet nokey -1
% ns_set delete $mySet 0
% ns_set array $mySet
e f c {Hello World!}
% set anotherSet [ns_set create] d1
% ns_set list d0 d1
% ns_set put $anotherSet dog.food "Yummy dog food!" 0
% ns_set put $anotherSet cat.food "Yummy cat food!" 1
% ns_set print $anotherSet
dog.food = Yummy dog food!
cat.food = Yummy cat food!
% set newSets [ns_set split $anotherSet] d2 d3
% foreach s $newSets { ns_set print $s }
dog:
food = Yummy dog food!
cat:
food = Yummy cat food!
% ns_set key $anotherSet 0 dog.food
% ns_set value $anotherSet 1 Yummy cat food!
% ns_set move $mySet $anotherSet d0
% ns_set array $mySet
e f c {Hello World!} dog.food {Yummy dog food!} cat.food {Yummy cat food!}
% ns_set array $anotherSet
% set thirdSet [ns_set new] d4
% ns_set move $thirdSet $mySet d4
% ns_set array $thirdSet
e f c {Hello World!} dog.food {Yummy dog food!} cat.food {Yummy cat food!}
% array set testArray [ns_set array $thirdSet]
# to run through an ns_set
for {set i 0} {$i < [ns_set size $myset]} {incr i} {
set key [ns_set key $myset $i]
set value [ns_set value $myset $i]
}
NULL values, distinct from empty strings, are useful when representing a database row as an ns_set. Currently, it is difficult to get a NULL value in an ns_set through the Tcl API. You may get a NULL value in the set created by ns_parsequery or by omitting the last value when seeding the ns_set in the create/new subcommand, etc. It is possible to create NULL-valued fields through the C API.
ns_set is intended for relatively small amounts of data. (Keys are found by a linear search through the whole underlying C array.) If you stuff very large amounts of data into an ns_set, performance will be poor - use a Tcl Array or a Tcl dict instead.