/*
    Title: Array
    
        A light weight implementation of dynamic array structure in C Macros.
        
        Each array actually consists of the following members
        
        (start code)
        ElementType* Name; //The pointer to elements.
        int Name_Index; //Index of the top element.
        int Name_Size; //Size allocated for the Array.
        (end)
        
        
    Constant: Array_Addition
    
        The number of empty elements to be added to an Array when an
        enlargement takes place.
        
        
    Section: Constructing/Destructing

    Macro: Array_Define
    
        Defines an Array.
    
    Usage:
    
    > Array_Define(Type, Name);
    
    This is equivalent to
    
    (start code)
        Type* Name;
        int Name_Index;
        int Name_Size;
    (end)
    
    Parameters:
    
        Type - Type of elements(e.g. int, float ...)
        
        Name - Name of the Array.
        
        
    Macro: Array_Gtor
    
        Defines and inits an Array.
    
    Usage:
    
    > Array_Gtor(Type, Name);
    
    Parameters:
    
        Type - Type of elements.
        
        Name - Name of the Array.
        
        
    Macro: Array_Ctor
    
        Inits an Array.
    
    Usage:
    
    > Array_Gtor(Type, Name);
    
    Parameters:
    
        Type - Type of elements.
        
        Name - Name of the Array.
        
        
    Macro: Array_Dtor
    
        Destructs(frees) an Array.
    
    Usage:
    
    > Array_Dtor(Type, Name);
    
    Parameters:
    
        Type - Type of elements.
        
        Name - Name of the Array.
        
        
    Macro: Array_ObjDtor
    
        Destructs an Array and automatically calls the destructor for each of 
        its elements.
    
    Usage:
    
    > Array_ObjDtor(Type, Name);
    
    Parameters:
    
        Type - Type of elements.
        
        Name - Name of the Array.
        
        
    Section: Operations

    Macro: Array_Resize
    
        Reallocates memory for an Array but preserves its original elements
        (when allocated size is bigger than original size).
    
    Usage:
    
    > Array_Resize(Type, Array, NewSize);
    
    Parameters:
    
        Type - Type of elements.
        
        Array - Name of the Array.
        
        NewSize - Number of elements the Array holds.
        
        
    Macro: Array_Push
    
        Add an element at the top of an Array.
    
    Usage:
    
    > Array_Push(Type, Array, Data);
    
    Parameters:
    
        Type - Type of elements.
        
        Array - Name of the Array.
        
        Data - The element to be pushed.
        
        
    Macro: Array_PushNull
    
        Add an empty element at the top of an Array.
        
    Warning:
    
        The element being added is not initialized and may not be zero.
    
    Usage:
    
    > Array_PushNull(Type, Array);
    
    Parameters:
    
        Type - Type of elements.
        
        Array - Name of the Array.
        
        
    Macro: Array_Pop
    
        Pops an element from the top of an Array.
        
    Warning:
    
        The Array is not reallocated.
    
    Usage:
    
    > ReturnedElement = Array_Pop(Type, Array);
    
    Parameters:
    
        Type - Type of elements.
        
        Array - Name of the Array.
    
    Returns:
    
        The element being poped.
        
        
    Macro: Array_Insert
    
        Inserts an element into an Array.
    
    Usage:
    
    > Array_Insert(Type, Array, Index, Data);
    
    Parameters:
    
        Type - Type of elements.
        
        Array - Name of the Array.
        
        Index - The index at where Data is inserted.
        
        Data - The element to be inserted.
        
        
    Macro: Array_InsertNull
    
        Inserts an empty element into an Array.
        
    Warning:
    
        The element being inserted is not initialized and may not be zero.
    
    Usage:
    
    > Array_InsertNull(Type, Array, Index);
    
    Parameters:
    
        Type - Type of elements.
        
        Array - Name of the Array.
        
        Index - The index at where element is inserted.
        
        
    Macro: Array_Remove
    
        Removes an element from an Array.
        
    Warning:
    
        The Array is not reallocated.
    
    Usage:
    
    > Array_Remove(Type, Array, Index);
    
    Parameters:
    
        Type - Type of elements.
        
        Array - Name of the Array.
        
        Index - The index of the element being removed.
        
        
    Macro: Array_RemoveRange
    
        Removes a range of elements from an Array.
        
    Warning:
    
        The Array is not reallocated.
    
    Usage:
    
    > Array_RemoveRange(Type, Array, LIndex, HIndex);
    
    Parameters:
    
        Type - Type of elements.
        
        Array - Name of the Array.
        
        LIndex - The lower index of the elements being removed.
        
        HIndex - The upper index of the elements being removed.
        
        
    Section: Advanced

    Macro: Array_IncFind
    
        Finds the index of an element by comparing in increasing trend.
    
    Usage:
    
    > Array_IncFind(Dest, Type, Array, Data);
    
    Parameters:
    
        Type - Type of elements.
        
        Array - Name of the Array.
        
        Data - An element to be compared.
        
        
    Macro: Array_DecFind
    
        Finds the index of an element by comparing in decreasing trend.
    
    Usage:
    
    > Array_DecFind(Dest, Type, Array, Data);
    
    Parameters:
    
        Type - Type of elements.
        
        Array - Name of the Array.
        
        Data - An element to be compared.
        
        
    Section: Auxillaries

    Macro: TopOf
    
        Fetches the top element of an Array.
    
    Usage:
    
    > ReturnedElement = TopOf(Array);
    
    Parameters:
        
        Array - Name of the Array.
        
        
    Macro: Array_Par
    
        Defines an Array in function parameters.
    
    Usage:
    
    > RetType FunctionName(..., Array_Par(Type, Array), ...)
    
    This is equivalent to
    
    (start code)
    RetType FunctionName(..., Type* Array, int Array_Index, int Array_Size,
                         ...);
    (end)
    
    Parameters:
    
        Type - Type of elements.
        
        Array - Name of the Array.
        
        
    Macro: Array_Arg
    
        Sends an Array in function arguments.
    
    Usage:
    
    > FunctionName(..., Array_Arg(Type, Array), ...);
    
    This is equivalent to
    
    > FunctionName(..., Array, Array_Index, Array_Size, ...);
    
    Parameters:
    
        Type - Type of elements.
        
        Array - Name of the Array.
*/

