nstcl  >  Documentation  >  nstcl-nssets  >  ns_set

Tcl Powered!

ns_set

NAME

ns_set — Manipulate sets of key/value pairs

SYNOPSIS

package require nstcl-nssets ?1.0?
package require nstcl ?1.0?

::nstcl::ns_set option arg ?...?

DESCRIPTION

This command manipulates sets of key/value pairs.

ns_set copy ?-persist? setId
Returns a new set that has the same name and key/value pairs as the given setId. Since nstcl has no concept of a "transaction" or "connection" -persist is a no-op, and is included strictly for source compatability.

 
ns_set cput setId key value
Conditionally appends a new field to the setId set if a field with the same key does not already exist in the set. Returns the field number of the new field (if added), or the field number of the existing key.

 
ns_set create ?-persist? name
Creates a new set and returns the setId. Since nstcl has no concept of a "transaction" or "connection" -persist is a no-op, and is included strictly for source compatability.

 
ns_set delete setId fieldNumber
Deletes field number fieldNumber from the setId set.

 
ns_set delkey setId key
Delete the first occurence (only) of key in the setId set. If the key does not exist the contents of setId are not changed, and no error is raised.

 
ns_set find setId key
Searches the setId set and returns the field number of the first instance of key. Fields are numbered beginning at position 0 (like list indexes in Tcl). If an instance of key is not found then -1 is returned.

 
ns_set free setId
Deletes the setId set (thus freeing the memory used). nstcl never explicitly frees sets (like AOLserver does) since nstcl does not have any notion of a "transaction". All sets persist until explicity freed.

 
ns_set get setId key
Returns the value of the first instance of key in the setId set. If key is not contained in the setId set an empty string is returned.

 
ns_set icput setId key value
Case-insensitive version of cput.

 
ns_set idelkey setId key
Case-insensitive version of delkey.

 
ns_set ifind setId key
Case-insensitive version of find.

 
ns_set iget setId key
Case-insensitive version of get.

 
ns_set isnull setId fieldNumber
Returns a 0 or a 1 depending on whether fieldNumber in the setId set is null. The empty string is not considered to be a null value, nor is the string with an ascii value of 0. This command is included for compatability with AOLserver only (whose Tcl API has no way to set a field to be null). Hence, the nstcl version of this command will always return 0.

 
ns_set iunique setId key
Case-insensitive version of unique

 
ns_set key setId fieldNumber
Returns the name of the fieldNumber key in the setId set. Sets are indexed beginning at position 0.

 
ns_set merge high low
Any key/value pairs from the low set are appended to the high set if the same key does not already exist in the high set. The low set is not modified in any way.

 
ns_set move to from
Moves all the key/value pairs from from to to, leaving from as a valid (but completely empty) set.

 
ns_set name setId
Returns the name of the setId set.

 
ns_set new ?-persist? name
Synonym for create

 
ns_set print setId
Pretty print the key/value pairs in the setId set (similar to Tcl's parray command for arrays). The AOLserver version of this command "prints" to the server log; the nstcl version returns a string.

 
ns_set put setId key value
Appends a new key/value pair to the setId set and returns the new field number.

 
ns_set size setId
Returns the number of key/value pairs in the setId set.

 
ns_set split ?-persist? setId ?splitChar?
Splits one set into multiple new sets based on the splitChar, and returns a Tcl list of the newly-allocated sets. The default splitChar, if not specified, is a period (.).

From the AOLserver documentation:
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!".

The -persist is a no-op in nstcl.

 
ns_set truncate setId size
Trunaces the setId set to the specified size and frees the memory used by the truncated key/value pairs.

 
ns_set unique setId key
Returns a 1 if the specified key is unique within the setId set, and 0 otherwise.

 
ns_set update setId key value
Updates the first instance of key in the setId set with a new value, or appends the key/value pair if key does not already exist within the setId set.

 
ns_set value setId fieldNumber
Returns the value of the fieldNumber key in the setId set. Sets are indexed beginning at position 0.

KEYWORDS

nssets, nstcl