TutTimeCvtTraverse

Name

TutTimeCvtTraverse — traverse all time converters

Synopsis

T_PTR TutTimeCvtTraverse(traverse_func, traverse_arg) 
T_TIME_CVT_TRAV_FUNC traverse_func; 
T_PTR traverse_arg; 

Arguments

traverse_func — function to call once for each converter

traverse_arg — argument to pass to traverse_arg

Return Values

The first non-null return value from traverse_func, or NULL if traverse_func always returns NULL.

Diagnostics

None

Description

TutTimeCvtTraverse traverses all time converters and calls traverse_func once for each converter. The traverse_func function is called with three arguments: the converter name, the converter, and the traverse_arg that TutTimeCvtTraverse was called with. When traverse_func returns a non-null value, then TutTimeCvtTraverse returns with that value.

There are two common uses for TutTimeCvtTraverse: to perform an operation on each converter and to search for a particular converter. In the first case, write traverse_func to always return NULL. In the second case, traverse_func should return NULL until it finds the desired converter and then return some kind of non-null value (such as the converter).

Caution

Be careful to always return a value from traverse_func.

The order that the converters traverse in is not controllable.

See Also

TutTimeCvtLookup

Examples

This example is a simple traversal function that prints the name of each time converter.

T_PTR print_name(name, converter, dummy_arg) 
T_STR name; 
T_TIME_CVT converter; 
T_PTR dummy_arg; /* not used */ 
{ 
  TutOut("Converter name is %s.\n", name); 
  return NULL;   /* continue traversal */ 
} /* print_name */ 
 

To call this function, this code could be used:

(void)TutTimeCvtTraverse(print_name, NULL); /* no real traverse_arg */ 

This example is a traversal function that counts the number of converters:

T_PTR count_converters(name, converter, counter_ptr) 
T_STR name; 
T_TIME_CVT converter; 
T_PTR counter_ptr; 
{ 
  T_INT4 *cnt_ptr = (T_INT4 *)counter_ptr;  
  (*counter_ptr)++;   /* increment our counter */ 
   return NULL;       /* continue traversal */ 
} /* count_converters */ 
 

To call this function, this code could be used:

T_INT4 counter = 0; 
(void)TutTimeCvtTraverse(count_converters, (T_PTR)&counter); 
TutOut("There are %d time converters.\n", counter);