View source for Solo: SoloParamHandle user properties

It can often be convenient to store information 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 property" field in SoloParamHandles that allows storing or retrieving in the SoloParamHandle whatever flags or info the user wants. 

[Note that the user property is like a property of a SoloParamHandle, e.g., like "position", which means that it is ''not'' saved with save_soloparamhandles.m, nor is a trial-by-trial history of it generated.] 

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

'''1) set_userprop.m'''
<pre>
% [sph] = set_userprop(sph, uprop_field, uprop_value)
%
% Use this to store data of your choice in a SoloParamHandle. Your user
% data will be a property of a SoloParamHandle, similar to "position", or
% the label string-- which means that user prop will *not* get saved when
% the SoloParamHandle is saved, and no history of the user prop is
% accumulated or stored.
%
% SET_USERPROP(sph, uprop_field, uprop_value), where uprop_field is a
%      string, erases only the previous value of the field named
%      uprop_field in the user prop, replacing it with the new value
%      uprop_value. If no field of the right name existed already, then the
%      field is created. This form of the call, with uprop_field, and
%      uprop_value, is the recommended form of call.
%
% SET_USERPROP(sph, uprop_struct) erases any previous user prop in
%      SoloParamHandle sph, and sets it to uprop_struct. This last,
%      uprop_struct, *must* be struct, even if it is an empty one.
%
% Returns the SoloParamHandle.
%
</pre>

'''2) get_userprop.m'''
<pre>
% [o] = get_userprop(sph, [uprop_field])
%
% If called with no arguments, returns a struct that is the user prop for
% SoloParamHandle sph. The default value is an empty struct.
%
% If called with one argument, that argument must be a string; if the user
% prop struct has a field with name uprop_field, then its value is
% returned. If no such field is found, an error will occur.
%
</pre>

'''3) has_userprop_field.m'''
<pre>
% [t] = has_userprop_field(sph, fieldname)
%
% Returns TRUE if SoloParamHandle sph has a field called fieldname, FALSE
% otherwise.
</pre>



An '''EXAMPLE''' of using these functions:
<pre>
% EXAMPLE:
% -------
%
% If sph is a SoloParamHandle,
%
% >> set_userprop(sph, 'my_new_field', 23);
%
% >> get_userprop(sph, 'my_new_field')
%   ans =
%      23
%
% >> has_userprop_field(sph, 'field_not_created_yet')
%   ans = 
%      0
%
% >> set_userprop(sph, 'field_not_created_yet', ...
%       {'oh yes it is created now', [30 40]});
%
% >> has_userprop_field(sph, 'field_not_created_yet')
%   ans = 
%      1
%
</pre>