View source for Documentation:Default String Representation and asString

You can define a class's '''DefaultStringRepresentation''' to control the text returned when that object is used with [[Documentation:OCLOperators asString|<code>asString</code>]]; use it to give objects a meaningful, consistent presentation in OCL expressions, messages, and views.

== How DefaultStringRepresentation works ==

[[Documentation:OCLOperators asString|<code>asString</code>]] is available on objects and converts the value to a string in the result of an OCL expression. For an object instance, the operation uses the class's '''DefaultStringRepresentation''' expression as its result.

For example, if a <code>Car</code> class has a registration-number attribute and its DefaultStringRepresentation is based on that attribute, then an expression such as:

<syntaxhighlight lang="ocl">
self.asString
</syntaxhighlight>

returns the car's registration number. This makes a constraint or message identify the actual car rather than an unspecified object representation.

Set a DefaultStringRepresentation that identifies the object to a user. A registration number is suitable for <code>Car</code>; a name or a business identifier may be suitable for another class. The expression must remain valid while the object is incomplete. For example, a newly created car may not yet have a brand, but it can still have a registration number for display.

== Use a derived presentation attribute ==

Do not place a complex expression directly in DefaultStringRepresentation when the representation must update as model values change. Instead, define a derived attribute that contains the presentation logic, then use that attribute from DefaultStringRepresentation.

For example, on a <code>Fruit</code> class, you can define a derived attribute named <code>Presentation</code> that combines the fruit name and weight. Configure the class's DefaultStringRepresentation to use:

<syntaxhighlight lang="ocl">
self.Presentation
</syntaxhighlight>

When the fruit's weight changes, the derived <code>Presentation</code> value changes with it. The same presentation definition can also be used elsewhere in the model, rather than duplicating the expression.

=== Recommended steps ===

# Identify the short text that users need to recognize an instance. For example, use a car's registration number.
# Add a derived attribute, such as <code>Presentation</code>, when the text requires more than a single stable attribute or will be reused.
# Put the OCL expression for the display text on the derived attribute.
# Set the class's DefaultStringRepresentation to <code>self.Presentation</code>.
# Use <code>self.asString</code> where an expression needs that object as text.
# Change an input value used by the presentation and verify that the derived value and displayed representation update.

== Performance and change tracking ==

'''DefaultStringRepresentation and <code>asString</code> are not subscribed.''' Each use of <code>asString</code> must be reevaluated. This matters when an expression is evaluated often or when it is part of an expression tree that needs efficient change tracking.

Avoid using <code>asString</code> directly in expressions that have high performance requirements. It can prevent the expression tree from subscribing properly to the values on which the text depends.

Use a derived attribute as the subscribed boundary instead. Put the dependencies in the derived attribute's OCL expression and refer to that attribute from DefaultStringRepresentation. For example, use <code>self.Presentation</code> as the default representation rather than repeating an expression that reads several attributes each time <code>asString</code> is evaluated.

{| class="wikitable"
! Situation
! Recommended approach
|-
| You need a readable object name in a message or expression.
| Define a meaningful DefaultStringRepresentation and use <code>object.asString</code>.
|-
| The representation combines values or is used in several places.
| Create a derived <code>Presentation</code> attribute and use <code>self.Presentation</code> in DefaultStringRepresentation.
|-
| The surrounding expression is performance-sensitive.
| Avoid direct <code>asString</code> in the expression tree; use a derived attribute whose dependencies can be tracked.
|}

== Do not confuse similar string features ==

{| class="wikitable"
! Feature
! Use it for
! Example
|-
| [[Documentation:OCLOperators asString|<code>asString</code>]]
| Converting an object or value to its string representation in OCL.
| <code>self.asString</code> returns the text defined by the object's DefaultStringRepresentation.
|-
| [[Documentation:ToString|<code>toString</code>]]
| Formatting a number as text, optionally with a format string.
| <code>5.toString('00')</code> returns <code>'05'</code>.
|-
| [[Documentation:State value as a string|State value as a string]]
| Converting a state-machine state value to text.
| <code>(#New).asString</code>.
|-
| [[Documentation:AsString|<code>&lt;AsString&gt;</code> in ViewModels]]
| The case-sensitive ViewModel pattern used in action names or constraint messages.
| This is not the same feature as the object <code>asString</code> operation; for non-action ViewModel presentation, use Databind labels.
|-
| [[Documentation:ClassFromString|<code>ClassFromString</code>]]
| Converting a string that names a model type back to an actionable OclType when working with model metadata.
| Use it as the inverse direction when a type has first been treated as a string.
|}

== See also ==

* [[Documentation:OCLOperators asString]]
* [[Documentation:ToString]]
* [[Documentation:State value as a string]]
* [[Documentation:AsString]]
* [[Documentation:ClassFromString]]

[[Category:Derivation]]
[[Category:Intermediate-Friendly]]
[[Category:OCL in Designer]]
[[Category:Performance tips for derivations]]
[[Category:Priority 50]]
[[Category:String, numeric, date and time operators]]