' ========================================================================================================================
'                                 ____,__,  __,  ____,_,  _,  ____ ____,__, ,____,____,
'                                (-/_|(-|  (-|  (-|_,(-|\ |  (-|__|-/_|( |_/(-|_,(-|__)
'                                _/  |,_|__,_|__,_|__,_| \|,  _|__)/  |,_| \,_|__,_|  \,
'
'                                             Copyright 2012 Allen Baker
'
' ------------------------------------------------------------------------------------------------------------------------
' File:          M037_StackOfVariants
' Originator:    Allen Baker (2012.02.19 20:16)
' ------------------------------------------------------------------------------------------------------------------------
' $RCSfile$
' $Revision$
' $Date$
' ========================================================================================================================
'
Option Explicit



' ========================================================================================================================
' Description
'    This module implements a Last-In_First-Out Stack data structure for storing entities of type Variant.
' ========================================================================================================================



' =====================================================================================================================
' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Constants  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
' =====================================================================================================================



' =====================================================================================================================
' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Types  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
' =====================================================================================================================



' ==============================================================================================
' Note:  All Objects are REFERENCE TYPES in VBA. All the other built-in data types in VBA are
'        VALUE TYPES. In addition, *all user defined types declared with the Type keyword*, all
'        enums, and all arrays are VALUE TYPES.
'
'        Assignment of a VALUE TYPE variable to another variable of the same VALUE TYPE copies
'        the value from one variable to the other so that each variable contains its own
'        separate instance of the value. Assignment of a REFERENCE TYPE variable to another
'        variable of the same REFERENCE TYPE copies the reference from one variable to the other
'        so that both variables "point to" the same instance of the value.
'
'        Notice that this means that assigning an array *copies* the entire contents of the
'        array.
' ----------------------------------------------------------------------------------------------
Public Type StackOfVariants
   mStackValues() As Variant
   mTopOfStackIdx As Long
   mStackIsEmpty  As Boolean
End Type



' =====================================================================================================================
' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Module Variables  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
' =====================================================================================================================



' =====================================================================================================================
' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Public Routines  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
' =====================================================================================================================



' ===========================================================================================================
' ===========================================================================================================
' ===========================================================================================================
' This function returns a new empty stack.
'
' returns
'    This function returns a new empty stack.
' -----------------------------------------------------------------------------------------------------------
Public Function newStackOfVariants() As StackOfVariants
   ReDim newStackOfVariants.mStackValues(0)
   newStackOfVariants.mTopOfStackIdx = 0
End Function



' ===========================================================================================================
' ===========================================================================================================
' ===========================================================================================================
' This function returns True if the StackOfVariants is empty, otherwise, it returns False.
'
' returns
'    This function returns True if the StackOfVariants is empty, otherwise, it returns False.
'
' param
'    pStack is the StackOfVariants to operate on
' -----------------------------------------------------------------------------------------------------------
Public Function stackOfVariantsIsEmpty(pStack As StackOfVariants) As Boolean
   stackOfVariantsIsEmpty = (pStack.mTopOfStackIdx = 0)
End Function



' ===========================================================================================================
' ===========================================================================================================
' ===========================================================================================================
' This subroutine places an object on the top of the StackOfVariants.
'
' param
'    pStack is the StackOfVariants to operate on
' param
'    pValue is the object to place on the top of the StackOfVariants
' -----------------------------------------------------------------------------------------------------------
Public Sub pushStackOfVariants(pStack As StackOfVariants, pValue As Variant)
   If (UBound(pStack.mStackValues) <= pStack.mTopOfStackIdx) Then
      ReDim Preserve pStack.mStackValues(UBound(pStack.mStackValues) + 10)
   End If
   pStack.mTopOfStackIdx = pStack.mTopOfStackIdx + 1
   pStack.mStackValues(pStack.mTopOfStackIdx) = pValue
End Sub



' ===========================================================================================================
' ===========================================================================================================
' ===========================================================================================================
' This function returns the top object on the StackOfVariants.
'
' returns
'    This function returns the top object on the StackOfVariants.
'
' param
'    pStack is the StackOfVariants to operate on
' -----------------------------------------------------------------------------------------------------------
Public Function popStackOfVariants(pStack As StackOfVariants) As Variant
   popStackOfVariants = "!!* ERROR: Invalid call to popStackOfVariants() on an empty StackOfVariants"
   If (Not stackOfVariantsIsEmpty(pStack)) Then
      popStackOfVariants = pStack.mStackValues(pStack.mTopOfStackIdx)
      pStack.mTopOfStackIdx = pStack.mTopOfStackIdx - 1
   End If
End Function



' ===========================================================================================================
' ===========================================================================================================
' ===========================================================================================================
' This function returns a count of the number of objects on the StackOfVariants.
'
' returns
'    This function returns a count of the number of objects on the StackOfVariants.
'
' param
'    pStack is the StackOfVariants to operate on
' -----------------------------------------------------------------------------------------------------------
Public Function stackOfVariantsCount(pStack As StackOfVariants) As Long
    stackOfVariantsCount = pStack.mTopOfStackIdx
End Function
'
'
'
''
'' =====================================================================================================================
'' =====================================================================================================================
'' =====================================================================================================================
'' This routine is a unit test for the StackOfVariants module
'' -----------------------------------------------------------------------------------------------------------
'Public Sub aaaa_StackTest()
'   Dim mStack As StackOfVariants
'   mStack = newStackOfVariants()
'
'   Call pushStackOfVariants(mStack, "Test 1")
'   Call pushStackOfVariants(mStack, 2048)
'   Call pushStackOfVariants(mStack, True)
'   Call pushStackOfVariants(mStack, Now())
'   Call pushStackOfVariants(mStack, "Test 5")
'   Dim idx As Long
'   For idx = 1 To 30
'      Call pushStackOfVariants(mStack, "Number " & idx)
'   Next idx
'
'   Dim row As Long
'   row = 1
'   Do While Not stackOfVariantsIsEmpty(mStack)
'      Cells(row, 1).value = "Pop LastIn: " & stackOfVariantsCount(mStack) & " - " & popStackOfVariants(mStack)
'      row = row + 1
'   Loop
'   Cells(row, 1).value = "Pop LastIn: " & stackOfVariantsCount(mStack) & " - " & popStackOfVariants(mStack)
'End Sub



' =====================================================================================================================
' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Private Routines  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
' =====================================================================================================================