# 7.3.32 MultiplicityElement

### Kernel

A multiplicity is a definition of an inclusive interval of non-negative integers beginning with a lower bound and ending with a (possibly infinite) upper bound. A multiplicity element embeds this information to specify the allowable cardinalities for an instantiation of this element.

## *Generalizations

Element (from Kernel ) on page 63

## *Description

A MultiplicityElement is an abstract metaclass that includes optional attributes for defining the bounds of a multiplicity. A MultiplicityElement also includes specifications of whether the values in an instantiation of this element must be unique or ordered.

## *Attributes

isOrdered : Boolean For a multivalued multiplicity, this attribute specifies whether the values in an instantiation of this element are sequentially ordered. Default is false.

isUnique : Boolean For a multivalued multiplicity, this attributes specifies whether the values in an instantiation of this element are unique. Default is true.

/ lower : Integer [0..1] Specifies the lower bound of the multiplicity interval, if it is expressed as an integer.

/ upper : UnlimitedNatural [0..1] Specifies the upper bound of the multiplicity interval, if it is expressed as an unlimited natural.

## *Associations

lowerValue: ValueSpecification [0..1] The specification of the lower bound for this multiplicity. Subsets

upperValue: ValueSpecification [0..1] The specification of the upper bound for this multiplicity. Subsets

Element::ownedElement

Element::ownedElement

## *Constraints

These constraints must handle situations where the upper bound may be specified by an expression not computable in the model.

 A multiplicity must define at least one valid cardinality that is greater than zero.

upperBound()->notEmpty() implies upperBound() > 0

 The lower bound must be a non-negative integer literal.

lowerBound()->notEmpty() implies lowerBound() >= 0

 The upper bound must be greater than or equal to the lower bound.

(upperBound()->notEmpty() and lowerBound()->notEmpty()) implies upperBound() >= lowerBound()

 If a non-literal ValueSpecification is used for the lower or upper bound, then evaluating that specification must not have side effects.

Cannot be expressed in OCL.

 If a non-literal ValueSpecification is used for the lower or upper bound, then that specification must be a constant expression.

Cannot be expressed in OCL.

 The derived lower attribute must equal the lowerBound.

lower = lowerBound()

 The derived upper attribute must equal the upperBound.

upper = upperBound()

 The query isMultivalued() checks whether this multiplicity has an upper bound greater than one.

MultiplicityElement::isMultivalued() : Boolean;pre: upperBound()->notEmpty()isMultivalued = (upperBound() > 1)

 The query includesCardinality() checks whether the specified cardinality is valid for this multiplicity.

MultiplicityElement::includesCardinality(C : Integer) : Boolean;pre: upperBound()->notEmpty() and lowerBound()->notEmpty()includesCardinality = (lowerBound() <= C) and (upperBound() >= C)

 The query includesMultiplicity() checks whether this multiplicity includes all the cardinalities allowed by the specified multiplicity.

MultiplicityElement::includesMultiplicity(M : MultiplicityElement) : Boolean;pre: self.upperBound()->notEmpty() and self.lowerBound()->notEmpty()and M.upperBound()->notEmpty() and M.lowerBound()->notEmpty()includesMultiplicity = (self.lowerBound() <= M.lowerBound()) and (self.upperBound() >= M.upperBound())

 The query lowerBound() returns the lower bound of the multiplicity as an integer.

MultiplicityElement::lowerBound() : [Integer];lowerBound = if lowerValue->isEmpty() then 1 else lowerValue.integerValue() endif

 The query upperBound() returns the upper bound of the multiplicity for a bounded multiplicity as an unlimited natural.

MultiplicityElement::upperBound() : [UnlimitedNatural];upperBound = if upperValue->isEmpty() then 1 else upperValue.unlimitedValue() endif

## *Semantics

A multiplicity defines a set of integers that define valid cardinalities. Specifically, cardinality C is valid for multiplicity M if M.includesCardinality(C).

A multiplicity is specified as an interval of integers starting with the lower bound and ending with the (possibly infinite) upper bound.

If a MultiplicityElement specifies a multivalued multiplicity, then an instantiation of this element has a collection of values. The multiplicity is a constraint on the number of values that may validly occur in that set.

If the MultiplicityElement is specified as ordered (i.e., isOrdered is true), then the collection of values in an instantiation of this element is ordered. This ordering implies that there is a mapping from positive integers to the elements of the collection of values. If a MultiplicityElement is not multivalued, then the value for isOrdered has no semantic effect.

If the MultiplicityElement is specified as unordered (i.e., isOrdered is false), then no assumptions can be made about the order of the values in an instantiation of this element.

If the MultiplicityElement is specified as unique (i.e., isUnique is true), then the collection of values in an instantiation of this element must be unique. If a MultiplicityElement is not multivalued, then the value for isUnique has no semantic effect.

The lower and upper bounds for the multiplicity of a MultiplicityElement may be specified by value specifications, such as (side-effect free, constant) expressions.

## *Notation

Issue 8097 - Fix typo.

The specific notation for a MultiplicityElement is defined by the concrete subclasses. In general, the notation will include a multiplicity specification, which is shown as a text string containing the bounds of the interval, and a notation for showing the optional ordering and uniqueness specifications.

The multiplicity bounds are typically shown in the format:

<lower-bound> ‘..’ <upper-bound>

where <lower-bound> is an integer and <upper-bound> is an unlimited natural number. The star character (*) is used as part of a multiplicity specification to represent the unlimited (or infinite) upper bound.

If the Multiplicity is associated with an element whose notation is a text string (such as an attribute, etc.), the multiplicity string will be placed within square brackets ([ ]) as part of that text string. Figure 7.61 shows two multiplicity strings as part of attribute specifications within a class symbol.

If the Multiplicity is associated with an element that appears as a symbol (such as an association end), the multiplicity string is displayed without square brackets and may be placed near the symbol for the element. Figure 7.62 shows two multiplicity strings as part of the specification of two association ends.

The specific notation for the ordering and uniqueness specifications may vary depending on the specific subclass of MultiplicityElement. A general notation is to use a property string containing ordered or unordered to define the ordering, and unique or non-unique to define the uniqueness.

## *Presentation Options

If the lower bound is equal to the upper bound, then an alternate notation is to use the string containing just the upper bound. For example, 1 is semantically equivalent to 1..1.

A multiplicity with zero as the lower bound and an unspecified upper bound may use the alternative notation containing a single star * instead of 0..*.

The following BNF defines the syntax for a multiplicity string, including support for the presentation options:

Issue 8226 - fix BNF

<multiplicity> ::= <multiplicity-range> [ [ ‘{‘ <order-designator> [‘,’ <uniqueness-designator> ] ‘}’ ] |

[ ‘{‘ <uniqueness-designator> [‘,’ <order-designator> ] ‘}’ ] ] <multiplicity-range> ::= [ <lower> ‘..’ ] <upper> <lower> ::= <integer> | <value-specification> <upper> ::= ‘*’ | <value-specification> <order-designator> ::= ‘ordered’ | ‘unordered’ <uniqueness-designator> ::= ‘unique’ | ‘nonunique’

## *Examples Figure 7.61 - Multiplicity within a textual specification Figure 7.62 - Multiplicity as an adornment to a symbol