SDMetrics User Manual

SDMetrics - the UML design measurement tool

Contents > 8 Defining Custom Design Metrics and Rules > 8.1 Definition of Metrics > 8.1.9 Substring

8.1.9 Substring

UML tools sometimes mangle various bits of tool-specific information into a single string in the XMI file. For example, the coordinates of an element in a diagram could be specified as follows:

...<geometry>206, 320, 69, 13</geometry>..., or
... location="Left=620;Top=743;Right=732;Bottom=783" ...

The substring procedure extract parts of such strings. Substring extraction is based on separator strings. In its simplest form, the source string is a comma-separated list of values such as "206, 320, 69, 13". The following definition extracts the third value, "69", from the list:

<metric name="width_string" domain="diagramelement">
  <substring source="geometry" separator="','" position="2"/>
</metric>

Attribute source specifies a metric expression that yields the string we want to dissect. Attribute separator specifies the separator string, which can be of any length. This will usually be just a string constant, so it needs to be enclosed in single quotes (see Section 8.5.1.1 "Constants"). In our example, the separator is a single comma, which will split the string "206, 320, 69, 13" into four parts: "206", "320", "69", and "13". Leading or trailing whitespaces are automatically trimmed from each substring.

With the position parameter, we tell SDMetrics which substring we want; the first substring is at position 0, position 2 yields the third value, "69". With negative positions -1, -2, etc. we can access the last substring, last but one substring, and so on, without having to know how many substrings there are. The default value for attribute position is -1 (return the last substring).

Often we do not want to use the substring as is, but process it further, e.g., retrieve its numerical value. We can do this directly with the optional attribute result. The following metric extracts the first value of a comma-separated list and converts it to a number:

<metric name="left" domain="diagramelement">
  <substring source="geometry" separator="','" position="0" result="parsenumber(_value)"/>
</metric>

Attribute result specifies a metric expression, variable _value contains the value of the substring we extracted.

In a source string such as "Left=620 ; Top=743 ; Right=732 ;", the beginning and end of the interesting substrings are delimited by different separators. The optional argument endseparator deals with this situation:

<metric name="top" domain="diagramelement">
  <substring source="location" separator="'Top='" endseparator="';'" 
    result="parsenumber(_value)"/>
</metric>

The separator 'Top=' cuts up the source string into two substrings: "Left=620 ;" and "743 ; Right=732 ;". Of these, we use the second (last) substring, because the position argument is missing. The attribute endseparator="';'" instructs SDMetrics to cut off the substring at the first semicolon. After automatic trimming of whitespace, this leaves us with the string "743", which then gets converted to the number 743.

The "substring" procedure has the following attributes:

source (required): Metric expression that yields the source string.
separator (required): Metric expression that yields the separator string.
position (optional): Metric expression that yields the index of the substring to use. Uses the last substring when omitted.
endseparator (optional): Metric expression that yields a separator string to further delimit the substring to the right. Uses the entire substring when omitted.
limit (optional): The maximum number of substrings returned. The last substring contains the remainder of the source string, even if there are further occurences of the separator string. When omitted, the number of substrings is determined by the number of occurences of the separator string.
result (optional): A metric expression to be applied to the resulting substring. The variable "_value" contains the value of the substring. When omitted, the substring itself is returned.

Section 8.1.8 "Subelements"

Contents

Section 8.2 "Definition of Sets"