TutTimeCvtCreate

Name

TutTimeCvtCreate — create a time converter

Synopsis

T_TIME_CVT TutTimeCvtCreate(name, num_to_str_func, str_to_num_func, 
                            destroy_func) 
T_STR name; 
T_TIME_CVT_NUM_TO_STR_FUNC num_to_str_func; 
T_TIME_CVT_STR_TO_NUM_FUNC str_to_num_func; 
T_TIME_CVT_DESTROY_FUNC destroy_func; 

Arguments

name — name of new time converter (not case sensitive)

num_to_str_func — function to convert numeric time value to a string

str_to_num_func — function to convert string time value to a number

destroy_func — optional function to be called if time converter is destroyed. This argument may be null.

Return Values

Returns pointer to new time converter, NULL if a converter with the same name already exists.

Diagnostics

None

Description

TutTimeCvtCreate creates a new SmartSockets time converter. A time converter consists of a name, a number-to-string function, a string-to-number function, and a destroy function.

Time converters are used by SmartSockets to convert time values that are stored as floating-point numbers into strings that can be more easily interpreted. For example, the current SmartSockets system time, as returned by TutGetCurrentTime, can be a large number such as 695520549.321. This number is almost useless unless it can be converted to a more meaningful string, such as Fri Mar 27 16:09:09.321 1998. Time converters provide this mechanism and also allow you to customize the printed format of the time value. Time converters are used throughout SmartSockets. For example, this conversion function is used when you are asked to enter a time, such as in the run until time command.

The number-to-string function num_to_str_func must be written to take two arguments: the numeric time value and an address where it places the string value. The num_to_str_func is responsible for converting the time value from a number to a string and storing a pointer to the string in time_str_return.

The num_to_str_func is also responsible for managing the storage for the string. A num_to_str_func should allocate enough string storage the first time it is called and then reuse that storage in subsequent calls. The num_to_str_func should not allocate a new string every time it is called. Alternatively, the num_to_str_func could declare a static string and choose to use that static storage every time.

The num_to_str_func returns TRUE if it successfully converted the number to a string, which is almost always the case, or FALSE if it could not do so. Some time converters may not treat all numeric values as valid time values.

The string to number function str_to_num_func is just the inverse of the number to string function. It must be written to take two arguments: the time string and an address where it places the numeric time value. Unlike the num_to_str_func, the str_to_num_func does not have to explicitly manage any storage. The str_to_num_func may choose to accept many different time string formats. The str_to_num_func returns TRUE if it successfully converted the string to a number, or FALSE if it could not do so. For example, a str_to_num_func expecting a string of the format HH:MM:SS is probably not going to understand the string yesterday. A str_to_num_func that understands DAY MMM DD HH:MM:SS.FF YYYY may also choose to understand MMM DDD HH:MM:SS.FF for ease of use. It is entirely up to the writer of the time converter to decide what string formats to accept.

Once a time converter has been created, it can be called with TutTimeCvtNumToStr to convert numeric time values to strings, and with TutTimeCvtStrToNum to convert string time values to numbers.

Write the optional destroy function destroy_func to do any cleanup necessary when the time converter is destroyed, such as freeing the string storage that was allocated. Time converters are normally not destroyed, but it is possible to destroy them if it is desirable to remove a time converter, making it unavailable for use. If a time converter is destroyed with TutTimeCvtDestroy, the destroy_func is called with no arguments. If destroy_func is not needed, specify it as NULL in the call to TutTimeCvtCreate.

SmartSockets has these standard converters:

There is a close relationship between time converters and the SmartSockets option Time_Format. The convenience function TutTimeNumToStr uses the value of the Time_Format option to determine which time converter to use, and then calls TutTimeCvtNumToStr using the appropriate converter. Therefore it is normally unnecessary to call TutTimeCvtNumToStr. By using TutTimeNumToStr instead, you can customize the printing of time by simply setting the Time_Format option.

The same relationship is true for TutTimeCvtStrToNum and TutTimeStrToNum. TutTimeStrToNum is a convenience function that should almost always be used instead of TutTimeCvtStrToNum.

Caution

SmartSockets time converter names are not case sensitive (FULL, full, and Full all refer to the same time converter).

See Also

TutTimeCvtNumToStr, TutTimeCvtDestroy, TutTimeCvtLookup, TutTimeStrToNum, TutTimeNumToStr

Examples

This example is a time converter named percentf that is similar to numeric, but always uses the %f printf conversion format (numeric uses the format specified in the option Real_Number_Format):

/* ============================================================== */ 
/*..utTimeCvtPercentfNumToStr -- convert time to plain number */ 
static T_BOOL T_ENTRY utTimeCvtPercentfNumToStr(time_val, 
time_str_return) 
T_REAL8 time_val;        /* time to be converted */ 
T_STR *time_str_return;  /* address of string */ 
{ 
  static T_CHAR time_str[80]; 
 
  sprintf(time_str, "%f", time_val); 
  *time_str_return = time_str; 
  return TRUE;           /* number successfully converted to string */ 
} /* utTimeCvtPercentfNumToStr */ 
 
/* ============================================================== */ 
/*..utTimeCvtPercentfStrToNum -- convert string to numeric time */ 
static T_BOOL T_ENTRY utTimeCvtPercentfStrToNum(time_str, 
time_val_return) 
T_STR time_str; 
T_REAL8 *time_val_return; 
{ 
  if (sscanf(time_str, "%lf", time_val_return) == 1) { 
    return TRUE;   /* successfully converted to number */ 
  }  
  else { 
    return FALSE;  /* conversion failed */ 
  }  
} /* utTimeCvtPercentfStrToNum */ 
 

Because this converter uses static storage for its string, it does not need a destroy_func.

This code registers the time converter:

if (T_NULL == TutTimeCvtCreate("percentf", 
utTimeCvtPercentfNumToStr, 
utTimeCvtPercentfStrToNum, T_NULL_FUNC)) { 
  /* error */ 
}