This document describes how to create variable functions. Also see:

Class Inheritance

You can create your own functions for any IDL data type (except structures and objects). The variable classes have the following inheritance structure:

 

 

You can create new functions on any of the IDL Data Type classes (such as IDL_Byte) or any of the superclasses (IDL_Integer, IDL_Number, and IDL_Variable).

When you create a new function and add it to IDL's path, that function will immediately become available to all variables of that data type within your IDL session. In addition, if your function is on one of the superclasses, then the function will become available to all subclasses. For example:

  • If you create a function called IDL_Float::Fraction, the ::Fraction function will be available on all variables of type FLOAT.
  • If you create a function called IDL_Number::IsWhole, the ::IsWhole function will be available on all IDL numeric data types.
  • If you create a function called IDL_Variable::Save, the ::Save function will be available for all IDL variables (except structures and objects).

Note: All variable methods must be functions, not procedures.

Arguments and Keywords

Your variable function should have the following signature:

function Class::MyFunction, variable [, arg2, arg3, ...] [KEYWORD=keyword, ...]
  compile_opt IDL2, STATIC
  ...
  return, result
end

The first argument is always set equal to the variable that was used to invoke the function. You can have any number of other arguments and keywords.

Be sure to use "compile_opt STATIC" to mark your function as a static method.

Example: IDL_Variable Function

We will create a function called IDL_Variable::Serialize that will convert any IDL variable (except structures and objects) to a JSON string and optionally save the string to a file. Create the following code and save it to a file called "idl_variable__serialize.pro":

function IDL_Variable::Serialize, variable, FILE=file
  ; Use STATIC to mark this as a static method
  compile_opt IDL2, STATIC
  ON_ERROR, 2
  ; Convert the variable to a JSON string.
  ; If type is a pointer, then dereference.
  result = JSON_SERIALIZE((variable.tname eq 'POINTER') ? $
    *variable : variable)
  ; Optionally save the JSON to a file.
  if (ISA(file)) then begin
    OPENW, lun, file, /GET_LUN
    PRINTF, lun, result
    FREE_LUN, lun
  endif
  return, result
end

For example:

IDL> data = FINDGEN(3,2)
IDL> HELP, data.Serialize()
IDL> PRINT, data.Serialize()
[[0.0,1.0,2.0],[3.0,4.0,5.0]]

IDL prints:

<Expression>    STRING    = '[[0.0,1.0,2.0],[3.0,4.0,5.0]]'
[[0.0,1.0,2.0],[3.0,4.0,5.0]]

Using the same function with a string array for input:

IDL> arr = ['abc', 'def', 'ghi', 'idl']

IDL> void = arr.Serialize(FILE='mydata.json')

Example: IDL_String Function

Now we will create a function that will take a JSON string and convert it back to an IDL variable. Create the following code and save it to a file called "idl_string__parsejson.pro":

function IDL_String::ParseJSON, json
  ; Use STATIC to mark this as a static method
  compile_opt IDL2, STATIC
  ON_ERROR, 2
  result = JSON_PARSE(json, /TOARRAY, /TOSTRUCT)
  return, result
end

Here, we take a valid JSON string and call the function:

IDL> json = '{"key1":0.0, "key2":[1,2,3], "key3":true}'
IDL> result = json.ParseJSON()
IDL> help, result

IDL prints:

** Structure <107234a0>, 3 tags, length=40, data length=33, refs=1:
  KEY1            DOUBLE          0.00000000
  KEY2            LONG64    Array[3]
  KEY3            BOOLEAN   true (1)

See Also