IDL Object Programming: Inherits vs. Contains

Last month, I wrote an article titled Overloading Objects in IDL. This article discussed how an object can inherit a class and become a subclass of the inherited class. When an object inherits another class, the object is considered to be one of the parent classes. In the Fancy_List example from last month's blog, this was demonstrated by calling ISA on the Fancy_List and asking IDL if the Fancy_List is a list. IDL reported true.

There are times, however, when inheritance is not appropriate. For instance, I'd like to have my fancy list include a hash, which contains the list's modification history; the hash keys will contain a timestamp of when a change is mode to the list, and the value of the hash will be the latest version of the hash.

In this example, it doesn't make sense for the fancy list to inherit HASH. First, the fancy list should not have the properties and methods of HASH. Additionally, we don't want to say that our fancy list is a hash. Finally, because LIST and HASH are both subclasses of IDL_Object and IDL does not allow IDL_Object to be inherited multiple times, the following line would give an error:

!null = {Fancy_List, inherits List, inherits hash}

% FANCY_LIST is already defined with a conflicting definition.
% 1 Compilation error(s) in module FANCY_LIST__DEFINE.

Instead, the fancy list should contain a hash rather than directly inherit it. The following object definition defines the object with a member variable called "history."

pro Fancy_List__Define

  !null = {Fancy_List, $
    inherits List, $
    history: Object_New() }

end

Note that this only creates a placeholder for the hash. The hash must be defined in the ::Init method.

function fancy_list::Init, _REF_EXTRA=extra

  if (~self.List::Init(_EXTRA=extra)) then return, 0
  
  self.history = OrderedHash()
  
  return, 1
  
end

 

Now, as expected, calling ISA(fl, 'HASH') returns zero.

Updating the member

Each time the list is modified, the hash needs to be updated. Here is an example of the ::Add method that updates the history each time a value is added. 

pro Fancy_List::Add, value, index, _REF_EXTRA=extra

  if ~Isa(value, /NUMBER) then return

  self.List::Add, value, index, _EXTRA=extra
  
  self.history[timestamp()] = self[0:self.Count()-1]

end

(the operation self[0:self.Count()-1], which creates a sub-list of the list containing all elements, is a clever way to duplicate the list)

Similar logic should be added to other modification methods such as ::Remove, ::Move, etc. 
 

Retrieving a member from outside of the object

Now that a fancy list with history can be created using the following call

fl = Obj_New('Fnacy_List')

how is the hash accessed?

The hash can either be a property of the object, or it can be accessed through a separate method. Generally, a property is sufficient unless extra work is needed to be performed on the member before it is passed outside of the object.

pro Fancy_List::GetProperty, MODIFICATION_HISTORY=history, _REF_EXTRA=extra
  
  if (Arg_Present(history)) then begin
    history = self.history
  endif
  
  if (N_Elements(extra) gt 0) then begin
    ; Get any properties not defined in this class from the superclass.
    self.List::GetProperty, _EXTRA=extra
  endif

end

One convenience of using properties is that they can be accessed using the "dot" sytax:

history = fl.MODIFICATION_HISTORY

Modifying a member from outside the class

Similar to accessing a member via GetProperty, it is common to be able to set a member via SetProperty. However, in this example, the history should not be included in SetProperty because it should only be appended from within the object and not from the outside.

One thing a user might want to do to save memory is occasionally clear the history. This is a good example of how a member should be modified via a separate method. Fancy_List::ClearHistory is a good name.

pro Fancy_List::ClearHistory
  
  self.history.Remove, /ALL
  
end

Cleaning up the member

Lastly, it is important to know what to do with member variables when the object that contains it is destroyed. In many cases the contained item will be automatically garbage collected when it falls out of scope, so there is nothing to worry about.

However, it is often good practice to write a ::Cleanup method that handles cleaning up the members. This ensures that no matter where the member gets used outside of the class, where it could potentially get stuck in a circular reference, it will be properly disposed. Additionally, there may be cases where you may want to explicitly cleanup or perform special handling on the member when the object is destroyed. 

Here is an example Cleanup method for Fancy_List:

pro Fancy_List::Cleanup
  
  Obj_Destroy, self.history
  
end

Here is a demonstration of the history being destroyed when the parent object is destroyed:

Obj_Destroy, fl
print, obj_Valid(history)

IDL prints:

   0