Timers.zh Documentation for Library Version 1.5

Before Using:

1. Be certain that the arrays Timers[] and TimersRunning[] have an identical index size. 
    Example: If you give Timers an index size of 20 (i.e Timers[20]), then you must ensure that the index size 
    of TimersRunning matches the new size of Timers[] (i.e. Timers[20]). 
        *The array TimersStatus[] is reaerved for future versions, anmd its index size will need to match the other Timers arrays.

2. Establish constants, as you desire. I have truncated the default contants in this release, from the long list in v1.0.
    That list was intended for use in situations where a person needs easy to reference durations that ARE SHARED across events.

Creating & using Timers

1. Ensure that your array has an empty value.
    (A) Assign a constant to that index if desired.
2. Prime the timer -- Do one of the following:
    (A) Use the function initTimer(timer,value) to prime, *and* start the timer. 
    (B) Use the function setTimer(timer,value) to prime a timer with a value, without starting it.
3. Start, pause, and resume timers.
    (A) To start a timer, use startTimer(timer)
    (B) To pause a timer, use pauseTimer(timer)
    (C) To resume a timer, use resumeTimer(timer) * 
        *While equivalent to startTimer(timer), the resumeTimer function ios reserved for future expansion.
4. Timer Operation
    To decrement a timer, call the function reduceTimer(timer). 
        (A) You may decrement timers by 1, as reduceTimer(timer), or specify 
        an amount per frame with reduceTimer(timer,amount);.
    To set a value to a timer, use setTimer(timer, amount). 
        (A) This normally only sets a timer if its present value is '0', 
        however, you may specify forced operation as setTimer(timer,true);.
    To stop, and clear a timer, use clearTimer(timer).
        *This is the opposite of initTimer(timer);.
    To check timer operation:
        (A) Use one of the following boolean conditions to check/compare a timer STATUS:
            (1) timerRunning() - returns true if running.
            (2) timer On() - returns true of running
            (3) timerOff() - returns true if not running.
        (B) Use one of the following to check/compatre against the VALUE of a timer:
            (1) returnTimer() - Int returns; returns the value of a spcified timer as an int.
            (2) checkTimer() - Boolean returns; returns true of a timer is <= 1;
                (A) Alternatively, checkTimer(TIMER,true) returns true if a timer is EXACTLY ZERO.
                (B) checkTimer(timer, value) can compare a specific value as a boolean.
                (C) checkTimer(timer, value, true) can compare a specific value, or less; as a boolean.
            (3) zeroTimer() returns true if a timer is exactly zero. 
                *I dislike how I named this function, and have replaced it with checkTimer(int timer, bool precise).
5. Timer Manipulation
    To change the specific numeric value of a timer to any arbitrary value, without regard to its present value, use:
        changeTimer(timer,value);
    To completely clear a timer, suspending it, and wiping its numeric value, use:
        clearTimer(timer);
    To add an arbitrary amount to any timer, use:
        increaseTimer(timer,value);
    To reduce a timer by an arbitrary value, even if it is not running, use:
        shrinkTimer(timer,value); -- This will not reduce a timer below zero.
            (A) If you want to shrink a timer, allowing it to drop below zero, use:
                shrinkTimer(timer,value,true);
6. Timers Notes:
    To automate timers, declare initTimer, or setTimer functions for each timer, and reduceTimer functions for each timer 
    that you are running in your loops -or- use automatic functions:
    
    AUTOMATED TIMER ACTIVITIES
    
    Starting, Pausing, Resuming, and stopping Timers: You can initiate, pause, or otherwise manipulate timer status en masse using:
        (1) startAllTimers(); - This converts the status of all timers to 'running'.
            ( Note: Timers should first be initialised with values. )
        (2) startRangeOfimers(min,max); -- This converts the status of timers min, to max, to running.
        (3) suspendAllTimers(); - This pauaes all timers.
            (A) stopAllTimers(); - Reserved for future use.
        (4) suspendRangeOfTimers(min, max); - This suspends timer min, to timer max.
            (A) stopRangeOfTimers(min,max); - Reserved for future use.
    
    Reducing Timers: You can set one command to reduc all timers, or all running timers, or a specific range of timers:
        (1) decreaseAllTimers(value); -- Decreases all timers by amount value. Will not reduce any timer below zero
            (A) decreaseAllTimers(value,true); -- Decreases all timers by amount value, allowing timers to be negative numbers.
        (2) decreaseRunningTimers(amount); -- Decreases only running timers by value specified in as amount. Will not reduce any timer below zero.
            (A) decreaseRunningTimers(amount, true); -- As above, except that negative values are permitted.
        (3) decreaseRangeOfTimers(min,max,amount); -- Decrease timer min, to timer max, by value amount;  will not reduce any timer below zero
            (A) decreaseRangeOfTimers(min,max,amount,true); - As above, except that negative values are permitted.
            
    Increasing Timers (en masse): 
        (1) increaseAllTimers(value); -- Increases all timers by amount value.
        (2) increaseRunningTimers(amount); -- Increases only running timers by value specified in as amount. 
        (3) increaseRangeOfTimers(min,max,amount); -- Increase timer min, to timer max, by value amount.
        
    Clear Timers (en masse): You can reaset the value of multiple timers to zero using:
        (1) clearAllTimers(); -- Clears all timers to zero.
        (2) clearRunningTimers(); -- Clears only running timers to zero.
        (3) clearSuspendedTimers(); -- Clears only non-running timers (status: Suspended)
            (A) clearPausedTimers(); -- As above, reserved for status PAUSED
            (B) clearStoppedTimers(); As above, reserved for status STOPPED.
        (4) clearRangeOfTimers(min,max); -- Clears timers min, to max, back to zero.
            
    Set Timer Values (en masse): You can set an arbitrary value to multiple timers, using:
        (1) setAllTimers(amount); -- Sets all timers to arbitrary value amount.
        (2) setRunningTimers(amount); -- Sets all RUNNING timers to arbitrary value amount.
        (3) setRangeOfTimers(min,max); -- Sets range of timers from timer min, to timer max to arbitrary value amount,
            
            
7. Library Notes:

The array TimerStatus is reserved for future expansion, that will utilise the following status types:
0: Timer off / STOPPED.
1: Timer on / RUNNING.
2. Timer SUSPENDED. This is *not* intended to be identical to STOPPED, and can be used to distinguish between a timer intentionally paused, 
   and one that was never initiated, or has been fully stopped/cleared/reset. Allows granulatiry in timer status.
3. Timer PAUSED. Intended for suspension actions that have a fixed DURATION.
4. Timer RESUMED. Intended to distinguish if a timer that is RUNNING has previously been PAUSED, or SUSPENDED.