cmStack.h/c: Added cmStackTop() to return the top stack element.

cmStack.c

   return rc;
 }
 
+const void* cmStackTop(     cmStackH_t h )
+{
+  unsigned n = cmStackCount(h);
+  if( n == 0 )
+    return NULL;
+  return cmStackGet(h,n-1);
+}
+
 cmStRC_t _cmStackSetGet( cmStack_t* p, unsigned index, char* data, unsigned dataEleCnt, bool setFl )
 {
   cmStRC_t   rc = kOkStRC;

cmStack.h

 
   extern cmStackH_t cmStackNullHandle;
 
-  // Allocate a stack to hold fixed data elements of size 'eleByteCnt'.
+  // Allocate a stack to hold data elements each of size 'eleByteCnt'.
   // The stack will be initialized with 'initCnt' empty slots. Once these
   // slots are filled 'expandCnt' additional slots will be added as necessary.
   cmStRC_t    cmStackAlloc( cmCtx_t* ctx, cmStackH_t* hp, unsigned initCnt, unsigned expandCnt, unsigned eleByteCnt );
   // Remove 'eleCnt' elements from the stack.
   cmStRC_t    cmStackPop(     cmStackH_t h, unsigned eleCnt );
 
+  // Return a pointer to the top element on the stack. This is the one which will be
+  // lost with the next call to cmStackPop(h,1).
+  const void* cmStackTop(     cmStackH_t h );
+
   // Set the value of 'dataEleCnt' elements on the stack.
   cmStRC_t    cmStackSet(     cmStackH_t h, unsigned index, const void* data, unsigned dataEleCnt );