My recent work on the upcoming ENV 5.2 API got me thinking
about how to validate input parameters correctly. One of my goals in writing a
robust ENVI API is to identify any and all invalid inputs and then throw
helpful error messages guiding the user in how to fix their inputs. The most
common approach is to call N_Elements on the variable name and compare that
against 0 (since all even numbers are treated as a logical false value without
compile_opt logical_predicate):
if
(N_Elements(bands) gt
0) then
...
While writing my unit test suites, I found a way to
confound this type of test. Any class that inherits from IDL_Object can
override the _overloadSize() method,
which changes the value returned by N_Elements and Size(/DIMENSION). The new
Hash and List classes do just this, as you can see when we compare the results
from a NullObject and the Hash object:
IDL> o = Obj_New()
IDL> N_Elements(o)
1
IDL> Size(o)
0 11 1
IDL> Size(o, /DIMENSIONS)
0
IDL> h = Hash()
IDL> N_Elements(h)
0
IDL> Size(h)
0 11 0
IDL> Size(h, /DIMENSIONS)
0
If a user passes in an empty Hash or List object, then the
N_Elements test above won't behave as expected.
My next approach was to use the ISA function, to identify variables
that weren't undefined:
if
(ISA(bands)) then
...
But there are at least two exceptions to this rule as
well. If you call ISA() on a NullObject or NullPointer, it returns 0, not 1 as
I had hoped, though it will detect empty Hash or List objects:
IDL> print, ISA(Obj_New())
0
IDL> print, ISA(Ptr_New())
0
IDL> print, ISA(Hash())
1
IDL> print, ISA(List())
1
My next approach was to use the Typename() function, which
does fit the bill:
if
(Typename(bands) ne
'UNDEFINED') then
...
As we can see, this approach is based on the fact that any
undefined variable will return the string 'UNDEFINED', while anything else will
return some other string.
IDL> print, Typename(Obj_New())
OBJREF
IDL> print, Typename(Ptr_New())
POINTER
IDL> print, Typename(Hash())
HASH
IDL> print, Typename(List())
LIST
IDL> print, Typename(foo)
UNDEFINED
IDL> print, Typename(!null)
UNDEFINED
IDL>
print, Typename([])
UNDEFINED
IDL> print, Typename({})
UNDEFINED
The downside to this approach is that it is using string
compares, which aren't as efficient as the comparison of a single Boolean variable. The better alternative is to use Size(/TYPE) which returns one of IDL's integer
type codes:
if
(Size(bands, /TYPE) ne
0) then
...
This is doing a simple integer comparison. This now
behaves as we want it to:
IDL> print, Size(Obj_New(), /TYPE)
11
IDL> print, Size(Ptr_New(), /TYPE)
10
IDL> print, Size(Hash(), /TYPE)
11
IDL> print, Size(List(), /TYPE)
11
IDL> print, Size(foo, /TYPE)
0
IDL> print, Size(!null, /TYPE)
0
IDL> print, Size([], /TYPE)
0
IDL> print, Size({}, /TYPE)
0
As you can see, there are a few different ways to express
an undefined variable, which can be a problem. When a particular keyword is
not used in a function call, then it is truly undefined, same if the variable
passed in for that keyword has never been set. But the last three cases I
showed are different ways to express a null variable. There is the explicit
!null literal, the empty array syntax [], and the empty struct syntax {}. These
last two may look funky, but they have their places in IDL 8.X. Back in the
IDL 7.1 and earlier days, it was common to see code like this:
outData = [0]
for i = 0, N_Elements(inData)-1 do begin
outData = [ outData, inData[i] ]
endfor
outData = outData[1: *]
We have to create a dummy array element to concatenate to,
then strip off the first element. Since IDL 8.0 this is a little simpler:
outData = []
for i = 0, N_Elements(inData)-1 do begin
outData = [ outData, inData[i] ]
endfor
The empty struct construct can be used for repeated calls
to Create_Struct() to append new tags. In either case if the for loop doesn't
get executed then we have an empty array or struct.
With the advent of List and Hash, we can also get an empty
array or struct from their ToArray() and ToStruct() methods respectively when
the container object has no elements. With ENVI Services Engine accepting REST
requests containing JSON inputs, we could end up with empty Hash and List
objects.
You may ask who cares, a !null or empty array is just as
ignorable as an undefined keyword, and in many cases this is a reasonable
assumption. But there are times when we want to discriminate between a !null
and an undefined, and none of the above tests will be able to accomplish this. In fact, we do this in enviTask, where calling oTask.ParamName=!null has the
effect of unsetting that parameter's value, and allowing its default value to
be returned, if it is set. The way to accomplish this is with the /NULL
keyword to ISA:
IDL> ISA(Obj_New(), /NULL)
0
IDL> ISA(Ptr_New(), /NULL)
0
IDL> ISA(Hash(), /NULL)
0
IDL> ISA(List(), /NULL)
0
IDL> ISA(foo, /NULL)
0
IDL> ISA(!null, /NULL)
1
IDL> ISA([], /NULL)
1
IDL> ISA({}, /NULL)
1
So putting it all together, the best way to validate
undefined vs null vs non-null is:
if (Size(val, /TYPE) eq 0) then begin
...
endif else if (ISA(val, /NULL)) then begin
...
endelse