The CODE_COVERAGE function returns information on which lines of code within a routine were not executed. You can use the CODE_COVERAGE function to find unneeded code paths within your IDL code, or to determine if your unit tests are exercising all of your code.
Tip: IDL automatically keeps track of code coverage for all compiled routines. There is no additional overhead to do this. You do not need to "enable" code coverage. You can call the CODE_COVERAGE function at any time to get an up-to-date snapshot of the executed and non-executed lines for your routines.
Example
Save the following code in a file and then compile the code (but do not run it):
function ex_codecover
PRINT, 2+2
if (0) then begin
PRINT, "never reached"
endif else begin
PRINT, "reached"
endelse
return, 1
end
Call the CODE_COVERAGE routine and print the results:
r = CODE_COVERAGE('ex_codecover', EXECUTED=e)
PRINT, 'Lines not executed: ', r.ToString()
PRINT, 'Lines executed: ', e.ToString()
IDL prints:
Lines not executed: 1 2 4 5 7 9
Lines executed: 0
Now call the function and then call CODE_COVERAGE:
void = EX_CODECOVER()
r = CODE_COVERAGE('ex_codecover', EXECUTED=e)
PRINT, 'Lines not executed: ', r.ToString()
PRINT, 'Lines executed: ', e.ToString()
IDL prints:
Lines not executed: 5
Lines executed: 1 2 4 7 9
See the end of this topic for the rules on what is considered a "line of code."
Syntax
Result = CODE_COVERAGE( Routine, /CLEAR, EXECUTED=variable, /FUNCTION, /INCLUDE_END, NLINES=variable, /QUIET )
Return Value
The Result is an integer array containing the line numbers of Routine which were not executed. If all lines were executed then Result is a scalar 0. The line numbers in Result are relative to the .pro file that contains the routine, with the count starting at line 1.
Arguments
Routine
A string giving the name of the user-written procedure or function to analyze. To be successful, the routine must have already been compiled. IDL will first look for a procedure with the given name, and if it cannot find one, it will then look for a function. You can use the FUNCTION keyword to force IDL to look only for a function.
Tip: If you are analyzing a Main program, use "$MAIN$" as the name.
Keywords
CLEAR
Set this keyword to clear the code coverage results for Routine.
EXECUTED
Set this keyword to a named variable. On return, this variable will be set to an integer array containing the line numbers of Routine which were executed. If none of the lines were executed then this variable will be set to a scalar 0.
FUNCTION
By default, CODE_COVERAGE first looks for a procedure with the given Routine name. If it cannot find a procedure then it automatically looks for a function. This works fine in all cases except when there is a procedure and a function with the same name. In this case, you can set the FUNCTION keyword to force CODE_COVERAGE to only look for a function.
INCLUDE_END
By default, CODE_COVERAGE does not include the END statement when computing executed or un-executed lines. This is because for most functions, the RETURN statement will be used to exit from the function and the END statement will never be reached. Even for procedures, you can use RETURN to exit from the procedure and again the END will not be reached. In all of these cases, if the END statements were included, then you would almost always have that line number in your Result, which could be confusing.
However, there may be cases where you want to know if a routine reached the end without hitting a RETURN. In these cases you can set INCLUDE_END to include the END statement within the list of executed or un-executed lines.
NLINES
Set this keyword to a named variable. On return, this variable will contain the total number of lines of code within the routine. This will always be equal to the total number of elements in Result and EXECUTED, and is provided as a convenience.
QUIET
Normally, if IDL cannot find Routine in its list of compiled routines, then CODE_COVERAGE will throw an error. If you set the QUIET keyword, then CODE_COVERAGE will quietly return –1 for the result (EXECUTED will also be set to –1, and NLINES will be set to 0).
Definition of Lines of Code
When computing the "lines of code" that were executed, IDL only looks at certain lines and ignores others. The following are considered "lines of code":
- All expressions and assignments
- "Begin" statements such as if, case, for, foreach, repeat, switch, until, and while.
The following are not considered "lines of code" and are ignored:
- Comment lines
- Empty case and switch selectors
- "End" statements such as endif, endcase, endelse, endfor, endforeach, and endwhile
- The END statement at the end of the routine (unless INCLUDE_END is set)
If you have multiple statements on a line, separated by "&" characters, then each statement will be considered as a separate "line". In this case, the same line number will be returned multiple times in the result (or in EXECUTED). For example, imagine you have the following lines at the end of your function:
18: PRINT,"getting close..."
19: PRINT,"returning..."
20: a=3 & return,a & PRINT,2+2
21: PRINT,"I already returned..."
22: end
After this code is executed, calling CODE_COVERAGE will return [20, 21], since the "print,2+2" and the following line were never executed (note that the "end" on line 22 is not included). The EXECUTED variable will contain [18, 19, 20, 20] since both the "a=3" and "return,a" statements were executed.
Version History
See Also
PROFILER, TIC, TOC