Solo: SoloParamHandle user data

From Bcontrol
Revision as of 01:45, 18 March 2009 by CarlosBrody (talk | contribs)

It can often be convenient to store data or flags with SoloParamHandles. For example, one particular lab, the Brody lab, has an SQL database server, and we want to flag SoloParamHandles whose value should be saved in the server. Since this is a lab-specific use, we don't want to add a flag about this to the core SoloParamHandle structure. Instead, there is a "user data" field in SoloParamHandles that allows storing or retrieving in the SoloParamHandle whatever flags or data the user wants. [Note that this user data is not saved with save_soloparamhandles.m.]

There are three methods of @SoloParamHandle objects that form the interface to the user data. An example of their use is at the bottom of this page.

1) set_userdata.m

% [sph] = set_userdata(sph, udata_field, udata_value)
%
% Use this to store data of your choice in a SoloParamHandle. Your user
% data will *not* get saved when the SoloParamHandle is saved. No history
% of the user data is accumulated or stored.
%
% SET_USERDATA(sph, udata_field, udata_value), where udata_field is a
%      string, erases only the previous value of the field named
%      udata_field in the user data, replacing it with the new value
%      udata_value. If no field of the right name existed already, then the
%      field is created. This form of the call, with udata_field, and
%      udata_value, is the recommended form of call.
%
% SET_USERDATA(sph, udata_struct) erases any previous user data in
%      SoloParamHandle sph, and sets it to udata_struct. This last,
%      udata_struct, *must* be struct, even if it is an empty one.
%
% Returns the SoloParamHandle.
%

2) get_userdata.m

% [o] = get_userdata(sph, [udata_field])
%
% If called with no arguments, returns a struct that is the user data for
% SoloParamHandle sph. The default value is an empty struct.
%
% If called with one argument, that argument must be a string; if the user
% data struct has a field with name udata_field, then its value is
% returned. If no such field is found, an error will occur.
%

3) has_userdata_field.m

% [t] = has_userdata_field(sph, fieldname)
%
% Returns TRUE if SoloParamHandle sph has a field called fieldname, FALSE
% otherwise.


An EXAMPLE of using these functions:

% EXAMPLE:
% -------
%
% If sph is a SoloParamHandle,
%
% >> set_userdata(sph, 'my_new_field', 23);
%
% >> get_userdata(sph, 'my_new_field')
%   ans =
%      23
%
% >> has_userdata_field(sph, 'field_not_created_yet')
%   ans = 
%      0
%
% >> set_userdata(sph, 'field_not_created_yet', ...
%       {'oh yes it is created now', [30 40]});
%
% >> has_userdata_field(sph, 'field_not_created_yet')
%   ans = 
%      1
%