Table of Contents Previous Next
Logo
Client-Side Slice-to-C# Mapping : 14.7 Mapping for User-Defined Types
Copyright © 2003-2009 ZeroC, Inc.

14.7 Mapping for User-Defined Types

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

14.7.1 Mapping for Enumerations

Enumerations map to the corresponding enumeration in C#. For example:
enum Fruit { Apple, Pear, Orange };
Not surprisingly, the generated C# definition is identical:
enum Fruit { Apple, Pear, Orange };

14.7.2 Mapping for Structures

Ice for .NET supports two different mappings for structures. By default, Slice structures map to C# structures if they (recursively) contain only value types. If a Slice structure (recursively) contains a string, proxy, class, sequence, or dictionary member, it maps to a C# class. A metadata directive (see Section 4.17) allows you to force the mapping to a C# class for Slice structures that contain only value types.
In addition, for either mapping, you can control whether Slice data members are mapped to fields or to properties (see page 428).

Structure Mapping for Structures

Consider the following structure:
struct Point {
    double x;
    double y;
};
This structure consist of only value types and so, by default, maps to a C# structure:
public struct Point
{
    public double x;
    public double y;

    public Point(double x, double y);

    public override int GetHashCode();
    public override bool Equals(object other);

    public static bool operator==(Point lhs, Point rhs);
    public static bool operator!=(Point lhs, Point rhs);
}
For each data member in the Slice definition, the C# structure contains a corresponding public data member of the same name.
The generated constructor accepts one argument for each structure member, in the order in which they are defined in the Slice definition. This allows you to construct and initialize a structure in a single statement:
Point p = new Point(5.1, 7.8);
The structure overrides the GetHashCode and Equals methods to allow you to use it as the key type of a dictionary. (Note that the static two-argument version of Equals is inherited from System.Object.) Two structures are equal if (recursively) all their data members are equal. Otherwise, they are not equal. For structures that contain reference types, Equals performs a deep comparison; that is, reference types are compared for value equality, not reference equality.

Class Mapping for Structures

The mapping for Slice structures to C# structures provides value semantics. Usually, this is appropriate, but there are situations where you may want to change this:
• If you use structures as members of a collection, each access to an element of the collection incurs the cost of boxing or unboxing. Depending on your situation, the performance penalty may be noticeable.
• On occasion, it is useful to be able to assign null to a structure, for example, to support "not there" semantics (such as when implementing parameters that are conceptually optional).
To allow you to choose the correct performance and functionality trade-off, the Slice-to-C# compiler provides an alternative mapping of structures to classes, for example:
["clr:class"] struct Point {
    double x;
    double y;
};
The "clr:class" metadata directive instructs the Slice-to-C# compiler to generate a mapping to a C# class for this structure. The generated code is identical, except that the keyword struct is replaced by the keyword class1 and that the class also inherits from ICloneable:
public class Point : _System.ICloneable
{
    public double x;
    public double y;

    public Point();
    public Point(double x, double y);

    public object Clone();

    public override int GetHashCode();
    public override bool Equals(object other);

    public static bool operator==(Point lhs, Point rhs);
    public static bool operator!=(Point lhs, Point rhs);
}
The Clone method performs a shallow memberwise copy, and the comparison methods have the usual semantics (they perform value comparison).
Note that you can influence the mapping for structures only at the point of definition of a structure, that is, for a particular structure type, you must decide whether you want to use the structure or the class mapping. (You cannot override the structure mapping elsewhere, for example, for individual structure members or operation parameters.)
As we mentioned previously, if a Slice structure (recursively) contains a member of reference type, it is automatically mapped to a C# class. (The compiler behaves as if you had explicitly specified the "clr:class" metadata directive for the structure.)
Here is our Employee structure from Section 4.9.4 once more:
struct Employee {
    long number;
    string firstName;
    string lastName;
};
The structure contains two strings, which are reference types, so the Slice-to-C# compiler generates a C# class for this structure:
public class Employee : _System.ICloneable
{
    public long number;
    public string firstName;
    public string lastName;

    public Employee();
    public Employee(long number,
                    string firstName,
                    string lastName);

    public object Clone();

    public override int GetHashCode();
    public override bool Equals(object other);

    public static bool operator==(Employee lhs, Employee rhs);
    public static bool operator!=(Employee lhs, Employee rhs);
}

Property Mapping for Structures

