topsGroupedList Class Reference

Overview

A structured container for values and objects.

topsGroupedList is a general-purpose container for holding Matlab values and objects, which it calls "items". It has a two-tiered structure: you must add items to "groups" of related items, and you must give each item its own "mnemonic" which identifies it within a group.

Groups and mnemonics can be strings or numbers. So a topsGroupedList is something like a struct (which uses strings) or cell array (which uses numbers) that contains a bunch of other structs or cell arrays. But it's more flexible and better organized than that.

One way it's more flexible is in the values that a group or mnemonic is allowed to have. Groups and mnemonics can use arbitrary strings, whereas structs cannot use strings that contain dots or spaces. Similarly, groups and mnemonics can have arbitrary numeric values, where as cell arrays must use positive integers.

There is one important constriant on groups and mnemonics: for each instance of topsGroupedList, all groups must be identified by either strings or numbers, but not a mixture of the two. Likewise, the mnemonics used in each group must be all strings or all numbers.

One way in which topsGroupedList is better organized than a random collection of structs and cell arrays is that you can always "ask" it what groups, mnemonics, and items it contains, and it knows where to look for them. You can also ask it if it contains a certain group, mnemonic, or item.

The big idea is that you can neatly list whatever data and objects you need for an experiment. As long as you give the list to your other functions and objects (as an argument, for example), they can access all of your stuff. Moreover, you can always view what's in your list by using its gui() method.

Inheritance diagram for topsGroupedList:

Protected Properties
Property	groups = {}
	cell array of strings or numbers for all list groups
Property	length = 0
	number of items contained among all groups
Property	allGroupsMap
	containers.Map of data for each group

Methods
self	topsGroupedList (varargin)
	Constuct with name optional. More...
fig	gui (self)
	Open a GUI to view object details. More...
p	guiPanel (self, varargin)
	Make a topsGroupedListPanel with details about this object.
	addItemToGroupWithMnemonic (self, item, group, mnemonic)
	Add a new item to the list. More...
	removeItemFromGroup (self, item, group)
	Remove all instances of an item from a group. More...
	removeMnemonicFromGroup (self, mnemonic, group)
	Remove a mnemonic and its item from a group. More...
	removeGroup (self, group)
	Remove a whole group from the list. More...
	removeAllGroups (self)
	Remove a whole groups from the list. More...
	makeGroupFromList (self, groupName, list)
	Make a group from a cell array list of pairs: <string mnemonic>="">,
	mergeGroupsIntoGroup (self, sourceGroups, destinationGroup)
	Combine multiple groups into another group. More...
item	getItemFromGroupWithMnemonic (self, group, mnemonic)
	Get an item out of the list. More...
varargout	subsref (self, info)
	Get list items with {} syntax. More...
self	subsasgn (self, info, value)
	Add list items with {} syntax. More...
n	numel (self, varargin)
	Tell Matlab how many items to expect from {} syntax It's always 1.
mnemonics	getAllMnemonicsFromGroup (self, group)
	Get all mnemonics from a group. More...
items mnemonics	getAllItemsFromGroup (self, group)
	Get all items (and optionally all mnemonics) from a group. More...
groupStruct	getAllItemsFromGroupAsStruct (self, group)
	Get all items from a group, as a struct array. More...
isContained	containsGroup (self, group)
	Does the list contain the given group? More...
matches isMatch	getGroupNamesMatchingExpression (self, expression)
	Get string group names that match the given regular expression. More...
isContained	containsMnemonicInGroup (self, mnemonic, group)
	Does the list contain the given group and mnemonic? More...
isContained	containsItemInGroup (self, item, group)
	Does the list contain the given group and item? More...
Methods inherited from topsFoundation
self	topsFoundation (name)
	Constuct with name optional. More...
fig	gui (self)
	Open a GUI to view object details. More...
p	guiPanel (self, varargin)
	Make a topsDetailPanel with details about this object. More...

Static Methods
static isContained	mapContainsItem (map, item)
	Does the containers.Map contain the given item? More...
static groupList	createGroupFromList (groupName, list)
	Convenient utility.
Static Methods inherited from topsFoundation
static c index	cellAdd (c, item, index)
	Add an item to a cell array. More...
static selector	cellContains (c, item)
	Does a cell array conatin an item? More...
static c	cellRemoveItem (c, item)
	Remove an item from a cell array. More...
static c	cellRemoveElement (c, index)
	Remove indexed elements from a cell array. More...
static index selector	findStructName (s, name)
	Where is the given name in the given struct array? More...

Additional Inherited Members
Properties and Events inherited from topsFoundation
Property	name = ''
	a string name to indentify the object
Property	clockFunction =@topsClock
	clock function, to standardize

Constructor

topsGroupedList()

self topsGroupedList

(

varargin

)

Constuct with name optional.

Parameters

name	optional name for this object

If name is provided, assigns name to this object.

Methods

gui()

fig gui

(

self

)

Open a GUI to view object details.

Opens a new GUI with components suitable for viewing objects of this class. Returns a topsFigure object which contains the GUI.

addItemToGroupWithMnemonic()

addItemToGroupWithMnemonic	(	self	,
		item	,
		group	,
		mnemonic
	)

Add a new item to the list.

Parameters

item	any Matlab value or object
group	a string or number that identifies a group of related items
mnemonic	a string or number to identify this new item. If group and mnemonic are already in the list, then item will replace an older item.

Note: for each topsGroupedList, group values must be all strings or all numbers. Likewise, for each group, mnemonics must be all strings or all numbers.

removeItemFromGroup()

removeItemFromGroup	(	self	,
		item	,
		group
	)

Remove all instances of an item from a group.

Parameters

item	the item to remove
group	the group from which item should be removed

