18.7 Mapping for User-Defined Types

Slice supports user-defined types: enumerations, structures, sequences, and dictionaries.

18.7.1 Mapping for Enumerations

Python does not have an enumerated type, so the Slice enumerations are emulated using a Python class: the name of the Slice enumeration becomes the name of the Python class; for each enumerator, the class contains an attribute with the same name as the enumerator. For example:

enum Fruit { Apple, Pear, Orange };

The generated Python class looks as follows:

class Fruit(object):
    def __init__(self, val):
        assert(val >= 0 and val < 3)
        self.value = val

    # ...

Fruit.Apple = Fruit(0)
Fruit.Pear = Fruit(1)
Fruit.Orange = Fruit(2)

Each instance of the class has a value attribute providing the integer value of the enumerator. Note that the generated class also defines a number of Python special methods, such as __str__ and __cmp__, which we have not shown.

Given the above definitions, we can use enumerated values as follows:

f1 = Fruit.Apple
f2 = Fruit.Orange

if f1 == Fruit.Apple:                # Compare with constant
    # ...

if f1 == f2:                         # Compare two enums
    # ...

if f2.value == Fruit.Apple.value:    # Use integer values
    # ...
elif f2.value == Fruit.Pear.value:
    # ...
elif f2.value == Fruit.Orange.value:
    # ...

As you can see, the generated class enables natural use of enumerated values. The Fruit class attributes are preinitialized enumerators that you can use for initialization and comparison. You may also instantiate an enumerator explicitly by passing its integer value to the constructor, but you must make sure that the passed value is within the range of the enumeration; failure to do so will result in an assertion failure:

favoriteFruit = Fruit(4) # Assertion failure!

18.7.2 Mapping for Structures

Slice structures map to Python classes with the same name. For each Slice data member, the Python class contains a corresponding attribute. For example, here is our Employee structure from Section 4.9.4 once more:

struct Employee {
    long number;
    string firstName;
    string lastName;
};

The Python mapping generates the following definition for this structure:

class Employee(object):
    def __init__(self, number=0, firstName='', lastName=''):
        self.number = number
        self.firstName = firstName
        self.lastName = lastName

    def __hash__(self):
        # ...

    def __eq__(self, other):
        # ...

    def __str__(self):
        # ...

The constructor initializes each of the attributes to a default value appropriate for its type.

The __hash__ method returns a hash value for the structure based on the value of all its data members.

The __eq__ method returns true if all members of two structures are (recursively) equal.

The __str__ method returns a string representation of the structure.

18.7.3 Mapping for Sequences

Slice sequences map by default to Python lists; the only exception is a sequence of bytes, which maps by default to a string in order to lower memory utilization and improve throughput. This use of native types means that the Python mapping does not generate a separate named type for a Slice sequence. It also means that you can take advantage of all the inherent functionality offered by Python’s native types. For example:

sequence<Fruit> FruitPlatter;

We can use the FruitPlatter sequence as shown below:

platter = [ Fruit.Apple, Fruit.Pear ]
assert(len(platter) == 2)
platter.append(Fruit.Orange)

The Ice run time validates the elements of a tuple or list to ensure that they are compatible with the declared type; a ValueError exception is raised if an incompatible type is encountered.

Allowable Sequence Values

Although each sequence type has a default mapping, the Ice run time allows a sender to use other types as well. Specifically, a tuple is also accepted for a sequence type that maps to a list, and in the case of a byte sequence, the sender is allowed to supply a tuple or list of integers as an alternative to a string¹.

Furthermore, the Ice run time accepts objects that implement Python’s buffer protocol as legal values for sequences of most primitive types. For example, you can use the array module to create a buffer that is transferred much more efficiently than a tuple or list. Consider the two sequence values in the sample code below:

import array
...
seq1 = array.array("i", [1, 2, 3, 4, 5])
seq2 = [1, 2, 3, 4, 5]

The values have the same on-the-wire representation, but they differ greatly in marshaling overhead because the buffer can be traversed more quickly and requires no validation.

Note that the Ice run time has no way of knowing what type of elements a buffer contains, therefore it is the application’s responsibility to ensure that a buffer is compatible with the declared sequence type.

Customizing the Sequence Mapping

The previous section described the allowable types that an application may use when sending a sequence. That kind of flexibility is not possible when receiving a sequence, because in this case it is the Ice run time’s responsibility to create the container that holds the sequence.

As stated earlier, the default mapping for most sequence types is a list, and for byte sequences the default mapping is a string. Unless otherwise indicated, an application always receives sequences as the container type specified by the default mapping. If it would be more convenient to receive a sequence as a different type, you can customize the mapping by annotating your Slice definitions with metadata. Table 18.2 describes the metadata directives supported by the Python mapping.

18.7.4 Mapping for Dictionaries