You can instruct the compiler to emit property definitions instead of public data members. For example:
["clr:property"] struct Point {
    double x;
    double y;
};
The "clr:property" metadata directive causes the compiler to generate a property for each Slice data member:
public struct Point
{
    private double x_prop;
    public double x {
        get {
            return x_prop;
        }
        set {
            x_prop = value;
        }
    }

    private double y_prop;
    public double y {
        get {
            return y_prop;
        }
        set {
            y_prop = value;
        }
    }

    // Other methods here...
}
Note that the properties are non-virtual because C# structures cannot have virtual properties. However, if you apply the "clr:property" directive to a structure that contains a member of reference type, or if you combine the "clr:property" and "clr:class" directives, the generated properties are virtual. For example:
["clr:property", "clr:class"]
struct Point {
    double x;
    double y;
};
This generates the following code:
public class Point : System.ICloneable
{
    private double x_prop;
    public virtual double x {
        get {
            return x_prop;
        }
        set {
            x_prop = value;
        }
    }

    private double y_prop;
    public virtual double y {
        get {
            return y_prop;
        }
        set {
            y_prop = value;
        }
    }

    // Other methods here...
}

14.7.3 Mapping for Sequences

Ice for .NET supports several different mappings for sequences. By default, sequences are mapped to arrays. You can use metadata directives (see Section 4.17) to map sequences to a number of alternative types:
• System.Collections.Generic.List
• System.Collections.Generic.LinkedList
• System.Collections.Generic.Queue
• System.Collections.Generic.Stack
• Types derived from Ice.CollectionBase (which is a drop-in replacement for System.Collections.CollectionBase)2
• User-defined custom types that derive from System.Collections.Generic.IEnumerable<T>.
The different mappings allow you to map sequences to a container type that provides the correct performance trade-off for your application.

Array Mapping for Sequences

By default, the Slice-to-C# compiler maps sequences to arrays. Interestingly, no code is generated in this case; you simply define an array of elements to model the Slice sequence. For example:
sequence<Fruit> FruitPlatter;
Given this definition, to create a sequence containing an apple and an orange, you could write:
Fruit[] fp = { Fruit.Apple, Fruit.Orange };
Or, alternatively:
Fruit fp[] = new Fruit[2];
fp[0] = Fruit.Apple;
fp[1] = Fruit.Orange;
The array mapping for sequences is both simple and efficient, especially for sequences that do not need to provide insertion or deletion other than at the end of the sequence.

Mapping to Predefined Generic Containers for Sequences

With metadata directives, you can change the default mapping for sequences to use generic containers provided by .NET. For example:
["clr:generic:List"] sequence<string> StringSeq;
["clr:generic:LinkedList"] sequence<Fruit> FruitSeq;
["clr:generic:Queue"] sequence<int> IntQueue;
["clr:generic:Stack"] sequence<double> DoubleStack;
The "clr:generic:<type>" metadata directive causes the slice2cs compiler to the map the corresponding sequence to one of the containers in the System.Collections.Generic namespace. For example, the Queue sequence maps to System.Collections.Generic.Queue<int> due to its metadata directive.
The predefined containers allow you to select an appropriate space–performance trade-off, depending on how your application uses a sequence. In addition, if a sequence contains value types, such as int, the generic containers do not incur the cost of boxing and unboxing and so are quite efficient. (For example, System.Collections.Generic.List<int> performs within a few percentage points of an integer array for insertion and deletion at the end of the sequence, but has the advantage of providing a richer set of operations.)

Mapping to Custom Types for Sequences

If the array mapping and the predefined containers are unsuitable for your application (for example, because may need a priority queue, which does not come with .NET), you can implement your own custom containers and direct slice2cs to map sequences to these custom containers. For example:
["clr:generic:MyTypes.PriorityQueue"] sequence<int> Queue;
This metadata directive causes the Slice Queue sequence to be mapped to the type MyTypes.PriorityQueue. You must specify the fully-qualified name of your custom type following the clr:generic: prefix. This is because the generated code prepends a global:: qualifier to the type name you provide; for the preceding example, the generated code refers to your custom type as global::MyTypes.PriorityQueue<int>.
Your custom type can have whatever interface you deem appropriate, but it must meet the following requirements:
• The custom type must derive from System.Collections.Generic.IEnumerable<T>.
• The custom type must provide a readable Count property that returns the number of elements in the collection.
• The custom type must provide an Add method that appends an element to the end of the collection.
• If (and only if) the Slice sequence contains elements that are Slice classes, the custom type must provide an indexer that sets the value of an element at a specific index. (Indexes, as usual, start at zero.)
As an example, here is a minimal class (omitting implementation) that meets these criteria:
public class PriorityQueue<T> : IEnumerable<T>
{
    public IEnumerator<T> GetEnumerator();

