Skip to content

# 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.

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

### 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:

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.

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

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.

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.