The cpplab class¶
This document describes the "cpplab" class. This is a MATLAB class that was designed to automatically bind C++ code to MATLAB objects. The "xolotl" class inherits from this class, so all "xolotl" objects are also cpplab objects.
Methods¶
add¶
The add method allows you to add cpplab objects to other cpplab objects and build a tree of cpplab objects.
Syntax
ParentObject.add(ChildObject)
ParentObject.add(ChildObject,'name')
ParentObject.add('path/to/ChildObject.hpp')
ParentObject.add('path/to/ChildObject.hpp','name')
ParentObject.add('path/to/ChildObject.hpp','name','Property',Value...)
ParentObject.add('path/to/ChildObject.hpp','Property',Value...)
Description
ParentObject.add(ChildObject)
addsChildObject
, acpplab
object toParentObject
, anothercpplab
object. The ChildObject is automatically named with the name of the C++ class it refers to, so you can access it using ParentObject.(ChildObject.cpp_class_name)ParentObject.add(ChildObject,'name')
addsChildObject
, acpplab
object toParentObject
, anothercpplab
object. The ChildObject is assigned the name 'name' in the tree, so you can access it usingParentObject.name
ParentObject.add('path/to/ChildObject.hpp')
addsChildObject
, acpplab
object toParentObject
, anothercpplab
object. The ChildObject is created on the fly using the path specified, and is automatically named with the name of the C++ class it refers to, so you can access it using ParentObject.(ChildObject.cpp_class_name)ParentObject.add('path/to/ChildObject.hpp','name')
addsChildObject
, acpplab
object toParentObject
, anothercpplab
object. The ChildObject is created on the fly using the path specified, and is assigned the name 'name' in the tree, so you can access it usingParentObject.name
ParentObject.add('path/to/ChildObject.hpp','name','Property',Value...)
addsChildObject
, acpplab
object toParentObject
, anothercpplab
object. The ChildObject is created on the fly using the path specified, and is assigned the name 'name' in the tree, so you can access it usingParentObject.name
. In addition, the ChildObject is configured on-the-fly with the properties you specify before addition to ParentObject.ParentObject.add('path/to/ChildObject.hpp','Property',Value...)
addsChildObject
, acpplab
object toParentObject
, anothercpplab
object. The ChildObject is created on the fly using the path specified, and is automatically named with the name of the C++ class it refers to, so you can access it using ParentObject.(ChildObject.cpp_class_name). In addition, the ChildObject is configured on-the-fly with the properties you specify before addition to ParentObject.
See Also
addNoHash¶
adds a cpplab object to another, but does not
update the hashes of the object being added to.
Do not use this method, use add()
instead.
See Also
copy¶
makes a copy of a cpplab object
Syntax
C2 = copy(C)
Description
Since cpplab
objects inherit from MATLAB's handle class,
they cannot be copied using simple assignation. That means that
% assuming C is a cpplab object
C2 = C;
does not make a copy of C
, and changes in C
manifest as
changes in C2
, and vice versa.
deserialize¶
Syntax
C.deserialize(V)
Description
C.deserialize(V)
updates all parameters in a cpplab object, including any child objects it may contain, using the vector V. V must be a vector containing doubles of the right size. An easy way to determine the correct size of V
is to use C.serialize()
first.
deserialize
is used to update all the values of your cpplab object using a vector, typically generated by C.serialize()
See
destroy¶
Syntax
ParentObject.ChildObject.destroy()
Description
removes a cpplab object that is contained within another and destroys it. This is the opposite of cpplab.add()
See
exist¶
Syntax
TF = exist(object,thing)
Description
removes a cpplab object that is contained within another and destroys it. This is the opposite of cpplab.add()
Warning
Do not use this method. It will be removed in a future release.
See Also
find¶
Syntax
object_names = find(self,cpp_parent_class_name)
object_names = find(self,object_name)
object_names = find(self,'*wildcard*parameter')
Description
finds objects in a structure cpplab tree that consists of nested objects.
object_names = find(self,cpp_parent_class_name)
See Also
generateConstructors¶
Syntax
[constructors, cpp_class_parent, names] = C.generateConstructors(prefix)
Description
Do not use this method.
generateHeaders¶
Syntax
H = C.generateHeaders
Description
Do not use this method.
get¶
Syntax
V = C.get('child_parameter')
V = C.set('*wildcard*string')
V = C.set('*wildcard*string')
Description
get
is a method that allows you to quickly read values from
multiple objects and parameters in a nested cpplab tree.
V = C.get('child_parameter')
gets the value of the parameter specified by the character vector. 'child_parameter' must be a resolvable name, i.e., C.child_parameter should exist as a scalar.V = C.set('*wildcard*string')
gets the values of all parameters in the cpplab object tree found using the wild card search string to the scalar value provided.V = C.set('*wildcard*string')
gets the values of all parameters in the cpplab object tree found using the wild card search string.
See Also
getAllHashes¶
Syntax
H = C.getAllHashes
Description
Do not use this method.
hashSource¶
Syntax
C.hashSource
Description
hashSource
asks the parent of a cpplab object in a nested cpplab object tree to compute its hash.
See Also
readCPPClass¶
Syntax
[class_members, input_types, default_values] = C.readCPPClass(cppfilename)
Description
Do not use this method.
readChildFunctions¶
Syntax
child_functions = C.readChildFunctions
Description
Do not use this method.
rebase¶
Syntax
C.rebase
Description
rebase
traverses a nested cpplab object tree, and checks that the cpp_class_path
of every cpplab object in the tree resolves correctly. If it doesn't, it calls resolvePath
to identify and link to the correct C++ file wherever it may be on your computer. MD5 hashing is used to ensure that the correct C++ file is linked against. If no C++ file with the correct hash is found, an error is thrown.
You will need to call this method if you save a cpplab object to disk, move it to a different computer, and load it there.
See Also
rebuildCache¶
Syntax
cpplab.rebuildCache
Description
This static method does two things:
- searches the MATLAB path and containing folders for C++ header files (with the extension .hpp), and makes a list of them that is stored in a file called
paths.cpplab
- Destroys the
cache
folder, including all files in it, in thecpplab
directory.
If you find that you are getting errors where cpplab complains it can't find certain files, a good first step is to run this method to rebuild the cache.
See Also
replicate¶
Description
Do not use this method.
resolvePath¶
Syntax
cpplab.resolvePath('search_string')
file_loc = cpplab.resolvePath('search_string')
[~,all_files] = cpplab.resolvePath()
Description
cpplab.resolvePath('search_string')
searches for a C++ file in the cache that matches the search string. If nothing is found in the cache, the cache is rebuilt, and folders on the MATLAB path are searched for C++ header files. If more than one file is found, the first file found is displayed.file_loc = cpplab.resolvePath('search_string')
searches for a C++ file in the cache that matches the search string. If nothing is found in the cache, the cache is rebuilt, and folders on the MATLAB path are searched for C++ header files. If more than one file is found, the first file found is returned.[~,all_files] = cpplab.resolvePath()
A cell array containing the paths to all C++ header files in the cache is returned. Nothing is actually searched, so you can call this method with no arguments -- the arguments are ignored.
Warning
Do not call resolvePath with two arguments. The shallow flag is meant for internal use.
See Also
search¶
Syntax
cpplab.search('search_string')
cpplab.search('*search*pattern*')
objects = cpplab.search('*search*pattern*');
Description
search
is a static method that looks for C++ files that match certain criterion.
cpplab.search('search_string')
searches thepaths.cpplab
cache for C++ objects whose location containssearch_string
, and displays all objects that match this in the command promptcpplab.search('*search*pattern*')
searches thepaths.cpplab
cache for C++ objects whose location contains the specified search pattern, allowing for wild cards, and displays all objects that match this in the command prompt.objects = cpplab.search('*search*pattern*');
searches thepaths.cpplab
cache for C++ objects whose location contains the specified search pattern, allowing for wild cards, and returns them in a cell array. Nothing is written to STDOUT.
See Also
serialize¶
Syntax
values = C.serialize;
[values, names] = C.serialize;
[values, names, is_relational] = C.serialize;
[values, names, is_relational, real_names] = C.serialize;
Description
serialize
is a method that traverses the cpplab object tree, collects the value of every parameter in every object and packs them into a vector.
values = C.serialize
returns a vector of all parameters in the nested cpplab object C.[values, names] = C.serialize
also returns the names of all parameters. The order of names matches the order of values[values, names, is_relational] = C.serialize
also returns a logical vector that is the same length as the other two outputs. Each element in this vector is either true or false based on whether the parameter is a scalar value or a relational function handle.[values, names, is_relational, real_names] = C.serialize
also returns a fourth cell vector which contains the real names of all parameters, that allows you to directly use it to reference those parameters.
See Also
set¶
Syntax
C.set('child_parameter',value)
C.set('*wildcard*string',scalar_value)
C.set('*wildcard*string',vector_value)
Description
set
is a method that allows you to quickly assign values to
multiple objects and parameters in a nested cpplab tree.
C.set('child_parameter',value)
sets the value of the parameter specified by the character vector in the first argument to the value in the second argument. 'child_parameter' must be a resolvable name, i.e., C.child_parameter should exist as a scalar.C.set('*wildcard*string',scalar_value)
sets the values of all parameters in the cpplab object tree found using the wildcard search string to the scalar value provided. If multiple parameters are found, then all of them will be set to scalar_value.C.set('*wildcard*string',vector_value)
sets the values of all parameters in the cpplab object tree found using the wildcard search string to the vector value provided. The number of parameters matching the search string must be equal to the length of the vector_value, otherwise an error is thrown.
See Also
shallowHash¶
Syntax
C.shallowHash
Description
shallowHash
computes the hash of a cpplab object using
the hashes of its children. Hashes are MD5 hashes computed
using GetMD5
See Also
subsasgn¶
Syntax
subsasgn(self, S, value)
Description
subsasgn
is an overloaded method of cpplab that
first checks that assignation that you're trying to do
is legal. It prevents you from overwriting a cpplab object
in a nested cpplab tree with a scalar, and prevents you
from nesting vectors when it expects scalars.
See Also
viewCode¶
Syntax
C.viewCode()
Description
viewCode
opens up the C++ file corresponding to this cpplab object in the default MATLAB editor.