From a46b1f79d3095b4e867148fee2cb94dfe84fab44 Mon Sep 17 00:00:00 2001 From: sebres Date: Tue, 10 Jan 2017 23:01:23 +0000 Subject: code review and inline documentation --- generic/tclClock.c | 262 +++++++++++++++++++++++++++++++++++++++++++++--- generic/tclClockFmt.c | 3 + generic/tclDate.h | 7 -- generic/tclDictObj.c | 32 +++++- generic/tclInt.h | 7 ++ generic/tclStrIdxTree.c | 3 +- 6 files changed, 288 insertions(+), 26 deletions(-) diff --git a/generic/tclClock.c b/generic/tclClock.c index a324b65..fc7c70c 100644 --- a/generic/tclClock.c +++ b/generic/tclClock.c @@ -167,7 +167,6 @@ static const struct ClockCommand clockCommands[] = { { "GetJulianDayFromEraYearWeekDay", ClockGetjuliandayfromerayearweekdayObjCmd }, { "ParseFormatArgs", ClockParseformatargsObjCmd }, - { "_test", TclStrIdxTreeTestObjCmd }, { NULL, NULL } }; @@ -262,10 +261,11 @@ TclClockInit( /* *---------------------------------------------------------------------- * - * ClockDeleteCmdProc -- + * ClockConfigureClear -- * - * Remove a reference to the clock client data, and clean up memory - * when it's all gone. + * Clean up cached resp. run-time storages used in clock commands. + * + * Shared usage for clean-up (ClockDeleteCmdProc) and "configure -clear". * * Results: * None. @@ -301,7 +301,20 @@ ClockConfigureClear( Tcl_UnsetObjRef(data->UTC2Local.tzName); Tcl_UnsetObjRef(data->Local2UTC.timezoneObj); } - + +/* + *---------------------------------------------------------------------- + * + * ClockDeleteCmdProc -- + * + * Remove a reference to the clock client data, and clean up memory + * when it's all gone. + * + * Results: + * None. + * + *---------------------------------------------------------------------- + */ static void ClockDeleteCmdProc( ClientData clientData) /* Opaque pointer to the client data */ @@ -335,7 +348,20 @@ ClockDeleteCmdProc( /* *---------------------------------------------------------------------- + * + * NormTimezoneObj -- + * + * Normalizes the timezone object (used for caching puposes). + * + * If already cached time zone could be found, returns this + * object (last setup or last used, system (current) or gmt). + * + * Results: + * Normalized tcl object pointer. + * + *---------------------------------------------------------------------- */ + static inline Tcl_Obj * NormTimezoneObj( ClockClientData *dataPtr, /* Client data containing literal pool */ @@ -411,9 +437,23 @@ ClockGetCurrentLocale( return dataPtr->CurrentLocale; } + /* *---------------------------------------------------------------------- + * + * NormLocaleObj -- + * + * Normalizes the locale object (used for caching puposes). + * + * If already cached locale could be found, returns this + * object (current, system (OS) or last used locales). + * + * Results: + * Normalized tcl object pointer. + * + *---------------------------------------------------------------------- */ + static Tcl_Obj * NormLocaleObj( ClockClientData *dataPtr, /* Client data containing literal pool */ @@ -494,7 +534,21 @@ NormLocaleObj( /* *---------------------------------------------------------------------- + * + * ClockMCDict -- + * + * Retrieves a localized storage dictionary object for the given + * locale object. + * + * This corresponds with call `::tcl::clock::mcget locale`. + * Cached representation stored in options (for further access). + * + * Results: + * Tcl-object contains smart reference to msgcat dictionary. + * + *---------------------------------------------------------------------- */ + MODULE_SCOPE Tcl_Obj * ClockMCDict(ClockFmtScnCmdArgs *opts) { @@ -560,6 +614,21 @@ ClockMCDict(ClockFmtScnCmdArgs *opts) return opts->mcDictObj; } +/* + *---------------------------------------------------------------------- + * + * ClockMCGet -- + * + * Retrieves a msgcat value for the given literal integer mcKey + * from localized storage (corresponding given locale object) + * by mcLiterals[mcKey] (e. g. MONTHS_FULL). + * + * Results: + * Tcl-object contains localized value. + * + *---------------------------------------------------------------------- + */ + MODULE_SCOPE Tcl_Obj * ClockMCGet( ClockFmtScnCmdArgs *opts, @@ -581,6 +650,21 @@ ClockMCGet( return valObj; /* or NULL in obscure case if Tcl_DictObjGet failed */ } +/* + *---------------------------------------------------------------------- + * + * ClockMCGetIdx -- + * + * Retrieves an indexed msgcat value for the given literal integer mcKey + * from localized storage (corresponding given locale object) + * by mcLitIdxs[mcKey] (e. g. _IDX_MONTHS_FULL). + * + * Results: + * Tcl-object contains localized indexed value. + * + *---------------------------------------------------------------------- + */ + MODULE_SCOPE Tcl_Obj * ClockMCGetIdx( ClockFmtScnCmdArgs *opts, @@ -609,6 +693,21 @@ ClockMCGetIdx( return valObj; } + +/* + *---------------------------------------------------------------------- + * + * ClockMCSetIdx -- + * + * Sets an indexed msgcat value for the given literal integer mcKey + * in localized storage (corresponding given locale object) + * by mcLitIdxs[mcKey] (e. g. _IDX_MONTHS_FULL). + * + * Results: + * Returns a standard Tcl result. + * + *---------------------------------------------------------------------- + */ MODULE_SCOPE int ClockMCSetIdx( @@ -639,7 +738,23 @@ ClockMCSetIdx( /* *---------------------------------------------------------------------- + * + * ClockConfigureObjCmd -- + * + * This function is invoked to process the Tcl "clock configure" command. + * + * Usage: + * ::tcl::clock::configure ?-option ?value?? + * + * Results: + * Returns a standard Tcl result. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- */ + static int ClockConfigureObjCmd( ClientData clientData, /* Client data containing literal pool */ @@ -781,7 +896,20 @@ ClockConfigureObjCmd( /* *---------------------------------------------------------------------- + * + * ClockGetTZData -- + * + * Retrieves tzdata table for given normalized timezone. + * + * Results: + * Returns a tcl object with tzdata. + * + * Side effects: + * The tzdata can be cached in ClockClientData structure. + * + *---------------------------------------------------------------------- */ + static inline Tcl_Obj * ClockGetTZData( ClientData clientData, /* Opaque pointer to literal pool, etc. */ @@ -839,9 +967,20 @@ ClockGetTZData( } return ret; } + /* *---------------------------------------------------------------------- + * + * ClockGetSystemTimeZone -- + * + * Returns system (current) timezone. + * + * Results: + * Returns normalized timezone object. + * + *---------------------------------------------------------------------- */ + static Tcl_Obj * ClockGetSystemTimeZone( ClientData clientData, /* Opaque pointer to literal pool, etc. */ @@ -869,9 +1008,20 @@ ClockGetSystemTimeZone( } return dataPtr->SystemTimeZone; } + /* *---------------------------------------------------------------------- + * + * ClockSetupTimeZone -- + * + * Sets up the timezone. Loads tzdata, etc. + * + * Results: + * Returns normalized timezone object. + * + *---------------------------------------------------------------------- */ + MODULE_SCOPE Tcl_Obj * ClockSetupTimeZone( ClientData clientData, /* Opaque pointer to literal pool, etc. */ @@ -908,20 +1058,22 @@ ClockSetupTimeZone( } return NULL; } + /* *---------------------------------------------------------------------- - * ClockFormatNumericTimeZone - * - * Formats a time zone as +hhmmss + * ClockFormatNumericTimeZone -- + * + * Formats a time zone as +hhmmss * * Parameters: - * z - Time zone in seconds east of Greenwich + * z - Time zone in seconds east of Greenwich * * Results: - * Returns the time zone object (formatted in a numeric form) + * Returns the time zone object (formatted in a numeric form) * * Side effects: - * None. + * None. * *---------------------------------------------------------------------- */ @@ -943,6 +1095,7 @@ ClockFormatNumericTimeZone(int z) { } return Tcl_ObjPrintf("%c%02d%02d", sign, h, m); } + /* *---------------------------------------------------------------------- * @@ -1145,7 +1298,20 @@ ClockGetdatefieldsObjCmd( /* *---------------------------------------------------------------------- + * + * ClockGetDateFields -- + * + * Converts given UTC time (seconds in a TclDateFields structure) + * to local time and determines the values that clock routines will + * use in scanning or formatting a date. + * + * Results: + * Date-time values are stored in structure "fields". + * Returns a standard Tcl result. + * + *---------------------------------------------------------------------- */ + int ClockGetDateFields( ClientData clientData, /* Client data of the interpreter */ @@ -1586,6 +1752,7 @@ ConvertLocalToUTCUsingTable( fields->seconds = fields->localSeconds - fields->tzOffset; #if 0 + /* currently unused, test purposes only */ /* * Convert back from UTC, if local times are different - wrong local time * (local time seems to be in between DST-hole). @@ -2404,9 +2571,24 @@ GetJulianDayFromEraYearMonthDay( + ym1o4; } } + /* *---------------------------------------------------------------------- + * + * GetJulianDayFromEraYearDay -- + * + * Given era, year, and dayOfYear (in TclDateFields), and the + * Gregorian transition date, computes the Julian Day Number. + * + * Results: + * None. + * + * Side effects: + * Stores day number in 'julianDay' + * + *---------------------------------------------------------------------- */ + MODULE_SCOPE void GetJulianDayFromEraYearDay( @@ -2740,6 +2922,19 @@ ClockMicrosecondsObjCmd( return TCL_OK; } +/* + *----------------------------------------------------------------------------- + * + * _ClockParseFmtScnArgs -- + * + * Parses the arguments for [clock scan] and [clock format]. + * + * Results: + * Returns a standard Tcl result, and stores parsed options + * (format, the locale, timezone and base) in structure "opts". + * + *----------------------------------------------------------------------------- + */ static int _ClockParseFmtScnArgs( @@ -2853,9 +3048,7 @@ _ClockParseFmtScnArgs( * Returns a standard Tcl result, whose value is a four-element list * comprising the time format, the locale, and the timezone. * - * This function exists because the loop that parses the [clock format] - * options is a known performance "hot spot", and is implemented in an effort - * to speed that particular code up. + * This function exists for backward compatibility purposes. * *----------------------------------------------------------------------------- */ @@ -2919,7 +3112,20 @@ ClockParseformatargsObjCmd( /*---------------------------------------------------------------------- * - * ClockFormatObjCmd - + * ClockFormatObjCmd -- , clock format -- + * + * This function is invoked to process the Tcl "clock format" command. + * + * Formats a count of seconds since the Posix Epoch as a time of day. + * + * The 'clock format' command formats times of day for output. Refer + * to the user documentation to see what it does. + * + * Results: + * Returns a standard Tcl result. + * + * Side effects: + * None. * *---------------------------------------------------------------------- */ @@ -3018,7 +3224,20 @@ done: /*---------------------------------------------------------------------- * - * ClockScanObjCmd - + * ClockScanObjCmd -- , clock scan -- + * + * This function is invoked to process the Tcl "clock scan" command. + * + * Inputs a count of seconds since the Posix Epoch as a time of day. + * + * The 'clock scan' command scans times of day on input. Refer to the + * user documentation to see what it does. + * + * Results: + * Returns a standard Tcl result. + * + * Side effects: + * None. * *---------------------------------------------------------------------- */ @@ -3188,7 +3407,20 @@ done: } /*---------------------------------------------------------------------- + * + * ClockFreeScan -- + * + * Used by ClockScanObjCmd for free scanning without format. + * + * Results: + * Returns a standard Tcl result. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- */ + int ClockFreeScan( ClientData clientData, /* Client data containing literal pool */ diff --git a/generic/tclClockFmt.c b/generic/tclClockFmt.c index 24c0f1d..ff16714 100644 --- a/generic/tclClockFmt.c +++ b/generic/tclClockFmt.c @@ -881,6 +881,7 @@ ObjListSearch(ClockFmtScnCmdArgs *opts, return TCL_RETURN; } #if 0 +/* currently unused */ static int LocaleListSearch(ClockFmtScnCmdArgs *opts, @@ -1042,6 +1043,7 @@ ClockStrIdxTreeSearch(ClockFmtScnCmdArgs *opts, return TCL_OK; } #if 0 +/* currently unused */ static int StaticListSearch(ClockFmtScnCmdArgs *opts, @@ -1093,6 +1095,7 @@ ClockScnToken_Month_Proc(ClockFmtScnCmdArgs *opts, DateInfo *info, ClockScanToken *tok) { #if 0 +/* currently unused, test purposes only */ static const char * months[] = { /* full */ "January", "February", "March", diff --git a/generic/tclDate.h b/generic/tclDate.h index cf307a6..1519842 100644 --- a/generic/tclDate.h +++ b/generic/tclDate.h @@ -509,11 +509,4 @@ MODULE_SCOPE int ClockFormat(register DateFormat *dateFmt, MODULE_SCOPE void ClockFrmScnClearCaches(void); -/* - * Other externals. - */ - -MODULE_SCOPE unsigned long TclEnvEpoch; /* Epoch of the tcl environment - * (if changed with tcl-env). */ - #endif /* _TCLCLOCK_H */ diff --git a/generic/tclDictObj.c b/generic/tclDictObj.c index caebbf1..b786c4f 100644 --- a/generic/tclDictObj.c +++ b/generic/tclDictObj.c @@ -1960,6 +1960,32 @@ DictSizeCmd( /* *---------------------------------------------------------------------- + * + * Tcl_DictObjSmartRef -- + * + * This function returns new tcl-object with the smart reference to + * dictionary object. + * + * Object returned with this function is a smart reference (pointer), + * so new object of type tclDictType, that directly references given + * dictionary object (with internally increased refCount). + * + * The usage of such pointer objects allows to hold more as one + * reference to the same real dictionary object, allows to make a pointer + * to part of another dictionary, allows to change the dictionary without + * regarding of the "shared" state of the dictionary object. + * + * Prevents "called with shared object" exception if object is multiple + * referenced. + * + * Results: + * The newly create object (contains smart reference) is returned. + * The returned object has a ref count of 0. + * + * Side effects: + * Increases ref count of the referenced dictionary. + * + *---------------------------------------------------------------------- */ Tcl_Obj * @@ -1991,9 +2017,9 @@ Tcl_DictObjSmartRef( * * DictSmartRefCmd -- * - * This function implements the "dict smartref" Tcl command. See the user - * documentation for details on what it does, and TIP#111 for the formal - * specification. + * This function implements the "dict smartref" Tcl command. + * + * See description of Tcl_DictObjSmartRef for details. * * Results: * A standard Tcl result. diff --git a/generic/tclInt.h b/generic/tclInt.h index a569788..15cb355 100644 --- a/generic/tclInt.h +++ b/generic/tclInt.h @@ -4886,6 +4886,13 @@ typedef struct NRE_callback { #define Tcl_Free(ptr) TclpFree(ptr) #endif +/* + * Other externals. + */ + +MODULE_SCOPE unsigned long TclEnvEpoch; /* Epoch of the tcl environment + * (if changed with tcl-env). */ + #endif /* _TCLINT */ /* diff --git a/generic/tclStrIdxTree.c b/generic/tclStrIdxTree.c index 686c1e4..773eb6a 100644 --- a/generic/tclStrIdxTree.c +++ b/generic/tclStrIdxTree.c @@ -418,7 +418,8 @@ TclStrIdxTreeGetFromObj(Tcl_Obj *objPtr) { /* * Several debug primitives */ -#if 1 +#if 0 +/* currently unused, debug resp. test purposes only */ void TclStrIdxTreePrint( -- cgit v0.12