UC++ Documentation

[TOC]

Conventions

T is a placeholder type for a UC++ Interface or a normal type.
t is a placeholder variable for instances of any type, generally T.
v is a placeholder variable.
All place holder types & variables can have a prefix number or alphanumeric string if used more than once.
A context-sensitive place holder is a string of characters wrapped in question marks(??), e.g. ?name?. They can appear anywhere and are context-sensitive. They may be color coded as green, if possible.
Macros are color coded in purple, if possible.
Whenever a UCInterface say, T, is referred in the documentation it always means UC::GCPtr<T>, however , in case T is used in T::?some-method-or-variable?, a declaration or definition, as a template parameter or it's explicitly specified that T refers to the actual type then the actual type T is referred to being not UC::GCPtr<T>.
In many examples or explanations it is written Let's go through this line by line:, but actually it means Let's go through all the lines in the code that need explanation:.

Instead of writing:

virtual ?class?::?function?(?params?) = 0;
// or
virtual ?function?(?params?) = 0; // in a class

the following will be written instead as a short hand for pure-virtual functions in the documentation,

abstract ?class?::?function?(?params?);
// or
abstract ?function?(?params?); // in a class

forceinline

This macro is defined as being equal to BOOST_FORCEINLINE, which is defined as

// Macro to use in place of 'inline' to force a function to be inline
#if !defined(BOOST_FORCEINLINE)
#  if defined(_MSC_VER)
#    define BOOST_FORCEINLINE __forceinline
#  elif defined(__GNUC__) && __GNUC__ > 3
#    define BOOST_FORCEINLINE inline __attribute__ ((__always_inline__))
#  else
#    define BOOST_FORCEINLINE inline
#  endif
#endif

It is a Macro to use in place of 'inline' to force a function to be inline.

UCInterface(Name, StrName, Inheritance, NativeInheritance, ...)

UCInterface is a convenience macro that simplifies much of the complexity and boiler-plate code of declaring a proper UC++ Interface.

The first parameter is the name of the UCInterface.
The second parameter is the type-name of the UCInterface, there are 2 valid values for this UC_WhereTypenameIsRealName which assigns the same type-name as the name, or UC_WhereTypenameIs( "?name?" ) where ?name? will become the registered name of the UCInterface used for reflection.
The third parameter is the group of UC++ Interfaces the UCInterface inherits, pass in the UC++ Interfaces as wrapped in UC_InheritsUCClasses(?classes?). Each parameter will be expanded into a convenience using declaration, corresponding to the 0 based index of the inherited UC++ Interface, as base0, base1, base2, base3, ...
The fourth parameter is the group of native classes the UCInterface inherits, pass in the classes as wrapped in UC_InheritsNativeClasses(?classes?). Each parameter will be expanded into a convenience using declaration, corresponding to the 0 based index of the inherited class, as nbase0, nbase1, nbase2, nbase3,... To inherit no native classes pass in UC_InheritsNoNativeClasses as this parameter.
The fifth parameter is "optional" and can include post modifiers like final, which prevent the UC++ Interface from being inherited.

Be careful there is a vast difference in the name and the type-name of a UCInterface. The name represents the struct identifier of the UCInterface. The type-name is a string that is the return value of T::SGetTypeName() & t.GetTypeName(), also it is the registered name of the UCInterface, used for mainly for reflection.

Remember, always make constructors `protected` or `private` never `public`.

To use certain things like ME or WME the object has to be constructed as a UC::GCPtr but if the object is called with the public constructor then there will be undefined behavior. So, to avoid that always make constructors protected or private never public.

UC_IsSingleton

This macro defines Make() as being a function that is implemented as

static pself Make(){
	static pself v(new self());
	return v;
}

Where self refers to the class in which UC_IsSingleton is being expanded, and pself is equal to UC::GCPtr<self>. The macro also defines GetInstance(), GetInst(), GetI(), Instance() and Inst() which all call Make().

NOTE: The functions GetInstance(), GetInst(), GetI(), Instance() and Inst() are all forceinline so calling either GetInstance(), GetInst(), GetI(), Instance() or Inst() is equivalent to calling Make().

OR

UC_IsAbstract

Tag macro that defines no constructors and Make functions.

OR

UC_IsAbstractAndHasCtors(name, hasEmptyCtor, ...)

Macro that defines constructors but no Make function. This macro has the same calling syntax as UC_HasExplicitCtors.

The name of the UCInterface.
The 2 valid values are UC_HasNoEmptyCtor & UC_AlsoHasEmptyCtor. This parameter is quite self-explanatory.
Pass in the parameters delimited by commas surrounded by braces for the multiple constructors delimited by commas.

OR

UC_OnlyHasEmptyCtor

Defines a Make function that uses the 0 parameterized version of the constructor that may or may not be explicitly defined.

OR

UC_HasNativeCtorsAndEmptyCtor

