The Types.uc file contains a default set of data types.  You are free to
rename or delete them, modify their properties, or to add your own types to
the list.  Fundamental types, such as Single, Double, or Extended precision,
and the various integer types, are associated with callback routines.  These
are included in a default library that is part of the uCalc DLL.  You can
construct your own data type handlers in the same manner, and compile them
into a DLL for use with uCalc.   See the help file for more details.

Many of the type definitions are similar.  So instead of giving individual
explanations for each, some of the first few lines are explained, along with
an aggregate of the rest.

==============================================================================

// Extended, String, and Stack are already pre-defined in the interpreter.
// Those 3 types can be renamed if necessary, but should not be un-defined.

These two lines are a comment, the content of which is self-explanatory.

==============================================================================

uCalc Prefix "uCalc Define "

Prefix is a useful command that you'll find many times elsewhere.  It
simply adds the text that you specify, at the beginning of every subsequent
line, so that you don't have to type it each time explicitly.  So the lines
that say:

   Begin
      DataType: Single
      Size: 4
      TypeHandler: ucAddr(uc_Single)
      ConvertsTo: Extended, ucAddr(uc_Convert_Single_Extended)
   End

for instance are the equivalent of:

uCalc Define Begin
uCalc Define    DataType: Single
uCalc Define    Size: 4
uCalc Define    TypeHandler: ucAddr(uc_Single)
uCalc Define    ConvertsTo: Extended, ucAddr(uc_Convert_Single_Extended)
uCalc Define End

These lines use the Define command to define a data type item.

==============================================================================

Begin

As mentioned in the previous section, this line is really "uCalc Define Begin".
Items are often defined all in one line, with multiple properties separated by
a "~~" (or whatever other term you set as a separator).  However if you use the
word Begin, then all other properties subsequently set with the Define
command will be associated with the same item, until you issue an "End".


==============================================================================

      DataType: Single

This names the data type -- Single in this case.


==============================================================================

      Size: 4

Typically a data type will require a fixed number of bytes for per unit.  By
setting a number of bytes for a given type, uCalc can automatically perform
such tasks as allocating that number of bytes whenever an item of that type is
created.

Some cases require additional code in the type handler callback routine in
order to allocate the right number of bytes.  The String (dynamic) type for
instance has a size of 4 bytes.  But this represents only the allocation size
for its handle.  The type handler handles the rest of the string allocation.

LPCSTR and FixedString have no hard-coded sizes at all.  The size is configured
on a case by case basis by the type handler.

The Void type is given a size of 10 to match Extended precision, which is the
default type (the default can be changed).  Otherwise the Void type does not
allocate memory the same the way other types do.

If you do not see a size for Extended precision, that's because it is already
defined in the interpreter executable itself, and the definition for it in
Types.uc simply adds more properties to this already defined type.


==============================================================================

      TypeHandler: ucAddr(uc_Single)

The TypeHandler property holds the address of the callback function that
contains type handling code for that type.  Depending on the data type, the
type handling routine might take care of tasks such as allocating, storing,
freeing, displaying, copying, returning, and resetting.  For types that are
simple, most of these tasks can be performed implicitly, typically leaving
the routine only the 3 required tasks of storing, returning, and displaying
the type.

uc_Single is a numeric constant, defined in ucalcpb.bas.  ucAddr() holds a
list of addresses of various ready-made library routines that you can pick from
so you don't have to start entirely from scratch when creating a language.


==============================================================================

      ConvertsTo: Extended, ucAddr(uc_Convert_Single_Extended)

In this property, we supply the name of a data type that this one can convert
to.  The type name is followed by a comma, and the address of a callback routine
that contains the code to perform the conversion.  That part is optional.
uCalc can generally perform implicit conversions from any simple type to
another.  However, a callback routine, when available, is more efficient.


==============================================================================

      ConvertsTo: Integer

Here, no callback routine is supplied for performing the conversion.  So this
type will implicitly perform a generic conversion to Integer.  A given type
can have any number of ConvertsTo properties.

      
==============================================================================

      ConvertsFrom: Integer

In the same way that you can indicate which other types this type can convert
to, you can also indicate which type it can convert from.

==============================================================================

      TextData: Ok

Among type definitions, only the Void data type uses this property.  Any item
can use this TextData property.  However, some items already use it implicitly,
in which case it should not be explicitly set to something else.

What TextData actually does in this context depends on the code present in the
type handler callback routine.  For void, it simply prints whatever value is
found in this property.  The Void type handler does nothing other than this
(for instance it does not handle allocations, etc...).  For other types, the
TextData property would simply have no effect.


==============================================================================

   End

When this point is reached, it indicates that you are finished with the
definition of a given item.  Subsequent calls to the Define command will imply
that you are dealing with a new item.


==============================================================================

ucalc Prefix ""

Earlier the prefix was set to "uCalc Define ".  Now the prefix is reset back to
nothing.
