NAME

Tcl_GetKeyedListKeys, Tcl_GetKeyedListField, Tcl_SetKeyedListField, Tcl_DeleteKeyedListField - Keyed list management routines. 

SYNOPSIS

#include <tclExtend.h>
 int
Tcl_GetKeyedListKeys (Tcl_Interp  ∗interp,
                      const char  ∗subFieldName,
                      const char  ∗keyedList,
                      int         ∗keyesArgcPtr,
                      char      ∗∗∗keyesArgvPtr);
 int
Tcl_GetKeyedListField (Tcl_Interp  ∗interp,
                       const char  ∗fieldName,
                       const char  ∗keyedList,
                       char       ∗∗fieldValuePtr);
 char ∗
Tcl_SetKeyedListField (Tcl_Interp  ∗interp,
                       const char  ∗fieldName,
                       const char  ∗fieldvalue,
                       const char  ∗keyedList);
 char ∗
Tcl_DeleteKeyedListField (Tcl_Interp  ∗interp,
                          const char  ∗fieldName,
                          const char  ∗keyedList);

DESCRIPTION

These routines perform operations on keyed lists.  See the Extended Tcl man page for a description of keyed lists. 

Tcl_GetKeyedListKeys

Retrieve a list of keyes from a keyed list.  The list is walked rather than converted to a argv for increased performance. 

Parameters:

o interp - Error message will be return in result if there is an error. 
o subFieldName - If "" or NULL, then the keys are retreved for the top level of the list.  If specified, it is name of the field who’s subfield keys are to be retrieve. 
o keyedList - The list to search for the field. 
o keyesArgcPtr - The number of keys in the keyed list is returned here. 
o keyesArgvPtr - An argv containing the key names.  It is dynamically allocated, containing both the array and the strings. A single call to ckfree will release it. 

Returns:

TCL_OK if a list of keys is returned, TCL_BREAK if the field was not found, or TCL_ERROR if an error occured. 

Tcl_GetKeyedListField

Retrieve a field value from a keyed list.  The list is walked rather than converted to a argv for increased performance.  This if the name contains sub-fields, this function recursive. 

Parameters:

o interp - Error message will be return in result if there is an error. 
o fieldName - The name of the field to extract.  Will recusively process sub-field names seperated by ‘.’. 
o keyedList - The list to search for the field. 
o fieldValuePtr - If the field is found, a pointer to a dynamicly allocated string containing the value is returned here.  If NULL is specified, then only the presence of the field is validated, the value is not returned. 

Returns:

TCL_OK if the field was found,  TCL_BREAK if the field was not found or TCL_ERROR if an error occured. 

Tcl_SetKeyedListField

Set a field value in keyed list. 

Parameters:

o interp - Error message will be return in result if there is an error. 
o fieldName - The name of the field to extract.  Will recusively process sub-field names seperated by ‘.’. 
o fieldValue - The value to set for the field. 
o keyedList - The keyed list to set a field value in, may be an NULL or an empty list to create a new keyed list. 

Returns:

A pointer to a dynamically allocated string, or NULL if an error occured. 

Tcl_DeleteKeyedListField

Delete a field value in keyed list. 

Parameters:

o interp - Error message will be return in result if there is an error. 
o fieldName - The name of the field to extract.  Will recusively process sub-field names seperated by ‘.’. 
o fieldValue - The value to set for the field. 
o keyedList - The keyed list to delete the field from. 

Returns:

A pointer to a dynamically allocated string containing the new list, or NULL if an error occured. 

Tcl  —