    public int Count
        get;

    public void Add(T elmt);

    public T this[int index] // Needed for class elements only.
        set;


    // Other methods and data members here...
}

CollectionBase Mapping for Sequences

The CollectionBase mapping is provided mainly for compatibility with Ice versions prior to 3.3. Internally, CollectionBase is implemented using System.Collections.Generic.List<T>, so it offers the same performance trade-offs as List<T>. (For value types, Ice.CollectionBase is considerably faster than System.Collections.CollectionBase, however.)
Ice.CollectionBase is not as type-safe as List<T> because, in order to remain source code compatible with System.Collections.CollectionBase, it provides methods that accept elements of type object. This means that, if you pass an element of the wrong type, the problem will be diagnosed only at run time, instead of at compile time. For this reason, we suggest that you do not use the CollectionBase mapping for new code.
To enable the CollectionBase mapping, you must use the "clr:collection" metadata directive:
["clr:collection"] sequence<Fruit> FruitPlatter;
With this directive, slice2cs generates a type that derives from Ice.CollectionBase:
public class FruitPlatter : Ice.CollectionBase<M.Fruit>,
                            System.ICloneable
{
    public FruitPlatter();
    public FruitPlatter(int capacity);
    public FruitPlatter(Fruit[] a);
    public FruitPlatter(
        System.Collections.Generic.IEnumerable<Fruit> l);

    public static implicit operator
        _System.Collections.Generic.List<Fruit>(FruitPlatter s);

    public virtual FruitPlatter GetRange(int index, int count);

    public static FruitPlatter Repeat(Fruit value, int count);

    public object Clone();
}
The generated FruitPlatter class provides the following methods:
• FruitPlatter();
FruitPlatter(int capacity);
FruitPlatter(Fruit[] a);
FruitPlatter(IEnumerable<Fruit> l);
Apart from calling the default constructor, you can also specify an initial capacity for the sequence or, using the array constructor, initialize a sequence from an array. In addition, you can initialize the class to contain the same elements as any enumerable collection with the same element type.
• FruitPlatter GetRange(int index, int count);
This method returns a new sequence with count elements that are copied from the source sequence beginning at index.
• FruitPlatter Repeat(Fruit value, int count);
This method returns a sequence with count elements that are initialized to value.
• object Clone()
The Clone method returns a shallow copy of the source sequence.
• static implicit operator List<Fruit>
                            (FruitPlatter s);
This operator performs an implicit conversion of a FruitPlatter instance to a List<Fruit>, so you can pass a FruitPlatter sequence where a List<Fruit>, IEnumerable<Fruit>, or System.Collections.IEnumerable is expected.
The remaining methods are provided by the generic Ice.CollectionBase base class. This class provides the following methods:
• CollectionBase();
CollectionBase(int capacity);
CollectionBase(T[] a);
CollectionBase(IEnumerable<T> l);
The constructors initialize the sequence as for the concrete derived class.
• int Count { get; }
This property returns the number of elements of the sequence.
• int Capacity { get; set; }
This property controls the capacity of the sequence. Its semantics are as for the corresponding property of List<T>.
• virtual void TrimToSize();
This method sets the capacity of the sequence to the actual number of elements.
• int Add(object o);
int Add(T value);
These methods append value at the end of the sequence. They return the index at which the element is inserted (which always is the value of Count prior the call to Add.)
• void Insert(int index, object o);
void insert(int index, T value);
These methods insert an element at the specified index.
• virtual void InsertRange(int index,
                         CollectionBase<T> c);
virtual void InsertRange(int index, T[] c);
These methods insert a range of values into the sequence starting at the given index.
• virtual void SetRange(int index,
                      CollectionBase<T> c);
virtual void SetRange(int index, T[] c);
These methods copy the provided sequence over a range of elements in the target sequence, starting at the provided index, with semantics as for System.Collections.ArrayList
• void RemoveAt(int index);
This method deletes the element at the specified index.
• void Remove(object o);
void Remove(T value);
These methods search for the specified element and, if present, delete that element. If the element is not in the sequence, the methods do nothing.
• virtual void RemoveRange(int index, int count);
This method removes count elements, starting at the given index.
• void Clear();
This method deletes all elements of the sequence.
• bool Contains(object o);
bool Contains(T value);
These methods return true if the sequence contains value; otherwise, they return false.
• int IndexOf(object o);
int IndexOf(T value);
These methods return the index of the specified element. If the element is not in the sequence, the return value is -1.
• virtual int LastIndexOf(T value);
virtual int LastIndexOf(T value,
                        int startIndex);