As the name suggests, the UCInterface has native constructors, and an empty constructor. The empty constructor must be there as it is required for reflection.

OR

UC_HasExplicitCtors(name, hasEmptyCtor, ...)

Macro that defines constructors and a Make function. This macro has the same calling syntax as UC_IsAbstractAndHasCtors.

The name of the UCInterface.
The 2 valid values are UC_HasNoEmptyCtor & UC_AlsoHasEmptyCtor. This parameter is quite self-explanatory.
Pass in the parameters delimited by commas surrounded by braces for the multiple constructors delimited by commas.

THEN

UC_HasMethods(...)

This macro defines functions and preps up the Call reflection function.

Call this macro as

UC_HasMethods((?name?, (...?args?...)), ...)

NOTE: If there are no arguments then instead of (?name?, (...?args?...)) write (?name?).

NOTE: This function only adds declarations for the methods, to add implementations for them use

UCMethod(?interface-name?::?name?, (...?args?...))

or

UCMethod(?interface-name?::?name?)

The defines function has all the ...?args?... as being of the type UC::GCPtr<UC::Object>, the defined function also has a return type of UC::GCPtr<UC::Object>.

OR

UC_HasNoMethods

This macro states that the UCInterface only has native functions and all reflection calls should be passed up to the base(s).

UCEndInterface(name)

Terminates the UCInterface with the name specified.

UCRegister(name)

Registers the UCInterface with the name specified as a real UCInterface. Remember that when a UCInterface is define, it must be UCRegistered in the implementation .cpp file.

Remember that: if a UCInterface is created, it must be UCRegistered in the implementation`.cpp` file & only UCRegistered in the implementation`.cpp` file.

UCException(name)

Defines a well-formed UC++ exception class with the name specified.

Remember UCExceptions aren't UCInterfaces!

Dynamically allocating and throwing a small UCException that will either soon be caught and be destroyed or end program execution and be destroyed is a terrible, terrible idea.

Remember use `throw ?exeception-type?(?message?)` not `throw ?exeception-type?::Make(?message?)`.

?exeception-type?::Make(?message?) is an expression that would work for a UCInterface UCException but Remember UCExceptions aren't UCInterfaces.

Remember: always and only use `try{...}catch(const ?exeception-type?& v){...}//more-catch-clauses` for catching UCExceptions.

If

try
{
    ...
}
catch(?exeception-type? ?name?)
{
    ...
}//?more-catch-clauses?

is used instead of

try
{
    ...
}
catch(const ?exeception-type?& ?name?)
{
    ...
}//?more-catch-clauses?

there will be a slow down in the application due to copying of the UCException.

UCBasedException(name, base)

Defines a well-formed UC++ exception class with the name specified that inherits the base specified.

Know and remember that a UCBasedException is no different from a UCException.

ME

Gets the UC::GCPtr corresponding to the current instance of the UCInterface.

WME

Gets the UC::WeakPtr corresponding to the current instance of the UCInterface.

Don't use ME or WME, use `this`, unless is is absolutely needed.

ME and WME aren't simple keywords not are they easy to small expressions, they involve real function calls, but don't do this:

UC::GCPtr<self>(this)

that's the worst thing that a person could ever do..

Bottom line: Use ME or WME only when absolutely need to, otherwise use this.

UCMethod(name, args)

Defines a method with name specified and the arguments specified by args.

NOTE: If there are no arguments then instead of UCMethod(?name?, (...?args?...)) write UCMethod(?name?).

To define implementations for UCInterface methods use this as:

UCMethod(?interface-name?::?name?, (...?args?...))

or

UCMethod(?interface-name?::?name?)

The defines function has all the ...?args?... as being of the type UC::GCPtr<UC::Object>, the defined function also has a return type of UC::GCPtr<UC::Object>.

UCCtor(name, args)

NOTE: If there are no arguments then instead of UCCtor(?name?, (...?args?...)) write UCCtor(?name?).

To define implementations of a constructor for UCInterfaces use this as:

UCCtor(?interface-name?::?name?, (...?args?...))

or

UCCtor(?interface-name?::?name?)

The defines function has all the ...?args?... as being of the type UC::GCPtr<UC::Object>, the defined function also has a return type of UC::GCPtr<UC::Object>.

UCCast(type, value)

Casts value to the specified type. If value can't be converted to the type specified, an exception of type will be thrown with the type UC::InvalidCastException with the message:

"Variable: \"?value?\" is not of the expected type: ?type?"

Where ?value? & ?type? refer to the value specified and the type specified respectively.

UCAsInt16(v)

Gets the value from v, converts it to a int16_t. v can be of type UC::Int16, UC::Byte or UC::SByte and the macro will work properly, but if v is of any other type then, an exception of type will be thrown with the type UC::InvalidCastException with the message:

"Variable: \"?value?\" doesn't hold a value that can be converted to a int16_t"