bionic (3) ns_set.3aolserver.gz
NAME
ns_set - commands
SYNOPSIS
Manipulate sets of key-value pairs.
SYNTAX
ns_set copy ?-persist? setId
ns_set cput setId key value
ns_set create ?-persist? name
ns_set delete setId fieldNumber
ns_set delkey setId key
ns_set find setId key
ns_set free setId
ns_set get setId key
ns_set icput setId key value
ns_set idelkey setId key
ns_set ifind setId key
ns_set iget setId key
ns_set isnull setId fieldNumber
ns_set iunique setId key
ns_set key setId fieldNumber
ns_set merge high low
ns_set move to from
ns_set name setId
ns_set new ?-persist? name
ns_set print setId
ns_set put setId key value
ns_set size setId
ns_set split ?-persist? setId ?splitChar?
ns_set truncate setId size
ns_set unique setId key
ns_set update setId key value
ns_set value setId fieldNumber
_________________________________________________________________
DESCRIPTION
ns_set copy
Returns a new set that has the same name and key value pairs as the passed-in set (setId). If
-persist is specified, the new set will persist even after the current transaction ends, and you
can free it later with ns_set free. If -persist is not specified, the new set is automatically
freed when the transaction ends.
ns_set cput
appends a new field to the set with key key and value value if the field does not already exist in
the set. The field number of the new field is returned.
ns_set create
(which is the same as ns_set new) 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 ns_set free. If -persist is not specified, the new set is
automatically freed when the transaction ends.
ns_set delete
deletes the field in the set at field number fieldNumber.
ns_set delkey
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.
ns_set find
returns the index of the first field in the specified set whose key name matches the specified
key. Zero (0) is the index of the first field. If no matching fields are found, ns_set find
returns -1.
ns_set free
frees the specified set. Sets must be explicitly freed with ns_set free if the -persist option was
used when creating the set. Otherwise, sets are automatically freed when the transaction ends.
ns_set get
returns the first value associated with the passed-in key. If the key is invalid, an empty string
is returned.
ns_set icput
is the case-insensitive counterpart of ns_set cput.
ns_set idelkey
is the case-insensitive counterpart of ns_set delkey.
ns_set ifind
is the case-insensitive counterpart of ns_set find.
ns_set iget
is the case-insensitive counterpart of ns_set get.
ns_set isnull
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 for an empty string.
ns_set iunique
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. ns_set unique is the case-sensitive version of this
function.
For example, a client could send multiple "Accept:" headers which would end up in the header set
for the connection. ns_set iunique would return 0 for the "Accept:" key, because there are
multiple fields with the key "Accept:".
ns_set key
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.
ns_set merge
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.
ns_set move
moves all fields from the from set to the end of the to set, leaving the from set a valid, empty
set.
ns_set name
returns the name of the set.
ns_set new
(which is the same as ns_set create) 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 ns_set free. If -persist is not specified, the new set is
automatically freed when the transaction ends.
ns_set print
prints the specified set to stderr.
ns_set put
appends a new field to the set with key key and value value. 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.
ns_set size
returns the number of key-value pairs in the set.
ns_set split
splits one set into multiple sets based on the splitChar as described below and returns a Tcl list
of the newly-allocated sets. It assumes that the keys in the specified set (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 (.).
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, ns_set split 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!".
ns_set truncate
reduces the set to the first size key-value pairs and frees the memory for the rest of the key-
value pairs that may have been in the set.
ns_set unique
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. ns_set iunique is the case-insensitive version of this
function.
ns_set update
updates the first field in the specified set whose key is key and replaces its value with value.
ns_set update is equivalent to ns_set delkey followed by ns_set put.
ns_set value
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.
NOTES
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.
KEYWORDS
key value