virtual int LastIndexOf(T value, int startIndex,
                         int count);
These methods search for the provided element and return its last occurrence in the sequence, as for
System.Collections.ArrayList.LastIndexOf.
• object this[int index] { get; set; }
T this[int index] { get; set; }
The indexers allow you to read and write elements using array subscript notation.
• IEnumerator<T> GetEnumerator();
This method returns an enumerator that you can use to iterate over the collection.
• static implicit operator List<T>
                            (CollectionBase<T> s);
As for the derived class, this operator permits implicit conversion to a List<T>.
• void CopyTo(T[] a);
void CopyTo(T[] a, int i);
void CopyTo(int i, T[] a, int ai, int c);
void CopyTo(System.Array a, int i);
These methods copy the contents of a sequence into an array. The semantics are the same as for the corresponding methods of List<T>.
• T[] ToArray();
The ToArray method returns the contents of the sequence as an array.
• void AddRange(CollectionBase<T> s);
void AddRange(T[] a);
The AddRange methods append the contents of a sequence or an array to the current sequence, respectively.
• virtual void Sort();
virtual void Sort(System.Collections.IComparer
                  comparer);
virtual void Sort(int index, int count,
    System.Collections.IComparer comparer);
These methods sort the sequence.
• virtual void Reverse();
virtual void Reverse(int index, int count);
These methods reverse the order of elements of the sequence.
• virtual int BinarySearch(T value);
virtual int BinarySearch(T value,
    System.Collections.IComparer comparer);
virtual int BinarySearch(int index, int count,
    T value,
    System.Collections.IComparer comparer);
The methods perform a binary search on the sequence, with semantics as for System.Collections.ArrayList.
• static FruitPlatter Repeat(Fruit value, int count);
This method returns a sequence with count elements that are initialized to value.
Note that for all methods that return sequences, these methods perform a shallow copy, that is, if you have a sequence whose elements have reference type, what is copied are the references, not the objects denoted by those references.
Ice.CollectionBase also provides the usual GetHashCode and Equals methods, as well as the comparison operators for equality and inequality. (Two sequences are equal if they have the same number of elements and all elements in corresponding positions are equal, as determined by the Equals method of the elements.)
Ice.CollectionBase also implements the inherited IsFixedSize, IsReadOnly, and IsSynchronized properties (which return false), and the inherited SyncRoot property (which returns this).
Creating a sequence containing an apple and an orange is simply a matter of writing:
FruitPlatter fp = new FruitPlatter();
fp.Add(Fruit.Apple);
fp.Add(Fruit.Orange);

Multi-Dimensional Sequences

Slice permits you to define sequences of sequences, for example:
enum Fruit { Apple, Orange, Pear };
["clr:generic:List"] sequence<Fruit> FruitPlatter;
["clr:generic:LinkedList"] sequence<FruitPlatter> Cornucopia;
If we use these definitions as shown, the type of FruitPlatter in the generated code is:
System.Collections.Generic.LinkedList<
    System.Collections.Generic.List<Fruit>
>
As you can see, the outer sequence contains elements of type List<Fruit>, as you would expect.
Now let us modify the definition to change the mapping of FruitPlatter to an array:
enum Fruit { Apple, Orange, Pear };
sequence<Fruit> FruitPlatter;
["clr:LinkedList"] sequence<FruitPlatter> Cornucopia;
With this definition, the type of Cornucopia becomes:
System.Collections.Generic.LinkedList<Fruit[]>
As you can see, the generated code now no longer mentions the type FruitPlatter anywhere and deals with the outer sequence elements as an array of Fruit instead.

14.7.4 Mapping for Dictionaries

Ice for .NET supports three different mappings for dictionaries. By default, dictionaries are mapped to System.Collections.Generic.Dictionary<T>. You can use metadata directives (see Section 4.17) to map dictionaries to two other types:
• System.Collections.Generic.SortedDictionary
• Types derived from Ice.DictionaryBase (which is a drop-in replacement for System.Collections.DictionaryBase)3

Mapping to Predefined Containers for Dictionaries

