Tcl_GetKeyedListKeys(3Tcl)Tcl_GetKeyedListKeys(3Tcl)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.
Page 1
Tcl_GetKeyedListKeys(3Tcl)Tcl_GetKeyedListKeys(3Tcl)
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.
Page 2
