m204wiki - User contributions [en]

Talk:Methods

2016-08-29T22:14:41Z

NMichell:

==Comment==
I landed on this page to discover more about the InternalNames block so I’m hesitant to perform an Edit in case I’ve misunderstood it.

It seems to me that the example given in this article is confusing: -

subroutine add(%petrol is float nameRequired optional, -
%oil is float nameRequired optional)
internalNames
%parm.petrol is %petrol
%parm.oil is %oil
end internalNames
...
%petrol = %petrol + %parm.petrol
%oil = %oil + %parm.oil

Surely something like...

%parm.petrol = %valueToBeReturnedToCaller

...would make more sense.

The explanation that follows the example compounds the problem: -

This example illustrates how if petrol and oil were private class variables, the InternalNames block makes it possible to have parameters in a method declaration with the same name, but to avoid naming conflict or confusion between the private class variables and the parameter names.

As I write this, I wonder if the situation envisaged is where the private class has a %petrol variable and the parameter name-mapping is to allow that to be distinct from the %petrol parameter. Hhmmm - that code needs a rewrite.

Happy to be corrected if I’ve missed a trick.

NMichell

e: nickmichell@gmail.com

==Response==
Nick,

I think you're correct that the explanation is a bit confusing – maybe too clever by a half. I think the reason DHS requested this feature is so they could refer to parameters in the code as <code>%parm.whatever</code> but not put the <code>parm.</code> part in the method template. This was especially important for named parameters, where it would have been dumb to do stuff like:
%foo:method(parm.x=%x, parm.y=true)

I think I'd avoid discussing private/public variables altogether here as I think it's a red herring. Certainly one can have a private or public variable called <code>petrol</code>, and while one can refer to it as <code>%petrol</code> in class code, I always advocate using <code>%this:petrol</code>. In such a case, if there is a local variable called <code>%petrol</code>, the only way one can get at the class variable is with <code>%this:petrol</code>. This is pretty standard O-O stuff, and it is the way Java, C++, and other "traditional" O-O languages work.

Sound reasonable? If so, we'll fix.

Thanks

:Hi Alex,

:Yes - removing the references to class variables would clear the waters.

:As an aside, the standard that's now evolved here is to name parameters %i.xyz, %o.abc etc. This serves both to identify them as parameters and as inputs or outputs.

:NMichell

:e: nickmichell@gmail.com

Talk:Methods

2016-08-29T03:05:21Z

NMichell: InterNames

I landed on this page to discover more about the InternalNames block so I’m hesitant to perform an Edit in case I’ve misunderstood it.

It seems to me that the example given in this article is confusing: -

subroutine add(%petrol is float nameRequired optional, -
%oil is float nameRequired optional)
internalNames
%parm.petrol is %petrol
%parm.oil is %oil
end internalNames
...
%petrol = %petrol + %parm.petrol
%oil = %oil + %parm.oil

Surely something like...

%parm.petrol = %valueToBeReturnedToCaller

...would make more sense.

The explanation that follows the example compounds the problem: -

This example illustrates how if petrol and oil were private class variables, the InternalNames block makes it possible to have parameters in a method declaration with the same name, but to avoid naming conflict or confusion between the private class variables and the parameter names.

As I write this, I wonder if the situation envisaged is where the private class has a %petrol variable and the parameter name-mapping is to allow that to be distinct from the %petrol parameter. Hhmmm - that code needs a rewrite.

Happy to be corrected if I’ve missed a trick.

NMichell

e: nickmichell@gmail.com

Enumerations

2014-02-24T02:23:35Z

NMichell: Added just before "Using user enumerations". Absence was causing "cookieShape is enumeration shape" to show as main body text, not code.

Objects may have properties that can have relatively few
values, such as True or False; Yes, No, or Maybe; Red, Green,
or Blue; or Small, Medium, Large, SuperSize.
These properties could be defined with a string datatype, in which case
they would be set to values like <code>'True'</code> or <code>'False'</code>.
Or they could be
defined with a numeric datatype like <var>Float</var>, in which case they would
be set to values like <code>0</code> or <code>1</code>.
Both of these options are unappealing:
<ul>
<li>Using strings ties you to a particular case-sensitive representation
of the values.
<li>Using numbers makes the code unclear, as the meaning of, say, 2 is not
readily apparent.
<li>Neither strings nor numbers provide any compile-time validation of values.
That is, if the value of a property can be either <code>'True'</code>
or <code>'False'</code>,
the compiler will allow the property to be set to <code>'True'</code>,
or <code>'False'</code>, or anything else, for that matter.
</ul>

