/****************************************************************************
*                                                                           *
*   TOCLABEL.SPL Copyright 2024 (C) DSP Development Corporation             *
*                                                                           *
*   Author:      Randy Race                                                 *
*                                                                           *
*   Synopsis:    Labels a window with elapsed tic/toc seconds               *
*                                                                           *
*   Revisions:    1 Nov 2024     RRR     Creation                           *
*                                                                           *
****************************************************************************/


#if @HELP_TOCLABEL

    TOCLABEL

    Purpose: Labels a window with elapsed tic/toc seconds.

    Syntax:  TOCLABEL(window)

              window - Optional. Window reference. Defaults to the current
                       Window.


    Returns: Nothing, the window is labeled with the value of TOC in seconds.

    Example:
             W1: gnorm(1024 * 512, 1)
             W2: tic;fft(w1);toclabel

             W2 is labeled with the approximate time to calculate the FFT
             of W1.
            
    Remarks:
             TOCLABEL labels a window with the elapsed time since the last
             TIC command with a precision of approximately 0.00001 seconds,
             i.e. 10 microseconds. The interval timer is not reset.

             TOCLABEL is useful for profiling the time performance of
             operations that result in a window series.

    See Also:
             CLOCK
             GETTIME
             TIC
             TOC
#endif


/* label window with tic/toc elapsed seconds */
toclabel(w = refwindow(w0))
{
        local tocstr;

        /* invoke toc and convert to string */
        tocstr = strnum(toc);

        /* label window */
        label(w, tocstr);
}