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) adds ChildObject, a cpplab object to ParentObject, another cpplab 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') adds ChildObject, a cpplab object to ParentObject, another cpplab object. The ChildObject is assigned the name 'name' in the tree, so you can access it using ParentObject.name
  • ParentObject.add('path/to/ChildObject.hpp') adds ChildObject, a cpplab object to ParentObject, another cpplab 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') adds ChildObject, a cpplab object to ParentObject, another cpplab 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 using ParentObject.name
  • ParentObject.add('path/to/ChildObject.hpp','name','Property',Value...) adds ChildObject, a cpplab object to ParentObject, another cpplab 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 using ParentObject.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...) adds ChildObject, a cpplab object to ParentObject, another cpplab 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.

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()


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()


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.


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)


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.

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.


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.


rebuildCache

Syntax

cpplab.rebuildCache

Description

This static method does two things:

  1. 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
  2. Destroys the cache folder, including all files in it, in the cpplab 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.


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.


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 the paths.cpplab cache for C++ objects whose location contains search_string, and displays all objects that match this in the command prompt
  • cpplab.search('*search*pattern*') searches the paths.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 the paths.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.

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.

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


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.


viewCode

Syntax

C.viewCode()

Description

viewCode opens up the C++ file corresponding to this cpplab object in the default MATLAB editor.