Mapped type are a unique feature of the Elements compiler. They let you create compatibility wrappers for types without ending up with classes that contain the real type. The wrappers will be eliminated by the compiler and rewritten to use the type the mapping maps to.
When working with Oxygene, C# or Swift, you will most commonly use mapped types (for example as provided by the Sugar cross-platform library), but not often implement mapped types yourself. All languages provide a syntax for easily and conveniently defining mapped types though, if needed, via the
mapped (Oxygene) and
__mapped (RemObjects C#) keywords.
What Are Mapped Types?
You can think of mapped types (usually classes) as "type aliases" or "inline types". They are not types that will actually exist at runtime. Instead, they are projections of an existing different type (the "real" type) under a new name and with a new set of visible members.
For example, a real class
Foo might readily exist, with methods
C. A mapped class called
Bar might be defined, exposing methods called
Z that actually map to the methods
C of the original class.
What is the Purpose of this Charade?
The most common goal for mapped classes is to allow different-but-similar classes that may exist on different platforms or in different frameworks to be used by one set of code, without a lot of Conditional Compilation.
For example, all platforms (such as .NET, Java, Cocoa) include basic classes such as strings, lists, dictionaries, XML documents, etc. But while these classes perform the same tasks on all platforms, their APIs generally look differently (both the classes and their members have different names), and they might have subtly different behavior (for example,
subString on Java treats the indices differently than
SubString on .NET).
A mapped class allows you to define a new class that is not "real" and that exposes one set of methods; this class can be used on all platforms. Under the hood, that mapped class will actually map to the original platform-specific classes, depending on which platform your code is compiled.
The Sugar library provides a wide range of such classes, ready to be used across platforms – and you can of course define your own.