Here is the definition of our EmployeeMap from Section 4.9.4 once more:
dictionary<long, Employee> EmployeeMap;
By default, he Slice-to-C# compiler maps the dictionary to the following type:
System.Collections.Generic.Dictionary<Employee>
You can use the "clr:generic:SortedDictionary" metadata directive to change the mapping to a sorted dictionary:
["clr:generic:SortedDictionary"]
dictionary<long, Employee> EmployeeMap;
With this definition, the type of the dictionary becomes:
System.Collections.Generic.SortedDictionary<Employee>

DictionaryBase mapping for Dictionaries

The DictionaryBase mapping is provided mainly for compatibility with Ice versions prior to 3.3. Internally, DictionaryBase is implemented using System.Collections.Generic.Dictionary<T>, so it offers the same performance trade-offs as Dictionary<T>. (For value types, Ice.DictionaryBase is considerably faster than System.Collections.DictionaryBase, however.)
Ice.DictionaryBase is not as type-safe as Dictionary<T> because, in order to remain source code compatible with System.Collections.DictionaryBase, it provides methods that accept elements of type object. This means that, if you pass an element of the wrong type, the problem will be diagnosed only at run time, instead of at compile time. For this reason, we suggest that you do not use the DictionaryBase mapping for new code.
To enable the DictionaryBase mapping, you must use the "clr:collection" metadata directive:
["clr:collection"] dictionary<long, Employee> EmployeeMap;
With this directive, slice2cs generates a type that derives from Ice.CollectionBase:
public class EmployeeMap : Ice.DictionaryBase<long, Employee>,
                           System.ICloneable
{
    public void AddRange(EmployeeMap m);
    public object Clone();
}
Note that the generated EmployeeMap class derives from Ice.DictionaryBase, which provides a super-set of the interface of the .NET System.Collections.DictionaryBase class. Apart from methods inherited from DictionaryBase, the class provides a Clone method and an AddRange method that allows you to append the contents of one dictionary to another. If the target dictionary contains a key that is also in the source dictionary, the target dictionary’s value is preserved. For example:
Employee e1 = new Employee();
e1.number = 42;
e1.firstName = "Herb";
e1.lastName = "Sutter";

EmployeeMap em1 = new EmployeeMap();
em[42] = e;

Employee e2 = new Employee();
e2.number = 42;
e2.firstName = "Stan";
e2.lastName = "Lipmann";

EmployeeMap em2 = new EmployeeMap();
em[42] = e2;

// Add contents of em2 to em1
//
em1.AddRange(em2);

// Equal keys preserve the original value
//
Debug.Assert(em1[42].firstName.Equals("Herb"));
The DictionaryBase class provides the following methods:
public abstract class DictionaryBase<KT, VT>
    : System.Collections.IDictionary
{
    public DictionaryBase();

    public int Count { get; }

    public void Add(KT key, VT value);
    public void Add(object key, object value);

    public void CopyTo(System.Array a, int index);

    public void Remove(KT key);
    public void Remove(object key);

    public void Clear();

    public System.Collections.ICollection Keys { get; }
    public System.Collections.ICollection Values { get; }

    public VT this[KT key] { get; set; }
    public object this[object key] { get; set; }

    public bool Contains(KT key);
    public bool Contains(object key);

    public override int GetHashCode();
    public override bool Equals(object other);
    public static bool operator==(DictionaryBase<KT, VT> lhs,
                                  DictionaryBase<KT, VT> rhs);
    public static bool operator!=(DictionaryBase<KT, VT> lhs,
                                  DictionaryBase<KT, VT> rhs);

    public System.Collections.IEnumerator GetEnumerator();

    public bool IsFixedSize { get; }
    public bool IsReadOnly { get; }
    public bool IsSynchronized { get; }
    public object SyncRoot { get; }
}
The methods have the same semantics as the corresponding methods in the .NET Framework. The Equals method returns true if two dictionaries contain the same number of entries and, for each entry, the key and value are the same (as determined by their Equals methods).
The Clone method performs a shallow copy.
The class also implements the inherited IsFixedSize, IsReadOnly, and IsSynchronized properties (which return false), and the SyncRoot property (which returns this).

1
Some of the generated marshaling code differs for the class mapping of structures, but this is irrelevant to application code.

2
This mapping is provided mainly for compatibility with Ice versions prior to 3.3.

3
This mapping is provided mainly for compatibility with Ice versions prior to 3.3.

Table of Contents Previous Next
Logo