Searches group for items that isequal() to item. Removes all such items, along with their mnemonics.

This method is likely to be very slow. Use removeMnemonicFromGroup for better performance.

removeMnemonicFromGroup()

removeMnemonicFromGroup	(	self	,
		mnemonic	,
		group
	)

Remove a mnemonic and its item from a group.

Parameters

mnemonic	the string or number identifying an item
group	the group from which mnemonic, and its item, should be removed

Removes mnemonic and its item from group.

removeGroup()

removeGroup	(	self	,
		group
	)

Remove a whole group from the list.

Parameters

group

the string or number identifying the group to remove

Removes all mnemonics and items from group, then removes group itself from the list.

removeAllGroups()

removeAllGroups

(

self

)

Remove a whole groups from the list.

Removes each item from each group, and each group itself, one at a time.

mergeGroupsIntoGroup()

mergeGroupsIntoGroup	(	self	,
		sourceGroups	,
		destinationGroup
	)

Combine multiple groups into another group.

Parameters

sourceGroups	cell array of strings or numbers identifying groups to be merged.
destinationGroup	string or number identifying a group that will receive all the mnemonics and items from all of the source groups. destinationGroup may exist already, or not.

Merging groups will probably result in redundant items being stored in the list. For example, imagine merging source groups A and B into a new destination group C. All of the original items in A and B will then be held redundantly in C. The length of the list will increase, even though no new items were added. So you might wish to remove A and B after the merge.

An exception is when the destination group already exists and uses some of the same mnemonics as the source groups. In that case, an item from a source group will overwrite any item in the destination group that has the same mnemonic. Thus, meging group A into group A (itself) should have no effect.

Another exception is when the source groups share some mnemonics among them. In that case, groups listed later in soureGroups will win out, and their items will overwrite items from other groups that share the same mnemonics.

getItemFromGroupWithMnemonic()

item getItemFromGroupWithMnemonic	(	self	,
		group	,
		mnemonic
	)

Get an item out of the list.

Parameters

group	the group containing the desired item
mnemonic	the menemonic identifying the desired item

Returns the item listed under group and mnemonic. If group isn't in the list, or doesn't contain mnemonic, returns [].

subsref()

varargout subsref	(	self	,
		info
	)

Get list items with {} syntax.

For topsGroupedList l,

• item = l{g}{m} is the same as item = l.getItemFromGroupWithMnemonic(g,m)
• allItems = l{g} is the same as allItems = l.getAllItemsFromGroup(g) Beware: [allItems, allMnemonics] = l{g} makes Matlab crash. But [allItems, allMnemonics] = l.getAllItemsFromGroup(g) works.

subsasgn()

self subsasgn	(	self	,
		info	,
		value
	)

Add list items with {} syntax.

For topsGroupedList l,

• l{g}{m} = item is the same as l.addItemToGroupWithMnemonic(item, g, m)

getAllMnemonicsFromGroup()

mnemonics getAllMnemonicsFromGroup	(	self	,
		group
	)

Get all mnemonics from a group.

Parameters

group

the group to get mnemonics for

Returns a cell array containing all mnemonics from group, or {} if group isn't in the list. The mnemonics will be sorted alphabetically or numerically.

getAllItemsFromGroup()

items mnemonics getAllItemsFromGroup	(	self	,
		group
	)

Get all items (and optionally all mnemonics) from a group.

Parameters

group

the group to get items for

Returns a cell array of all items from group. If group isn't in the list, returns {}. Items will be sorted alphabetically or numerically, by mnemonic.

Optionally returns all mnemonics from group, as well.

getAllItemsFromGroupAsStruct()

groupStruct getAllItemsFromGroupAsStruct	(	self	,
		group
	)

Get all items from a group, as a struct array.

Parameters

group

the group to get items for

Returns a struct array with one element per item in group. Each struct element has three fields:

• item – the item itself
• mnemonic – the mnemonic for the item
• group – the string or number equal to group

If group isn't in the list, the struct array will have zero length.

containsGroup()

isContained containsGroup	(	self	,
		group
	)

Does the list contain the given group?

Parameters

group

a string or number for a group that might be in the list

Returns true if the list contains group. Otherwise returns false.

getGroupNamesMatchingExpression()

matches isMatch getGroupNamesMatchingExpression	(	self	,
		expression
	)

Get string group names that match the given regular expression.

Parameters

expression

a regular expression to match agains group names in the list

Compares expression to the names of groups in the list. Returns a cell array of strings of group names that match expression. If the list uses numeric group names, returns an empty cell array.

Also returns as a second ouput a logical selector with one element per list group, set to true where a group matches expression.

Regular expressions are specially formatted strings used for matching patterns in other strings. See Matlab's builtin regexp() and "Regular Expressions" documentation.

containsMnemonicInGroup()

isContained containsMnemonicInGroup	(	self	,
		mnemonic	,
		group
	)

Does the list contain the given group and mnemonic?

Parameters

mnemonic	a string or number for a menemonic that might be in group
group	a string or number for a group that might be in the list

Returns true if the list contains group and group contains mnemonic. Otherwise returns false.

containsItemInGroup()

isContained containsItemInGroup	(	self	,
		item	,
		group
	)

Does the list contain the given group and item?

Parameters

item	a value or object that might be in group
group	a string or number for a group that might be in the list

Searches group for any occurence of item. Returns true if the list contains group and group contains at least on item that isequal() to item. Otherwise returns false.

mapContainsItem()

static isContained mapContainsItem ( map  , item    )

static

Does the containers.Map contain the given item?

Parameters

map	an instance of containers.Map
item	a value or object that might be in the map

Searches the map for the item. Returns true if any value in map isequal() to item. Otherwise returns false.

---

The documentation for this class was generated from the following file:

• topsGroupedList.m