I recognize that for groups we can use the make_unique method to “check” for uniqueness or at least make a group unique if it is not. However it doesn’t really give us any indication if it was required, in other words it returns the group object regardless of whether it actually made the group unique or not, at least that is my understanding after a quick spat of testing.
Is there a method or way to actually check if a group is unique within the model? And rather than change the status of that group, just check for this case and report it back?
I don’t think there is a unique? method per se, but it is easy to get the Group’s Component Definition and see how many Instances it has. Only one instance means unique.
I’m looking at the various ways to check for multiple instances for a definition, which would be the most lightest (least computationally expensive) method to use?
In the beginning the concept of a group was that there should “only ever be one” instance.
Back in those days, accessing the group’s definition was “hidden” and a convenience method was given to access the group definition’s entities collection.
I suppose this was meant to discourage using a group’s definition object to insert “extra” group instances.
But this idea of “one and only one” later changed and it was understood that multiple copies were both fine and desirable if their entities were the same. (They might individually differ as to instance scaling and material assignments.)
And when there were multiple “copies”, ie, instances, manually entering a group instance for edit automatically caused a unique definition to be generated for the instance entered.
The API added #make_unique for both group and component instance objects by SU v6.0, so that extension code could mimic manual editing behavior.
Eventually, it was understood that trying to hide the fact that a group was just a “special” type of component instance from extension coders, made no sense. Then (2015) a direct access #definition was added making coding much simpler for routines that need to act upon both kinds of instances.
The total number instances whether used, not used or mixed, from the viewpoint of the definition itself, is …
cdef.instances.size
The documentation explains the differences for the other two methods which are more robust as they take into account how the definition’s instances are nested within other definition’s entities collections.
So, these count_ prefixed methods are more from the DefintionList's perspective. The count_used_instances() method is the most recent (2016) addition and likely the first one you should call in a determination algorithm.
# Check if Instances are actually placed in the model.
def used_instances?(cdef)
cdef.count_used_instances > 0
end
# Check if definition has any instances, which might be members of
# definitions without instances in the model.
def any_instances?(cdef)
cdef.count_instances > 0 || cdef.instances.size > 0
end
The definition’s instances collection can contain one and only one instance …
cdef.instances.size == 1
… but that instance could be a member of another definition’s entities collection and this definition could be used multiple places within the model and perhaps within other nesting contexts.
… and I also think that the API docs are using “unique” to also mean “individual” in the description for the #count_instances method, which contributes to the mystery.
Okay, it’s going to take me a bit to digest this all but I appreciate the history behind this “mess”. I get it though, software evolves over time and because of that it has impacted these methods and what is now available.