summaryrefslogtreecommitdiffstats
path: root/generic
diff options
context:
space:
mode:
authorsebres <sebres@users.sourceforge.net>2017-01-11 16:36:28 (GMT)
committersebres <sebres@users.sourceforge.net>2017-01-11 16:36:28 (GMT)
commitb2190d273f42dc51a6455279afdf00695c45c12b (patch)
tree1ee500850aa1cc85a543afe3024c76f77d769d60 /generic
parent0be426fec21fe7b763b7486ec2c6d11d17fb19e3 (diff)
downloadtcl-b2190d273f42dc51a6455279afdf00695c45c12b.zip
tcl-b2190d273f42dc51a6455279afdf00695c45c12b.tar.gz
tcl-b2190d273f42dc51a6455279afdf00695c45c12b.tar.bz2
code review and inline documentation
Diffstat (limited to 'generic')
-rw-r--r--generic/tclClock.c27
-rw-r--r--generic/tclClockFmt.c323
2 files changed, 323 insertions, 27 deletions
diff --git a/generic/tclClock.c b/generic/tclClock.c
index efa9120..c63f425 100644
--- a/generic/tclClock.c
+++ b/generic/tclClock.c
@@ -412,7 +412,19 @@ NormTimezoneObj(
/*
*----------------------------------------------------------------------
+ *
+ * ClockGetSystemLocale --
+ *
+ * Returns system locale.
+ *
+ * Executes ::tcl::clock::GetSystemLocale in given interpreter.
+ *
+ * Results:
+ * Returns system locale tcl object.
+ *
+ *----------------------------------------------------------------------
*/
+
static inline Tcl_Obj *
ClockGetSystemLocale(
ClockClientData *dataPtr, /* Opaque pointer to literal pool, etc. */
@@ -426,7 +438,19 @@ ClockGetSystemLocale(
}
/*
*----------------------------------------------------------------------
+ *
+ * ClockGetCurrentLocale --
+ *
+ * Returns current locale.
+ *
+ * Executes ::tcl::clock::mclocale in given interpreter.
+ *
+ * Results:
+ * Returns current locale tcl object.
+ *
+ *----------------------------------------------------------------------
*/
+
static inline Tcl_Obj *
ClockGetCurrentLocale(
ClockClientData *dataPtr, /* Client data containing literal pool */
@@ -978,6 +1002,9 @@ ClockGetTZData(
*
* Returns system (current) timezone.
*
+ * If system zone not yet cached, it executes ::tcl::clock::GetSystemTimeZone
+ * in given interpreter and caches its result.
+ *
* Results:
* Returns normalized timezone object.
*
diff --git a/generic/tclClockFmt.c b/generic/tclClockFmt.c
index ff16714..d875bd4 100644
--- a/generic/tclClockFmt.c
+++ b/generic/tclClockFmt.c
@@ -41,6 +41,24 @@ CLOCK_LOCALE_LITERAL_ARRAY(MsgCtLitIdxs, "_IDX_");
* Clock scan and format facilities.
*/
+/*
+ *----------------------------------------------------------------------
+ *
+ * _str2int -- , _str2wideInt --
+ *
+ * Fast inline-convertion of string to signed int or wide int by given
+ * start/end.
+ *
+ * The given string should contain numbers chars only (because already
+ * pre-validated within parsing routines)
+ *
+ * Results:
+ * Returns a standard Tcl result.
+ * TCL_OK - by successful conversion, TCL_ERROR by (wide) int overflow
+ *
+ *----------------------------------------------------------------------
+ */
+
static inline int
_str2int(
int *out,
@@ -101,6 +119,22 @@ _str2wideInt(
return TCL_OK;
}
+/*
+ *----------------------------------------------------------------------
+ *
+ * _itoaw -- , _witoaw --
+ *
+ * Fast inline-convertion of signed int or wide int to string, using
+ * given padding with specified padchar and width (or without padding).
+ *
+ * This is a very fast replacement for sprintf("%02d").
+ *
+ * Results:
+ * Returns position in buffer after end of conversion result.
+ *
+ *----------------------------------------------------------------------
+ */
+
static inline char *
_itoaw(
char *buf,
@@ -257,7 +291,15 @@ _witoaw(
}
/*
- *----------------------------------------------------------------------
+ * Global GC as LIFO for released scan/format object storages.
+ *
+ * Used to holds last released CLOCK_FMT_SCN_STORAGE_GC_SIZE formats
+ * (after last reference from Tcl-object will be removed). This is helpful
+ * to avoid continuous (re)creation and compiling by some dynamically resp.
+ * variable format objects, that could be often reused.
+ *
+ * As long as format storage is used resp. belongs to GC, it takes place in
+ * FmtScnHashTable also.
*/
#if CLOCK_FMT_SCN_STORAGE_GC_SIZE > 0
@@ -268,6 +310,24 @@ static struct {
unsigned int count;
} ClockFmtScnStorage_GC = {NULL, NULL, 0};
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockFmtScnStorageGC_In --
+ *
+ * Adds an format storage object to GC.
+ *
+ * If current GC is full (size larger as CLOCK_FMT_SCN_STORAGE_GC_SIZE)
+ * this removes last unused storage at begin of GC stack (LIFO).
+ *
+ * Assumes caller holds the ClockFmtMutex.
+ *
+ * Results:
+ * None.
+ *
+ *----------------------------------------------------------------------
+ */
+
static inline void
ClockFmtScnStorageGC_In(ClockFmtScnStorage *entry)
{
@@ -291,6 +351,22 @@ ClockFmtScnStorageGC_In(ClockFmtScnStorage *entry)
ClockFmtScnStorageDelete(delEnt);
}
}
+
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockFmtScnStorage_GC_Out --
+ *
+ * Restores (for reusing) given format storage object from GC.
+ *
+ * Assumes caller holds the ClockFmtMutex.
+ *
+ * Results:
+ * None.
+ *
+ *----------------------------------------------------------------------
+ */
+
static inline void
ClockFmtScnStorage_GC_Out(ClockFmtScnStorage *entry)
{
@@ -304,13 +380,19 @@ ClockFmtScnStorage_GC_Out(ClockFmtScnStorage *entry)
#endif
+
/*
- *----------------------------------------------------------------------
+ * Global format storage hash table of type ClockFmtScnStorageHashKeyType
+ * (contains list of scan/format object storages, shared across all threads).
+ *
+ * Used for fast searching by format string.
*/
-
static Tcl_HashTable FmtScnHashTable;
static int initialized = 0;
+/*
+ * Wrappers between pointers to hash entry and format storage object
+ */
static inline Tcl_HashEntry *
HashEntry4FmtScn(ClockFmtScnStorage *fss) {
return (Tcl_HashEntry*)(fss + 1);
@@ -320,8 +402,18 @@ FmtScn4HashEntry(Tcl_HashEntry *hKeyPtr) {
return (ClockFmtScnStorage*)(((char*)hKeyPtr) - sizeof(ClockFmtScnStorage));
};
-/*
- * Format storage hash (list of formats shared across all threads).
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockFmtScnStorageAllocProc --
+ *
+ * Allocate space for a hash entry containing format storage together
+ * with the string key.
+ *
+ * Results:
+ * The return value is a pointer to the created entry.
+ *
+ *----------------------------------------------------------------------
*/
static Tcl_HashEntry *
@@ -353,6 +445,19 @@ ClockFmtScnStorageAllocProc(
return hPtr;
}
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockFmtScnStorageFreeProc --
+ *
+ * Free format storage object and space of given hash entry.
+ *
+ * Results:
+ * None.
+ *
+ *----------------------------------------------------------------------
+ */
+
static void
ClockFmtScnStorageFreeProc(
Tcl_HashEntry *hPtr)
@@ -373,6 +478,19 @@ ClockFmtScnStorageFreeProc(
ckfree(fss);
}
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockFmtScnStorageDelete --
+ *
+ * Delete format storage object.
+ *
+ * Results:
+ * None.
+ *
+ *----------------------------------------------------------------------
+ */
+
static void
ClockFmtScnStorageDelete(ClockFmtScnStorage *fss) {
Tcl_HashEntry *hPtr = HashEntry4FmtScn(fss);
@@ -392,7 +510,7 @@ static Tcl_HashKeyType ClockFmtScnStorageHashKeyType;
/*
- * Type definition.
+ * Type definition of clock-format tcl object type.
*/
Tcl_ObjType ClockFmtObjType = {
@@ -409,9 +527,6 @@ Tcl_ObjType ClockFmtObjType = {
#define ObjLocFmtKey(objPtr) \
(*((Tcl_Obj **)&(objPtr)->internalRep.twoPtrValue.ptr2))
-/*
- *----------------------------------------------------------------------
- */
static void
ClockFmtObj_DupInternalRep(srcPtr, copyPtr)
Tcl_Obj *srcPtr;
@@ -442,9 +557,7 @@ ClockFmtObj_DupInternalRep(srcPtr, copyPtr)
copyPtr->length = srcPtr->length;
}
}
-/*
- *----------------------------------------------------------------------
- */
+
static void
ClockFmtObj_FreeInternalRep(objPtr)
Tcl_Obj *objPtr;
@@ -472,9 +585,7 @@ ClockFmtObj_FreeInternalRep(objPtr)
}
objPtr->typePtr = NULL;
};
-/*
- *----------------------------------------------------------------------
- */
+
static int
ClockFmtObj_SetFromAny(interp, objPtr)
Tcl_Interp *interp;
@@ -494,9 +605,7 @@ ClockFmtObj_SetFromAny(interp, objPtr)
return TCL_OK;
};
-/*
- *----------------------------------------------------------------------
- */
+
static void
ClockFmtObj_UpdateString(objPtr)
Tcl_Obj *objPtr;
@@ -518,7 +627,25 @@ ClockFmtObj_UpdateString(objPtr)
/*
*----------------------------------------------------------------------
+ *
+ * ClockFrmObjGetLocFmtKey --
+ *
+ * Retrieves format key object used to search localized format.
+ *
+ * This is normally stored in second pointer of internal representation.
+ * If format object is not localizable, it is equal the given format
+ * pointer and the first pointer of internal representation may be NULL.
+ *
+ * Results:
+ * Returns tcl object with key or format object if not localizable.
+ *
+ * Side effects:
+ * Converts given format object to ClockFmtObjType on demand for caching
+ * the key inside its internal representation.
+ *
+ *----------------------------------------------------------------------
*/
+
MODULE_SCOPE Tcl_Obj*
ClockFrmObjGetLocFmtKey(
Tcl_Interp *interp,
@@ -545,6 +672,25 @@ ClockFrmObjGetLocFmtKey(
/*
*----------------------------------------------------------------------
+ *
+ * FindOrCreateFmtScnStorage --
+ *
+ * Retrieves format storage for given string format.
+ *
+ * This will find the given format in the global storage hash table
+ * or create a format storage object on demaind and save the
+ * reference in the first pointer of internal representation of given
+ * object.
+ *
+ * Results:
+ * Returns scan/format storage pointer to ClockFmtScnStorage.
+ *
+ * Side effects:
+ * Converts given format object to ClockFmtObjType on demand for caching
+ * the format storage reference inside its internal representation.
+ * Increments objRefCount of the ClockFmtScnStorage reference.
+ *
+ *----------------------------------------------------------------------
*/
static ClockFmtScnStorage *
@@ -609,16 +755,16 @@ FindOrCreateFmtScnStorage(
*
* Tcl_GetClockFrmScnFromObj --
*
- * Returns a clock format/scan representation of (*objPtr), if possible.
- * If something goes wrong, NULL is returned, and if interp is non-NULL,
- * an error message is written there.
+ * Returns a clock format/scan representation of (*objPtr), if possible.
+ * If something goes wrong, NULL is returned, and if interp is non-NULL,
+ * an error message is written there.
*
* Results:
- * Valid representation of type ClockFmtScnStorage.
+ * Valid representation of type ClockFmtScnStorage.
*
* Side effects:
- * Caches the ClockFmtScnStorage reference as the internal rep of (*objPtr)
- * and in global hash table, shared across all threads.
+ * Caches the ClockFmtScnStorage reference as the internal rep of (*objPtr)
+ * and in global hash table, shared across all threads.
*
*----------------------------------------------------------------------
*/
@@ -644,7 +790,27 @@ Tcl_GetClockFrmScnFromObj(
return fss;
}
-
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockLocalizeFormat --
+ *
+ * Wrap the format object in options to the localized format,
+ * corresponding given locale.
+ *
+ * This searches localized format in locale catalog, and if not yet
+ * exists, it executes ::tcl::clock::LocalizeFormat in given interpreter
+ * and caches its result in the locale catalog.
+ *
+ * Results:
+ * Localized format object.
+ *
+ * Side effects:
+ * Caches the localized format inside locale catalog.
+ *
+ *----------------------------------------------------------------------
+ */
+
MODULE_SCOPE Tcl_Obj *
ClockLocalizeFormat(
ClockFmtScnCmdArgs *opts)
@@ -713,6 +879,22 @@ clean:
return (opts->formatObj = valObj);
}
+/*
+ *----------------------------------------------------------------------
+ *
+ * FindTokenBegin --
+ *
+ * Find begin of given scan token in string, corresponding token type.
+ *
+ * Results:
+ * Position of token inside string if found. Otherwise - end of string.
+ *
+ * Side effects:
+ * None.
+ *
+ *----------------------------------------------------------------------
+ */
+
static const char *
FindTokenBegin(
register const char *p,
@@ -748,12 +930,22 @@ FindTokenBegin(
return p;
}
-/*
+/*
+ *----------------------------------------------------------------------
+ *
* DetermineGreedySearchLen --
*
- * Determine min/max lengths as exact as possible (speed, greedy match)
+ * Determine min/max lengths as exact as possible (speed, greedy match).
*
+ * Results:
+ * None. Lengths are stored in *minLenPtr, *maxLenPtr.
+ *
+ * Side effects:
+ * None.
+ *
+ *----------------------------------------------------------------------
*/
+
static void
DetermineGreedySearchLen(ClockFmtScnCmdArgs *opts,
DateInfo *info, ClockScanToken *tok,
@@ -836,6 +1028,23 @@ DetermineGreedySearchLen(ClockFmtScnCmdArgs *opts,
*maxLenPtr = maxLen;
}
+/*
+ *----------------------------------------------------------------------
+ *
+ * ObjListSearch --
+ *
+ * Find largest part of the input string from start regarding min and
+ * max lengths in the given list (utf-8, case sensitive).
+ *
+ * Results:
+ * TCL_OK - match found, TCL_RETURN - not matched, TCL_ERROR in error case.
+ *
+ * Side effects:
+ * Input points to end of the found token in string.
+ *
+ *----------------------------------------------------------------------
+ */
+
static inline int
ObjListSearch(ClockFmtScnCmdArgs *opts,
DateInfo *info, int *val,
@@ -909,6 +1118,26 @@ LocaleListSearch(ClockFmtScnCmdArgs *opts,
}
#endif
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockMCGetListIdxTree --
+ *
+ * Retrieves localized string indexed tree in the locale catalog for
+ * given literal index mcKey (and builds it on demand).
+ *
+ * Searches localized index in locale catalog, and if not yet exists,
+ * creates string indexed tree and stores it in the locale catalog.
+ *
+ * Results:
+ * Localized string index tree.
+ *
+ * Side effects:
+ * Caches the localized string index tree inside locale catalog.
+ *
+ *----------------------------------------------------------------------
+ */
+
static TclStrIdxTree *
ClockMCGetListIdxTree(
ClockFmtScnCmdArgs *opts,
@@ -960,6 +1189,27 @@ done:
return idxTree;
}
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockMCGetMultiListIdxTree --
+ *
+ * Retrieves localized string indexed tree in the locale catalog for
+ * multiple lists by literal indices mcKeys (and builds it on demand).
+ *
+ * Searches localized index in locale catalog for mcKey, and if not
+ * yet exists, creates string indexed tree and stores it in the
+ * locale catalog.
+ *
+ * Results:
+ * Localized string index tree.
+ *
+ * Side effects:
+ * Caches the localized string index tree inside locale catalog.
+ *
+ *----------------------------------------------------------------------
+ */
+
static TclStrIdxTree *
ClockMCGetMultiListIdxTree(
ClockFmtScnCmdArgs *opts,
@@ -1016,6 +1266,25 @@ done:
return idxTree;
}
+/*
+ *----------------------------------------------------------------------
+ *
+ * ClockStrIdxTreeSearch --
+ *
+ * Find largest part of the input string from start regarding lengths
+ * in the given localized string indexed tree (utf-8, case sensitive).
+ *
+ * Results:
+ * TCL_OK - match found and the index stored in *val,
+ * TCL_RETURN - not matched or ambigous,
+ * TCL_ERROR - in error case.
+ *
+ * Side effects:
+ * Input points to end of the found token in string.
+ *
+ *----------------------------------------------------------------------
+ */
+
static inline int
ClockStrIdxTreeSearch(ClockFmtScnCmdArgs *opts,
DateInfo *info, TclStrIdxTree *idxTree, int *val,