---
name: "ns_set"
section: "3aolserver"
platform: "linux"
package: "aolserver4-dev"
version: "4.5.1-18.1"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/ns_set/3aolserver"
---

# ns\_set(3aolserver)

commands

```

```

## 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