The special type of class called '''enumerations'''
solves these problems.
An enumeration class doesn't actually describe a set of objects but a set of
values or, more specifically, names for a set of values.
Since values are syntactically nouns, as are objects, enumeration handling is very
similar to object handling.
<var class="product">SOUL</var> supports '''system enumerations''' (pre-defined
in the <var class="product">Model 204</var> nucleus) as well as
'''user enumerations''' (defined within a <var class="product">SOUL</var> request.

==Declaring enumeration variables==
Enumeration variables are declared very much like objects:
variable [Is] Enumeration className [Initial(value)]

The <var>Boolean</var> enumeration is so heavily used that the keyword
<var>Enumeration</var> is optional for <var>Boolean</var> enumeration variables:
variable [Is] Boolean [Initial(value)]


For example:
%myAim is boolean


An <var>Enumeration</var> variable, like an <var>Object</var> variable can be null;
in fact this the the default initial value for all enumeration variables.
This means that certain operations on enumeration variables can result
in null-pointer reference errors.
It also means that, in some sense, all enumerations contain a special value
of <var>Null</var> (though <var>Null</var> behaves somewhat differently from other values).
This means that caution should be used for inequality tests on enumeration
variables as a null will satisfy an inequality test.

Enumeration variables, including <var>Booleans</var>, can have a
compile-time initial value as specified by an <var>Initial</var> clause:
%myAim is boolean initial(true)

Such a clause can also be placed on variables in a class <var>Public</var>, <var>Private</var>, or
<var>Shared</var> block:
class alison
public
variable myaim is boolean initial(true)
...
end public
...
end class


As with other variable types, an <var>Initial</var> clause in a <var>Public</var> or <var>Private</var> block
sets the initial value for the variable when the containing object is
instantiated.

The sections that follow describe how to use enumerations, including the methods
that may be applied to them.
Most of the individual enumeration classes are documented elsewhere: in the
context of the (typically one) system class method
that uses the enumeration.

==Using enumerations==
An explicit <var>New</var> method is '''not''' allowed for enumeration variables.
Instead, they must be set from the possible values for the enumeration:
%well is enumeration boolean
...
%well = %(boolean):true
...
%well = %(boolean):false


Enumeration values are similar to shared properties of an object class and,
as with other shared properties, an enumeration variable can be used instead
of the class name to reference the shared properties:
%well is enumeration boolean
...
%well = %well:true
...
%well = %well:false


Or, because the class can be inferred from the target,
enumerations can be set using just the value name:
%well is enumeration boolean
...
%well = true
...
%well = false


You can also use just the value name
when a method parameter is an enumeration:
class customer
public
subroutine setActive(%active is enumeration boolean)
...
end public
...
end class
...
%myCustomer is object customer
...
%myCustomer:setActive(false)


Often, though, an enumeration will be a property rather than a
parameter.
The previous example would probably be recast as:
class customer
public
property active is enumeration boolean
...
end public
...
end class
...
%myCustomer is object customer
...
%myCustomer:active = false


System enumerations
can be declared with an explicit "system" on their declaration:
%active is enumeration system:boolean


Enumerations have a <var>ToString</var> method that returns the
string form of a value:
%active is enumeration boolean

%active = true

print %active:toString


<div id="imp2str"></div>
<blockquote class="note">'''Note:'''

Explicitly calling the <var>ToString</var> method was formerly required to
display the string form of an enumeration value, and simply
specifying <code>print %active</code> in the example above was an error,
because <code>%active</code> is an object, not a string.

However, now that explicitly specifying
<var>ToString</var> is optional, a statement like <code>print %active</code>
automatically implies <code>print %active:toString</code>.
This is described further in [[#Calling ToString implicitly|Calling ToString implicitly]], below. 
</blockquote>

Enumerations can also have other methods.
One class of such methods are "Is" methods that return
<code>0</code> or <code>1</code> depending on whether the method has a particular
value.

For example, the following method tests if
the value of <code>%active</code> is <code>True</code>:
%active is enumeration boolean
...
if %active:isTrue then


This is almost exactly equivalent to the following:
%active is enumeration boolean
...
if %active eq true then


The one difference between the two forms is that the former would cause
a null-pointer-reference request cancellation if <code>%active</code> had never
been set, while the latter would simply evaluate <code>%active eq true</code>
as false, since a <var>Null</var> value is not equal to <code>True</code>.
'''Note:'''
There is an alternative to using these <var>Is</var> methods for <var>Boolean</var> enumerations
in the context of an <var>If</var> statement:
automatic conversion of
a <var>Boolean</var> <var>True</var> to a 1, and of a <var>False</var> to a 0.
See [[#Using Boolean enumerations|Using Boolean enumerations]]. 

It is possible to use enumerations without ever declaring a variable
with that enumeration.
For example, one can set the <var>UseDefault</var> property of a
<var>[[NamedArraylist class|NamedArraylist]]</var> by just using the enumeration value:
%description is collection NamedArraylist of string len 64
...
%description:useDefault = true


==Common enumeration methods==
The methods listed below are available to all system enumerations. The individual method descriptions follow.
<ul class="nobul">
<li><var>[[#Copy function|Copy]]</var>
<li><var>[[#DeepCopy function|DeepCopy]]</var>
<li><var>[[#FromString function|FromString]]</var>
<li><var>[[#ToString property|ToString]]</var>
</ul>

The [[#Using Boolean enumerations|versatile]] <var>Boolean</var> enumeration has additional methods available.

===Copy function===
This function returns an exact copy of the method object.
It is identical to the <var>[[#DeepCopy function|DeepCopy]]</var> method.
Since enumeration variables simply have values, a <var>Copy</var> or <var>DeepCopy</var> is no
different from an assignment, so enumerations are always copyable and deep
copyable, as described in [[Copying objects|"Copying objects"]].
As such, there is no real reason to do a <var>Copy</var> or <var>DeepCopy</var> of an
enumeration variable, and the presence of these methods simply
makes the copyability of enumeration variables explicit.

====Copy syntax====
%cop = enum:Copy


====Syntax terms====
<table>
<tr><th>%cop</th>
<td>An enumeration variable to contain the copy of ''enum''. <var class="term">%cop</var> does not have to be [[XmlDoc API#XmlDoc states|empty]].
</td></tr>
<tr><th>enum</th>
<td>An enumeration variable or an expression that results in an enumeration.
</td></tr></table>

The method object (<var class="term">enum</var>) may be <var>Null</var>.
The output of a copy of a <var>Null</var> object is a <var>Null</var> object.

===DeepCopy function===
This function returns an exact copy of the method object.
It is identical to the <var>[[#Copy function|Copy]]</var> method.
Since enumeration variables simply have values, a <var>Copy</var> or <var>DeepCopy</var> is no
different from an assignment, so enumerations are always copyable and deep
copyable, as described in [[Copying objects|"Copying objects"]].
As such, there is no real reason to do a <var>Copy</var> or <var>DeepCopy</var> of an
enumeration variable, and the presence of these methods simply
makes the copyability of enumeration variables explicit.

====DeepCopy syntax====
%dcop = enum:DeepCopy


====Syntax terms====
<table>
<tr><th>%dcop</th>
<td>An enumeration variable to contain the deep copy of <var class="term">enum</var>. <var class="term">%dcop</var> does not have to be [[XmlDoc API#XmlDoc states|empty]].
</td></tr>
<tr><th>enum</th>
<td>An enumeration variable or an expression that results in an enumeration.
</td></tr></table>

The method object (<var class="term">enum</var>) may be <var>Null</var>.
The output of a deep copy of a <var>Null</var> object is a <var>Null</var> object.

===FromString function===
<var>FromString</var> is a [[Notation conventions for methods#Shared methods|shared]] function that converts a string argument into a value of the specified enumeration type.
This is the opposite of the enumeration <var>ToString</var> method, which converts an enumeration value to its <var>String</var> representation.


====FromString syntax====
%enum = [%(enumType):]FromString(string)

====Syntax terms====
<table>
<tr><th>%enum</th>
<td>An enumeration variable or expression. </td></tr>
<tr><th><var class="nobr">%(enumType)</var> </th>
<td>This explicit specification of the enumeration type in parentheses denotes a [[Object variables#Virtual Constructor methods|virtual constructor]]. See [[#Usage notes|"Usage notes"]], below, for more information about invoking this function. </td></tr>

<tr><th>string</th>
<td>A [[Longstrings|longstring]] variable that is assigned the current string value of <var class="term">enum</var>.
</td></tr>
</table>

====Usage Notes====
<ul>
<li>As an example, consider the following user-defined enumeration:
enumeration Animal
public
value cat
value dog
value gecko
value parrot
end public
end enumeration


You can populate an <code>Animal</code> enumeration variable with one of the <code>Animal</code> enumeration values by making a call to <var>FromString</var>:
%pet is enumeration animal
%pet = fromString('gecko')

The result of a <var>Print</var> of <code>%pet</code> above is <code>gecko</code>.
<blockquote class="note">'''Note:''' In the method call, <code>fromString</code> might but does '''not''' have to be preceded by <code>%(Animal):</code> to identify the type of enumeration, because the type is determined from the result variable. You could also get the same result from invoking with an already defined enumeration variable, as in:
%pet = %pet:fromString('gecko')
</blockquote>

<li>Only strings that match a value of the particular enumeration type
can be converted. If a string cannot be converted to an enumeration
value, <var>FromString</var> throws an <var>[[InvalidValue class|Invalidvalue]]</var> exception:
%pet = fromString('alien')

<nowiki>***</nowiki> 1 CANCELLING REQUEST: MSIR.0750: Class Animal, function
FromString: InvalidValue exception: ALIEN is not a valid enumeration
value in line 84, procedure ENUM, file MYPROC

</ul>

===ToString property===
This non-settable property examines an enumeration
and returns a printable or testable string representation of its value.

====ToString syntax====
%ls = enum:ToString


====Syntax terms====
<table>
<tr><th>%ls</th>
<td>A [[Longstrings|longstring]] variable that is assigned the current string value of <var class="term">enum</var>.
</td></tr>
<tr><th>enum</th>
<td>An enumeration variable or an expression that results in an enumeration.
</td></tr></table>

<div id="printenum"></div>
====Calling ToString implicitly====
To return a string representation of the value of a <var class="product">SOUL</var> system or user-defined enumeration, you can do either of the following:
<ul>
<li>Explicitly specify the <var>ToString</var> method.

<li>Print (or audit) the value of an enumeration, and <var>ToString</var> is implied,
as shown in the following example:
begin
enumeration color
public
value red
value white
value blue
value green
end public
end enumeration

%x is boolean initial(true)
%z is enumeration color initial(blue)
%daem is object daemon

%daem = new

print %x with ' ' %z
[[PrintText statement|printText]] {~} = {%x}, {~} = {%z}
print %daem:haveDaemon
printText {~} = {%daem:haveDaemon}
end


The <var>Print</var> and <var>PrintText</var> statements above produce these results:
True blue
%x = True, %z = blue
True
%daem:haveDaemon = True


<blockquote class="note">'''Note:'''
In addition, the implicit <var>ToString</var> feature extends beyond enumerations:
upon any attempt to print or audit any object value, <var class="product">SOUL</var> will try to apply a
<var>ToString</var> method to the object.
If the object is an enumeration (as shown above) or is an
instance of a system or user-defined class that has a <var>ToString</var> method,
a <var>ToString</var> is implicitly
applied and the result is a successful print or audit of the object value.

For example, the user-defined class in the following request includes a
<var>ToString</var> method.
The request's <code>printText</code> statement prints <code>%x = a=11, b=22</code>. 
begin
class mumble
public
variable a is float
variable b is float
constructor new(%a is float nameRequired, %b is float)
function tostring is longstring
end public
constructor new(%a is float nameRequired, %b is float)
%this:a = %a
%this:b = %b
end constructor
function tostring is longstring
return 'a=' with %a with ', b=' with %b
end function
end class

%x is object mumble
%x = new(a=11, b=22)
printText {~} = {%x}
end


If the object you try to print or audit directly is not an enumeration or is
an instance of a class that does not have a <var>ToString</var> method (system or
user-written), you receive a compilation error.
For example, if <code>%sl</code> is a <var>Stringlist</var> object, no user <var>ToString</var> method exists,
and your request contains a <code>Print %sl</code> statement, you get a message
like the following: 
*** 1 MSIR.0733: Member TOSTRING not found in class STRINGLIST
print %sl
(FILE = JALWORK, PROCEDURE = FOO, LINE = 28)
*** M204.1042: COMPILATION ERRORS


Finally, if the object you try to print directly is a <var>Unicode</var> variable,

the implicit <var>ToString</var> method returns an EBCDIC character-encoded value for
Unicode characters that do not translate to EBCDIC.
This is described further in [[Unicode#Implicit Unicode conversions|"Implicit Unicode conversions"]]. 
</blockquote>
</ul>

==Boolean enumeration==
The [[Boolean enumeration]] is probably the most commonly used, and so the most important enumeration class. Because of its importance, it is treated specially by <var class="product">SOUL</var>, and is a topic unto itself.

==User enumerations==
While there are a wide variety of system enumerations that can be useful in
many contexts (especially the <var>Boolean</var> enumeration), it is
also possible to define user enumerations in <var class="product">SOUL</var>.
This is done via the <var>Enumeration</var> statement/block, which is very similar to the
<var>Class</var> statement/block (as in [[Classes and Objects|"Classes and objects"]]).

===The Enumeration block===
The <var>Enumeration</var> block can contain <var>Public</var>, <var>Private</var>, <var>Public</var> <var>Shared</var>, and <var>Private</var> <var>Shared</var> blocks, just like any other class.
However, because enumeration classes don't really describe objects, there
can be no instance variables.
That is, the <var>Public</var> and <var>Private</var> blocks cannot contain <var>Variable</var> declarations.

Instead, the <var>Public</var> block must contain one or more <var>Value</var> declarations
whose syntax is:
Value value [attribute]


Each value declared by a <var>Value</var> declaration becomes one of the values of the enumeration.

One or more '''attributes''' (a constant datum of type <var>String</var>, <var>Float</var>, or <var>Enumeration</var>) can be attached to an enumeration value. 

No values or attributes are allowed in the <var>Private</var> or <var>Shared</var> blocks.

'''Note:''' The value in a <var>Value</var> clause is unusual in that the case (lower or upper)
of the characters in its value are saved and used in the implicit <var>ToString</var> method. The same is true for the values in an <var>Attribute</var> clause. 

The following is an example of a simple enumeration:
enumeration shape
public
attribute code is string

value triangle (code='31')
value square (code='44')
value rhombus (code='42')
value rectangle (code='41')
value quadrilateral (code='40')
value pentagon (code='50')
value circle (code='01')
end public
end enumeration


All attributes must be declared before any value is declared. In a given <var>Value</var> clause:
<ul>
<li>A specification for each attribute must be explicitly present.
<li>An attribute may be specified by name or by position; and like a method [[Methods#Named_parameters|named parameter]], an attribute specified with its name may not precede an attribute specified only by position.
<li>An attribute name may not repeat.
</ul>

'''Note:'''
Just as for <var>Class</var> blocks, 
an <var>Enumeration</var> block you declare inside a method or complex subroutine
must be preceded by the keyword <var>Local</var>.
For more information about locally-scoped classes and enumerations,
see [[Local and Common entities#Local classes, enumerations, and structures|"Local classes, enumerations, and structures"]].

===Using user enumerations===
You can use user-defined enumerations just like system enumerations.
That is, variables are declared with the <var>Enumeration</var> keyword and class name:
%cookieShape is enumeration shape


Enumeration values may be assigned to an enumeration variable:
%cookieShape = circle


Such a variable may be printed (<code>Print %cookieShape</code>), and it may be used to access an enumeration attribute:
Print %cookieShape:code


More commonly, enumerations may be used as method parameters:
class cookie
...
subroutine cut(%shape is enumeration shape)
...
end class


And, typically, literal values are used as the arguments when invoking
such a method:
%biscuit is object cookie
...
%biscuit:cut(pentagon)


Enumeration values are not strings, so they are case insensitive.
While the class of an enumeration value can almost always be determined
from context, the class name can always be explicitly specified for a
value:
%cookieShape = %(shape):circle
...
%biscuit:cut(%(shape):pentagon)


Like system enumerations, user enumeration variables can be in a state where
they have no value, that is, they can be null.
In fact, that is the initial value of any enumeration variable.

As with system enumerations, you can change the default initial value
with the <var>Initial</var> clause on the variable declaration:
variable [Is] Enumeration enumerationName [Initial(value)]


You can set the default initial value for local variables:
%cutout is enumeration shape initial(square)


And you can set it for variables in class blocks:
class cookie
public
variable shape is enumeration shape initial(round)
...
end public
...
end class


Of course, instance-specific (non-<var>Shared</var>) initial values are set
for each instance of the class when it is created.

===Enumeration methods===
Enumeration classes can also contain methods that operate on
or are related to the enumeration values.
For example, the <code>Shape</code> enumeration can have a method that returns the number
of sides in a shape:
enumeration shape
public
...
function sides is float
end public
function sides is float
if %this eq circle then
return 0
end if
if %this eq triangle then
return 3
end if
...
end function
end enumeration


As this example illustrates, the implicit <code>%this</code> variable for enumeration
methods contains not an object reference but an enumeration value.

Enumeration methods can be applied to enumeration values as well as enumeration variables.
This is one case, however, where the enumeration value '''must'''
be qualified with the class name, because it appears in a context where
the class cannot be determined otherwise:
print %(shape):rhombus:sides


And, as with objects, an enumeration method could be applied to the output
of another method that returns an enumeration value.
For example, if the <code>PickCookie</code> method of the <code>Jar</code> class returns a
<code>Cookie</code> object, and the <code>Shape</code> method of the <code>Cookie</code> class returns a
<code>Shape</code> enumeration value, the following prints the number of sides of
a picked cookie:
%jar is object jar
...
print %jar:pickCookie:shape:sides


===Inverse attribute methods===
Inverse attribute methods let you derive an enumeration <var>Value</var> based on the value of one of
its <var>[[#The Enumeration block|Attributes]]</var>. To do so, you declare an <code>inverse</code> method at the end of an <var>Attribute</var> declaration, then you invoke the method, as is shown with the <code>fromOz</code> method in this example:
enumeration coffee
public
attribute oz is float inverse fromOz

value tall (12)
value grande (16)
value venti (20)
end public
end enumeration

%order is enumeration coffee

%order = fromOz(16)
Print %order


The result is: 
grande

====Usage notes====
<ul>
<li>Inverse attribute calls throw an <var>[[InvalidValue class|InvalidValue]]</var> exception if the given value cannot be inverted.
<li>Since the same attribute value may appear in more than one <var>Value</var> specification,
inverse attribute calls are checked at compile time for such ambiguous
value parameters. If you try to invert an attribute value that has multiple possible inverses,
you receive <code>MSIR.1029: Attribute error: Duplicate values specified for
invertible attribute</code> when you attempt to compile the offending enumeration.
</ul>

===Automatic methods===
Several methods are automatically provided for <var class="product">SOUL</var> enumeration
classes.
Some of these are identical to common methods available in most system
enumerations.
These methods are:
<table class="thJustBold">
<tr>
<th>Copy</th>
<td>Performs a “copy” of the enumeration value. Since enumeration variables simply have values, a <var>Copy</var> or <var>DeepCopy</var> is no different from an assignment, so enumerations are always copyable and deep
copyable, as described in [[Copying objects|"Copying objects"]]. As such, there is no real reason to do a <var>Copy</var> or <var>DeepCopy</var> of an enumeration variable, and the presence of these methods simply makes the copyability of enumeration variables explicit.</td>
</tr>
<tr>
<th>DeepCopy</th>
<td>Performs a “copy” of the enumeration value. Since enumeration variables simply have values, a <var>Copy</var> or <var>DeepCopy</var> is no different from an assignment, so enumerations are always copyable and deep
copyable, as described in [[Copying objects|"Copying objects"]]. As such, there is no real reason to do a <var>Copy</var> <var>Or</var> DeepCopy of an enumeration variable, and the presence of these methods simply makes the copyability of enumeration variables explicit.</td>
</tr>
<tr>
<th>FromOrdinal</th>
<td>This shared method is the inverse of the <var>Ordinal</var> method and converts an ordinal number to an enumeration value. The class specified in the shared method invocation determines the class of the result enumeration value.
By default, the <var>FromOrdinal</var> method behaves as if it is a private method. That is, it can only be accessed inside the class. This can be overridden by specifying <code>Allow Ordinal</code> in the <var>Public</var> block.

This method was introduced in <var class="product">[[Sirius Mods]]</var> Version 8.1.</td>
</tr>
<tr>
<th>NumberOfValues</th>
<td>This shared method returns the number of values in the enumeration class. The class specified in the shared method invocation determines the class whose value count is returned.
By default, the <var>NumberOfValues</var> method behaves as if it is a private method. That is, it can only be accessed inside the class. This can be overridden by specifying <code>Allow Ordinal</code> in the <var>Public</var> block.

This method was introduced in <var class="product">[[Sirius Mods]]</var> Version 8.1.</td>
</tr>
<tr>
<th>Ordinal</th>
<td>Returns the ordinal position of the <var>Value</var> clause associated with the value of the enumeration. For example, if an enumeration was declared as follows:
enumeration shot
public
value rock
value paper
value scissors
end public
end enumeration

The ordinal for a value of <var>Rock</var> is 1, for <var>Paper</var> 2, and <var>Scissors</var> 3.
By default, the <var>Ordinal</var> method behaves as if it is a private method. That is, it can only be accessed inside the class. This can be overridden by specifying <code>Allow Ordinal</code> in the <var>Public</var> block, as described below.</td>
</tr>
<tr>
<th>ToString</th>
<td>Returns a string representation of the enumeration value.
The value returned uses the same case for the characters as was used on the <var>Value</var> declaration.</td>
</tr>
</table>

====Using the Ordinal method====
The <var>Ordinal</var> method, especially, bears further discussion.
It can be very useful in writing enumeration methods, especially in
conjunction with the <var>Jump</var> statement.
For example, the <code>Sides</code> method in the <code>Shape</code> enumeration above could have been
written like:
function sides is float
jump to (three, four, four, four, four, five, none) %this:ordinal
three: return 3
four: return 4
five: return 5
none: return 0
end function


While this might justifiably be disparaged as questionable programming technique,
it '''is''' very efficient and simple.

One disadvantage of such a technique is that the code is now highly
dependent on the order of the value declarations.
This means that it becomes difficult to rearrange the value declarations,
or to insert one into the list after there is code that uses the <var>Ordinal</var>
method on an enumeration class.
For this reason, the <var>Ordinal</var> method behaves like a private method, by
default.
That is, it is only available to methods inside the <var>Enumeration</var> class
block.

One use of the <var>Ordinal</var> method that you might want to make public occurs
when the enumeration values have a natural ordering.
Consider, for example, the following enumeration:
enumeration volume
public
value low
value medium
value high
value deafening
end public
end enumeration


With such an enumeration, one might want to use an enumeration value's
ordinality in comparisons.
To allow this to be done, the <var>Allow Ordinal</var> directive must be placed in
the <var>Public</var> block of the enumeration definition:
enumeration volume
public
allow ordinal
value low
value medium
value high
value deafening
end public
end enumeration


Then, code like the following can be used outside the class:
%leftSpeakerVolume is enumeration volume
%rightSpeakerVolume is enumeration volume
...
if %leftSpeakerVolume:ordinal gt -
%rightSpeakerVolume:ordinal then
...
end if


Of course, the same effect could be achieved by adding a different method
to the enumeration, called perhaps <code>Level</code>, that returned a non-ordinal value
that could still be used for comparisons:
%leftSpeakerVolume is enumeration volume
%rightSpeakerVolume is enumeration volume
...
if %leftSpeakerVolume:level gt -
%rightSpeakerVolume:level then
...
end if


The advantage of this approach is that a non-ordinal value is less likely
to be misused for computed jumps, and the levels leave space to add values
associated with new enumeration values.
Another approach that avoids exposing the ordinal values of an
enumeration is to provide a comparison method to compare two enumeration
values.

====Using the FromOrdinal and NumberOfValues methods====
The <var>FromOrdinal</var> and <var>NumberOfValues</var> methods were introduced in <var class="product">Sirius Mods</var> version 8.1.

These two methods make it easy to enumerate all the values in an enumeration class without having to maintain code that has a list of all the values. Because these methods could be used to build an equivalent to the automatic <var>Ordinal</var> method, they require <var>Allow Ordinal</var> to be set in the enumeration class against which they are used (see example below).

The <var>FromOrdinal</var> method is a [[Shared_class_members|shared method]] and has a single input argument: the ordinal number of the value to which to set the target enumeration variable. For example, if one has a <var>Stooge</var> enmeration:
enumeration stooge
public
value moe
value larry
value curly
value shemp
allow ordinal
end public
end enumeration

then the following sequence:
%favorite is enumeration stooge
%favorite = %(stooge):fromOrdinal(3)
printText {~=%favorite}

would print:
%favorite=curly

If an invalid ordinal number is specified as input to the <var>FromOrdinal</var> method, an <var>[[InvalidValue_class|InvalidValue]]</var> exception is thrown. For example, the following:
%favorite = %(stooge):fromOrdinal(-5)

would result in the following request canceling error message:
MSIR.0750: Class Stooge, function FromOrdinal: InvalidValue exception: -5 is not -
a valid ordinal number for class Stooge ...

You can catch such an exception to produce a list of all values in an enumeration class:
for %i from 1 to 99999999
try printText {%(stooge):fromOrdinal(%i)}
catch invalidValue; loop end
end try
end for

This outputs:
moe
larry
curly
shemp

The <var>NumberOfValues</var> automatic method for enumerations lets you do this a little more tidily:
for %i from 1 to %(stooge):numberOfValues
printText {%(stooge):fromOrdinal(%i)}
end for

The <var>NumberOfValues</var> method has no parameters.

<var>NumberOfValues</var> and <var>FromOrdinal</var> can be used to build an [[Arraylist_class|Arraylist]] that contains one item for each value in the enumeration class:
%stoogeValues is arraylist of enumeration stooge
...
%stoogeValues = new
for %i from 1 to %(stooge):numberOfValues
%stoogeValues:add(%(stooge):fromOrdinal(%i))
end for

One advantage of having such an <var>Arraylist</var> is that it can easily be sorted or searched. For example, the following displays the stooge values sorted in ascending character order:
%stoogevalues:[[SortNew_(GenericNamedArraylist_function)|sortNew]](ascending(toString)):print

This displays:
1: curly
2: larry
3: moe
4: shemp


==See also==
<ul>
<li>[[Object oriented programming in SOUL]]
</ul>

[[Category:SOUL object-oriented programming topics]]

Enumerations

2014-02-24T02:22:23Z

NMichell: Undo revision 67592 by NMichell (talk)

Objects may have properties that can have relatively few
values, such as True or False; Yes, No, or Maybe; Red, Green,
or Blue; or Small, Medium, Large, SuperSize.
These properties could be defined with a string datatype, in which case
they would be set to values like <code>'True'</code> or <code>'False'</code>.
Or they could be
defined with a numeric datatype like <var>Float</var>, in which case they would
be set to values like <code>0</code> or <code>1</code>.
Both of these options are unappealing:
<ul>
<li>Using strings ties you to a particular case-sensitive representation
of the values.
<li>Using numbers makes the code unclear, as the meaning of, say, 2 is not
readily apparent.
<li>Neither strings nor numbers provide any compile-time validation of values.
That is, if the value of a property can be either <code>'True'</code>
or <code>'False'</code>,
the compiler will allow the property to be set to <code>'True'</code>,
or <code>'False'</code>, or anything else, for that matter.
</ul>

The special type of class called '''enumerations'''
solves these problems.
An enumeration class doesn't actually describe a set of objects but a set of
values or, more specifically, names for a set of values.
Since values are syntactically nouns, as are objects, enumeration handling is very
similar to object handling.
<var class="product">SOUL</var> supports '''system enumerations''' (pre-defined
in the <var class="product">Model 204</var> nucleus) as well as
'''user enumerations''' (defined within a <var class="product">SOUL</var> request.

==Declaring enumeration variables==
Enumeration variables are declared very much like objects:
variable [Is] Enumeration className [Initial(value)]

The <var>Boolean</var> enumeration is so heavily used that the keyword
<var>Enumeration</var> is optional for <var>Boolean</var> enumeration variables:
variable [Is] Boolean [Initial(value)]


For example:
%myAim is boolean


An <var>Enumeration</var> variable, like an <var>Object</var> variable can be null;
in fact this the the default initial value for all enumeration variables.
This means that certain operations on enumeration variables can result
in null-pointer reference errors.
It also means that, in some sense, all enumerations contain a special value
of <var>Null</var> (though <var>Null</var> behaves somewhat differently from other values).
This means that caution should be used for inequality tests on enumeration
variables as a null will satisfy an inequality test.

Enumeration variables, including <var>Booleans</var>, can have a
compile-time initial value as specified by an <var>Initial</var> clause:
%myAim is boolean initial(true)

Such a clause can also be placed on variables in a class <var>Public</var>, <var>Private</var>, or
<var>Shared</var> block:
class alison
public
variable myaim is boolean initial(true)
...
end public
...
end class


As with other variable types, an <var>Initial</var> clause in a <var>Public</var> or <var>Private</var> block
sets the initial value for the variable when the containing object is
instantiated.

The sections that follow describe how to use enumerations, including the methods
that may be applied to them.
Most of the individual enumeration classes are documented elsewhere: in the
context of the (typically one) system class method
that uses the enumeration.

==Using enumerations==
An explicit <var>New</var> method is '''not''' allowed for enumeration variables.
Instead, they must be set from the possible values for the enumeration:
%well is enumeration boolean
...
%well = %(boolean):true
...
%well = %(boolean):false


Enumeration values are similar to shared properties of an object class and,
as with other shared properties, an enumeration variable can be used instead
of the class name to reference the shared properties:
%well is enumeration boolean
...
%well = %well:true
...
%well = %well:false


Or, because the class can be inferred from the target,
enumerations can be set using just the value name:
%well is enumeration boolean
...
%well = true
...
%well = false


You can also use just the value name
when a method parameter is an enumeration:
class customer
public
subroutine setActive(%active is enumeration boolean)
...
end public
...
end class
...
%myCustomer is object customer
...
%myCustomer:setActive(false)


Often, though, an enumeration will be a property rather than a
parameter.
The previous example would probably be recast as:
class customer
public
property active is enumeration boolean
...
end public
...
end class
...
%myCustomer is object customer
...
%myCustomer:active = false


System enumerations
can be declared with an explicit "system" on their declaration:
%active is enumeration system:boolean


Enumerations have a <var>ToString</var> method that returns the
string form of a value:
%active is enumeration boolean

%active = true

print %active:toString


<div id="imp2str"></div>
<blockquote class="note">'''Note:'''

Explicitly calling the <var>ToString</var> method was formerly required to
display the string form of an enumeration value, and simply
specifying <code>print %active</code> in the example above was an error,
because <code>%active</code> is an object, not a string.

However, now that explicitly specifying
<var>ToString</var> is optional, a statement like <code>print %active</code>
automatically implies <code>print %active:toString</code>.
This is described further in [[#Calling ToString implicitly|Calling ToString implicitly]], below. 
</blockquote>

Enumerations can also have other methods.
One class of such methods are "Is" methods that return
<code>0</code> or <code>1</code> depending on whether the method has a particular
value.

For example, the following method tests if
the value of <code>%active</code> is <code>True</code>:
%active is enumeration boolean
...
if %active:isTrue then


This is almost exactly equivalent to the following:
%active is enumeration boolean
...
if %active eq true then


The one difference between the two forms is that the former would cause
a null-pointer-reference request cancellation if <code>%active</code> had never
been set, while the latter would simply evaluate <code>%active eq true</code>
as false, since a <var>Null</var> value is not equal to <code>True</code>.
'''Note:'''
There is an alternative to using these <var>Is</var> methods for <var>Boolean</var> enumerations
in the context of an <var>If</var> statement:
automatic conversion of
a <var>Boolean</var> <var>True</var> to a 1, and of a <var>False</var> to a 0.
See [[#Using Boolean enumerations|Using Boolean enumerations]]. 

It is possible to use enumerations without ever declaring a variable
with that enumeration.
For example, one can set the <var>UseDefault</var> property of a
<var>[[NamedArraylist class|NamedArraylist]]</var> by just using the enumeration value:
%description is collection NamedArraylist of string len 64
...
%description:useDefault = true


==Common enumeration methods==
The methods listed below are available to all system enumerations. The individual method descriptions follow.
<ul class="nobul">
<li><var>[[#Copy function|Copy]]</var>
<li><var>[[#DeepCopy function|DeepCopy]]</var>
<li><var>[[#FromString function|FromString]]</var>
<li><var>[[#ToString property|ToString]]</var>
</ul>

The [[#Using Boolean enumerations|versatile]] <var>Boolean</var> enumeration has additional methods available.

===Copy function===
This function returns an exact copy of the method object.
It is identical to the <var>[[#DeepCopy function|DeepCopy]]</var> method.
Since enumeration variables simply have values, a <var>Copy</var> or <var>DeepCopy</var> is no
different from an assignment, so enumerations are always copyable and deep
copyable, as described in [[Copying objects|"Copying objects"]].
As such, there is no real reason to do a <var>Copy</var> or <var>DeepCopy</var> of an
enumeration variable, and the presence of these methods simply
makes the copyability of enumeration variables explicit.

====Copy syntax====
%cop = enum:Copy


====Syntax terms====
<table>
<tr><th>%cop</th>
<td>An enumeration variable to contain the copy of ''enum''. <var class="term">%cop</var> does not have to be [[XmlDoc API#XmlDoc states|empty]].
</td></tr>
<tr><th>enum</th>
<td>An enumeration variable or an expression that results in an enumeration.
</td></tr></table>

The method object (<var class="term">enum</var>) may be <var>Null</var>.
The output of a copy of a <var>Null</var> object is a <var>Null</var> object.

===DeepCopy function===
This function returns an exact copy of the method object.
It is identical to the <var>[[#Copy function|Copy]]</var> method.
Since enumeration variables simply have values, a <var>Copy</var> or <var>DeepCopy</var> is no
different from an assignment, so enumerations are always copyable and deep
copyable, as described in [[Copying objects|"Copying objects"]].
As such, there is no real reason to do a <var>Copy</var> or <var>DeepCopy</var> of an
enumeration variable, and the presence of these methods simply
makes the copyability of enumeration variables explicit.

====DeepCopy syntax====
%dcop = enum:DeepCopy


====Syntax terms====
<table>
<tr><th>%dcop</th>
<td>An enumeration variable to contain the deep copy of <var class="term">enum</var>. <var class="term">%dcop</var> does not have to be [[XmlDoc API#XmlDoc states|empty]].
</td></tr>
<tr><th>enum</th>
<td>An enumeration variable or an expression that results in an enumeration.
</td></tr></table>

The method object (<var class="term">enum</var>) may be <var>Null</var>.
The output of a deep copy of a <var>Null</var> object is a <var>Null</var> object.

===FromString function===
<var>FromString</var> is a [[Notation conventions for methods#Shared methods|shared]] function that converts a string argument into a value of the specified enumeration type.
This is the opposite of the enumeration <var>ToString</var> method, which converts an enumeration value to its <var>String</var> representation.


====FromString syntax====
%enum = [%(enumType):]FromString(string)

====Syntax terms====
<table>
<tr><th>%enum</th>
<td>An enumeration variable or expression. </td></tr>
<tr><th><var class="nobr">%(enumType)</var> </th>
<td>This explicit specification of the enumeration type in parentheses denotes a [[Object variables#Virtual Constructor methods|virtual constructor]]. See [[#Usage notes|"Usage notes"]], below, for more information about invoking this function. </td></tr>

<tr><th>string</th>
<td>A [[Longstrings|longstring]] variable that is assigned the current string value of <var class="term">enum</var>.
</td></tr>
</table>

====Usage Notes====
<ul>
<li>As an example, consider the following user-defined enumeration:
enumeration Animal
public
value cat
value dog
value gecko
value parrot
end public
end enumeration


You can populate an <code>Animal</code> enumeration variable with one of the <code>Animal</code> enumeration values by making a call to <var>FromString</var>:
%pet is enumeration animal
%pet = fromString('gecko')

The result of a <var>Print</var> of <code>%pet</code> above is <code>gecko</code>.
<blockquote class="note">'''Note:''' In the method call, <code>fromString</code> might but does '''not''' have to be preceded by <code>%(Animal):</code> to identify the type of enumeration, because the type is determined from the result variable. You could also get the same result from invoking with an already defined enumeration variable, as in:
%pet = %pet:fromString('gecko')
</blockquote>

<li>Only strings that match a value of the particular enumeration type
can be converted. If a string cannot be converted to an enumeration
value, <var>FromString</var> throws an <var>[[InvalidValue class|Invalidvalue]]</var> exception:
%pet = fromString('alien')

<nowiki>***</nowiki> 1 CANCELLING REQUEST: MSIR.0750: Class Animal, function
FromString: InvalidValue exception: ALIEN is not a valid enumeration
value in line 84, procedure ENUM, file MYPROC

</ul>

===ToString property===
This non-settable property examines an enumeration
and returns a printable or testable string representation of its value.

====ToString syntax====
%ls = enum:ToString


====Syntax terms====
<table>
<tr><th>%ls</th>
<td>A [[Longstrings|longstring]] variable that is assigned the current string value of <var class="term">enum</var>.
</td></tr>
<tr><th>enum</th>
<td>An enumeration variable or an expression that results in an enumeration.
</td></tr></table>

<div id="printenum"></div>
====Calling ToString implicitly====
To return a string representation of the value of a <var class="product">SOUL</var> system or user-defined enumeration, you can do either of the following:
<ul>
<li>Explicitly specify the <var>ToString</var> method.

<li>Print (or audit) the value of an enumeration, and <var>ToString</var> is implied,
as shown in the following example:
begin
enumeration color
public
value red
value white
value blue
value green
end public
end enumeration

%x is boolean initial(true)
%z is enumeration color initial(blue)
%daem is object daemon

%daem = new

print %x with ' ' %z
[[PrintText statement|printText]] {~} = {%x}, {~} = {%z}
print %daem:haveDaemon
printText {~} = {%daem:haveDaemon}
end


The <var>Print</var> and <var>PrintText</var> statements above produce these results:
True blue
%x = True, %z = blue
True
%daem:haveDaemon = True


<blockquote class="note">'''Note:'''
In addition, the implicit <var>ToString</var> feature extends beyond enumerations:
upon any attempt to print or audit any object value, <var class="product">SOUL</var> will try to apply a
<var>ToString</var> method to the object.
If the object is an enumeration (as shown above) or is an
instance of a system or user-defined class that has a <var>ToString</var> method,
a <var>ToString</var> is implicitly
applied and the result is a successful print or audit of the object value.

For example, the user-defined class in the following request includes a
<var>ToString</var> method.
The request's <code>printText</code> statement prints <code>%x = a=11, b=22</code>. 
begin
class mumble
public
variable a is float
variable b is float
constructor new(%a is float nameRequired, %b is float)
function tostring is longstring
end public
constructor new(%a is float nameRequired, %b is float)
%this:a = %a
%this:b = %b
end constructor
function tostring is longstring
return 'a=' with %a with ', b=' with %b
end function
end class

%x is object mumble
%x = new(a=11, b=22)
printText {~} = {%x}
end


If the object you try to print or audit directly is not an enumeration or is
an instance of a class that does not have a <var>ToString</var> method (system or
user-written), you receive a compilation error.
For example, if <code>%sl</code> is a <var>Stringlist</var> object, no user <var>ToString</var> method exists,
and your request contains a <code>Print %sl</code> statement, you get a message
like the following: 
*** 1 MSIR.0733: Member TOSTRING not found in class STRINGLIST
print %sl
(FILE = JALWORK, PROCEDURE = FOO, LINE = 28)
*** M204.1042: COMPILATION ERRORS


Finally, if the object you try to print directly is a <var>Unicode</var> variable,

the implicit <var>ToString</var> method returns an EBCDIC character-encoded value for
Unicode characters that do not translate to EBCDIC.
This is described further in [[Unicode#Implicit Unicode conversions|"Implicit Unicode conversions"]]. 
</blockquote>
</ul>

==Boolean enumeration==
The [[Boolean enumeration]] is probably the most commonly used, and so the most important enumeration class. Because of its importance, it is treated specially by <var class="product">SOUL</var>, and is a topic unto itself.

==User enumerations==
While there are a wide variety of system enumerations that can be useful in
many contexts (especially the <var>Boolean</var> enumeration), it is
also possible to define user enumerations in <var class="product">SOUL</var>.
This is done via the <var>Enumeration</var> statement/block, which is very similar to the
<var>Class</var> statement/block (as in [[Classes and Objects|"Classes and objects"]]).

===The Enumeration block===
The <var>Enumeration</var> block can contain <var>Public</var>, <var>Private</var>, <var>Public</var> <var>Shared</var>, and <var>Private</var> <var>Shared</var> blocks, just like any other class.
However, because enumeration classes don't really describe objects, there
can be no instance variables.
That is, the <var>Public</var> and <var>Private</var> blocks cannot contain <var>Variable</var> declarations.

Instead, the <var>Public</var> block must contain one or more <var>Value</var> declarations
whose syntax is:
Value value [attribute]


Each value declared by a <var>Value</var> declaration becomes one of the values of the enumeration.

One or more '''attributes''' (a constant datum of type <var>String</var>, <var>Float</var>, or <var>Enumeration</var>) can be attached to an enumeration value. 

No values or attributes are allowed in the <var>Private</var> or <var>Shared</var> blocks.

'''Note:''' The value in a <var>Value</var> clause is unusual in that the case (lower or upper)
of the characters in its value are saved and used in the implicit <var>ToString</var> method. The same is true for the values in an <var>Attribute</var> clause. 

The following is an example of a simple enumeration:
enumeration shape
public
attribute code is string

value triangle (code='31')
value square (code='44')
value rhombus (code='42')
value rectangle (code='41')
value quadrilateral (code='40')
value pentagon (code='50')
value circle (code='01')
end public
end enumeration


All attributes must be declared before any value is declared. In a given <var>Value</var> clause:
<ul>
<li>A specification for each attribute must be explicitly present.
<li>An attribute may be specified by name or by position; and like a method [[Methods#Named_parameters|named parameter]], an attribute specified with its name may not precede an attribute specified only by position.
<li>An attribute name may not repeat.
</ul>

'''Note:'''
Just as for <var>Class</var> blocks, 
an <var>Enumeration</var> block you declare inside a method or complex subroutine
must be preceded by the keyword <var>Local</var>.
For more information about locally-scoped classes and enumerations,
see [[Local and Common entities#Local classes, enumerations, and structures|"Local classes, enumerations, and structures"]].

===Using user enumerations===
You can use user-defined enumerations just like system enumerations.
That is, variables are declared with the <var>Enumeration</var> keyword and class name:
%cookieShape is enumeration shape


Enumeration values may be assigned to an enumeration variable:
%cookieShape = circle


Such a variable may be printed (<code>Print %cookieShape</code>), and it may be used to access an enumeration attribute:
Print %cookieShape:code


More commonly, enumerations may be used as method parameters:
class cookie
...
subroutine cut(%shape is enumeration shape)
...
end class


And, typically, literal values are used as the arguments when invoking
such a method:
%biscuit is object cookie
...
%biscuit:cut(pentagon)


Enumeration values are not strings, so they are case insensitive.
While the class of an enumeration value can almost always be determined
from context, the class name can always be explicitly specified for a
value:
%cookieShape = %(shape):circle
...
%biscuit:cut(%(shape):pentagon)


Like system enumerations, user enumeration variables can be in a state where
they have no value, that is, they can be null.
In fact, that is the initial value of any enumeration variable.

As with system enumerations, you can change the default initial value
with the <var>Initial</var> clause on the variable declaration:
variable [Is] Enumeration enumerationName [Initial(value)]


You can set the default initial value for local variables:
%cutout is enumeration shape initial(square)


And you can set it for variables in class blocks:
class cookie
public
variable shape is enumeration shape initial(round)
...
end public
...
end class


Of course, instance-specific (non-<var>Shared</var>) initial values are set
for each instance of the class when it is created.

===Enumeration methods===
Enumeration classes can also contain methods that operate on
or are related to the enumeration values.
For example, the <code>Shape</code> enumeration can have a method that returns the number
of sides in a shape:
enumeration shape
public
...
function sides is float
end public
function sides is float
if %this eq circle then
return 0
end if
if %this eq triangle then
return 3
end if
...
end function
end enumeration


As this example illustrates, the implicit <code>%this</code> variable for enumeration
methods contains not an object reference but an enumeration value.

Enumeration methods can be applied to enumeration values as well as enumeration variables.
This is one case, however, where the enumeration value '''must'''
be qualified with the class name, because it appears in a context where
the class cannot be determined otherwise:
print %(shape):rhombus:sides


And, as with objects, an enumeration method could be applied to the output
of another method that returns an enumeration value.
For example, if the <code>PickCookie</code> method of the <code>Jar</code> class returns a
<code>Cookie</code> object, and the <code>Shape</code> method of the <code>Cookie</code> class returns a
<code>Shape</code> enumeration value, the following prints the number of sides of
a picked cookie:
%jar is object jar
...
print %jar:pickCookie:shape:sides


===Inverse attribute methods===
Inverse attribute methods let you derive an enumeration <var>Value</var> based on the value of one of
its <var>[[#The Enumeration block|Attributes]]</var>. To do so, you declare an <code>inverse</code> method at the end of an <var>Attribute</var> declaration, then you invoke the method, as is shown with the <code>fromOz</code> method in this example:
enumeration coffee
public
attribute oz is float inverse fromOz

value tall (12)
value grande (16)
value venti (20)
end public
end enumeration

%order is enumeration coffee

%order = fromOz(16)
Print %order


The result is: 
grande

====Usage notes====
<ul>
<li>Inverse attribute calls throw an <var>[[InvalidValue class|InvalidValue]]</var> exception if the given value cannot be inverted.
<li>Since the same attribute value may appear in more than one <var>Value</var> specification,
inverse attribute calls are checked at compile time for such ambiguous
value parameters. If you try to invert an attribute value that has multiple possible inverses,
you receive <code>MSIR.1029: Attribute error: Duplicate values specified for
invertible attribute</code> when you attempt to compile the offending enumeration.
</ul>

===Automatic methods===
Several methods are automatically provided for <var class="product">SOUL</var> enumeration
classes.
Some of these are identical to common methods available in most system
enumerations.
These methods are:
<table class="thJustBold">
<tr>
<th>Copy</th>
<td>Performs a “copy” of the enumeration value. Since enumeration variables simply have values, a <var>Copy</var> or <var>DeepCopy</var> is no different from an assignment, so enumerations are always copyable and deep
copyable, as described in [[Copying objects|"Copying objects"]]. As such, there is no real reason to do a <var>Copy</var> or <var>DeepCopy</var> of an enumeration variable, and the presence of these methods simply makes the copyability of enumeration variables explicit.</td>
</tr>
<tr>
<th>DeepCopy</th>
<td>Performs a “copy” of the enumeration value. Since enumeration variables simply have values, a <var>Copy</var> or <var>DeepCopy</var> is no different from an assignment, so enumerations are always copyable and deep
copyable, as described in [[Copying objects|"Copying objects"]]. As such, there is no real reason to do a <var>Copy</var> <var>Or</var> DeepCopy of an enumeration variable, and the presence of these methods simply makes the copyability of enumeration variables explicit.</td>
</tr>
<tr>
<th>FromOrdinal</th>
<td>This shared method is the inverse of the <var>Ordinal</var> method and converts an ordinal number to an enumeration value. The class specified in the shared method invocation determines the class of the result enumeration value.
By default, the <var>FromOrdinal</var> method behaves as if it is a private method. That is, it can only be accessed inside the class. This can be overridden by specifying <code>Allow Ordinal</code> in the <var>Public</var> block.

This method was introduced in <var class="product">[[Sirius Mods]]</var> Version 8.1.</td>
</tr>
<tr>
<th>NumberOfValues</th>
<td>This shared method returns the number of values in the enumeration class. The class specified in the shared method invocation determines the class whose value count is returned.
By default, the <var>NumberOfValues</var> method behaves as if it is a private method. That is, it can only be accessed inside the class. This can be overridden by specifying <code>Allow Ordinal</code> in the <var>Public</var> block.

This method was introduced in <var class="product">[[Sirius Mods]]</var> Version 8.1.</td>
</tr>
<tr>
<th>Ordinal</th>
<td>Returns the ordinal position of the <var>Value</var> clause associated with the value of the enumeration. For example, if an enumeration was declared as follows:
enumeration shot
public
value rock
value paper
value scissors
end public
end enumeration

The ordinal for a value of <var>Rock</var> is 1, for <var>Paper</var> 2, and <var>Scissors</var> 3.
By default, the <var>Ordinal</var> method behaves as if it is a private method. That is, it can only be accessed inside the class. This can be overridden by specifying <code>Allow Ordinal</code> in the <var>Public</var> block, as described below.</td>
</tr>
<tr>
<th>ToString</th>
<td>Returns a string representation of the enumeration value.
The value returned uses the same case for the characters as was used on the <var>Value</var> declaration.</td>
</tr>
</table>

====Using the Ordinal method====
The <var>Ordinal</var> method, especially, bears further discussion.
It can be very useful in writing enumeration methods, especially in
conjunction with the <var>Jump</var> statement.
For example, the <code>Sides</code> method in the <code>Shape</code> enumeration above could have been
written like:
function sides is float
jump to (three, four, four, four, four, five, none) %this:ordinal
three: return 3
four: return 4
five: return 5
none: return 0
end function


While this might justifiably be disparaged as questionable programming technique,
it '''is''' very efficient and simple.

One disadvantage of such a technique is that the code is now highly
dependent on the order of the value declarations.
This means that it becomes difficult to rearrange the value declarations,
or to insert one into the list after there is code that uses the <var>Ordinal</var>
method on an enumeration class.
For this reason, the <var>Ordinal</var> method behaves like a private method, by
default.
That is, it is only available to methods inside the <var>Enumeration</var> class
block.

One use of the <var>Ordinal</var> method that you might want to make public occurs
when the enumeration values have a natural ordering.
Consider, for example, the following enumeration:
enumeration volume
public
value low
value medium
value high
value deafening
end public
end enumeration


With such an enumeration, one might want to use an enumeration value's
ordinality in comparisons.
To allow this to be done, the <var>Allow Ordinal</var> directive must be placed in
the <var>Public</var> block of the enumeration definition:
enumeration volume
public
allow ordinal
value low
value medium
value high
value deafening
end public
end enumeration


Then, code like the following can be used outside the class:
%leftSpeakerVolume is enumeration volume
%rightSpeakerVolume is enumeration volume
...
if %leftSpeakerVolume:ordinal gt -
%rightSpeakerVolume:ordinal then
...
end if


Of course, the same effect could be achieved by adding a different method
to the enumeration, called perhaps <code>Level</code>, that returned a non-ordinal value
that could still be used for comparisons:
%leftSpeakerVolume is enumeration volume
%rightSpeakerVolume is enumeration volume
...
if %leftSpeakerVolume:level gt -
%rightSpeakerVolume:level then
...
end if


The advantage of this approach is that a non-ordinal value is less likely
to be misused for computed jumps, and the levels leave space to add values
associated with new enumeration values.
Another approach that avoids exposing the ordinal values of an
enumeration is to provide a comparison method to compare two enumeration
values.

====Using the FromOrdinal and NumberOfValues methods====
The <var>FromOrdinal</var> and <var>NumberOfValues</var> methods were introduced in <var class="product">Sirius Mods</var> version 8.1.

These two methods make it easy to enumerate all the values in an enumeration class without having to maintain code that has a list of all the values. Because these methods could be used to build an equivalent to the automatic <var>Ordinal</var> method, they require <var>Allow Ordinal</var> to be set in the enumeration class against which they are used (see example below).

The <var>FromOrdinal</var> method is a [[Shared_class_members|shared method]] and has a single input argument: the ordinal number of the value to which to set the target enumeration variable. For example, if one has a <var>Stooge</var> enmeration:
enumeration stooge
public
value moe
value larry
value curly
value shemp
allow ordinal
end public
end enumeration

then the following sequence:
%favorite is enumeration stooge
%favorite = %(stooge):fromOrdinal(3)
printText {~=%favorite}

would print:
%favorite=curly

If an invalid ordinal number is specified as input to the <var>FromOrdinal</var> method, an <var>[[InvalidValue_class|InvalidValue]]</var> exception is thrown. For example, the following:
%favorite = %(stooge):fromOrdinal(-5)

would result in the following request canceling error message:
MSIR.0750: Class Stooge, function FromOrdinal: InvalidValue exception: -5 is not -
a valid ordinal number for class Stooge ...

You can catch such an exception to produce a list of all values in an enumeration class:
for %i from 1 to 99999999
try printText {%(stooge):fromOrdinal(%i)}
catch invalidValue; loop end
end try
end for

This outputs:
moe
larry
curly
shemp

The <var>NumberOfValues</var> automatic method for enumerations lets you do this a little more tidily:
for %i from 1 to %(stooge):numberOfValues
printText {%(stooge):fromOrdinal(%i)}
end for

The <var>NumberOfValues</var> method has no parameters.

<var>NumberOfValues</var> and <var>FromOrdinal</var> can be used to build an [[Arraylist_class|Arraylist]] that contains one item for each value in the enumeration class:
%stoogeValues is arraylist of enumeration stooge
...
%stoogeValues = new
for %i from 1 to %(stooge):numberOfValues
%stoogeValues:add(%(stooge):fromOrdinal(%i))
end for

One advantage of having such an <var>Arraylist</var> is that it can easily be sorted or searched. For example, the following displays the stooge values sorted in ascending character order:
%stoogevalues:[[SortNew_(GenericNamedArraylist_function)|sortNew]](ascending(toString)):print

This displays:
1: curly
2: larry
3: moe
4: shemp


==See also==
<ul>
<li>[[Object oriented programming in SOUL]]
</ul>

[[Category:SOUL object-oriented programming topics]]

Enumerations

2014-02-24T02:19:03Z

NMichell: Added just before "Using user enumerations". Absence was causing "cookieShape is enumeration shape" to be shown in main text body.