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