Compilation of resources.
~~~~~~~~~~~~~~~~~~~~~~~~~~
    Built-in in C-- the compiler of resources on the possibilities concedes
to specialized compilers of resources, but these possibilities, as it seems,
will be enough for majority of your problems.

    It will be easier to list that built-in in C-- the compiler of resources
does not know how to make.  The operators of resources are not treated:
'VERSION', 'VERSIONINFO' and difiniendums by the user resources.  If
necessary, it is possible to enter datas entered with the help of of these
operators, with the help of of operator 'RCDATA'.  Many operators of
resources have optional parameters 'loading' and 'memory'.  The support of
these parameters is not realized.  By meeting these parameters, the compiler
simply will pass them.

    To include the C-- compiler to treat resources it is possible by two
methods:

    1. To include in the project by the instruction '#include' the file with
the '.rc' extension.  Files with such extension the compiler considers as the
file with resources. The file of resources is necessary for including in your
project only after inclusion of heading files Windows.

    2. Resources it is possible to possess in a skew field of the program in
any place, but the text of resources should begin with the instruction
'#pragma resource start', and to be finished by the instruction '#pragma
resource end'.  The resources can be divided on a part and these parts it
possible to possess in any place, convenient for you, (silly to possess
resources in the block of the comments and then to be surprised, why they
were not compiled).  The compiler will collect these parts and will compile.

    It is possible to write names of operators both large, and small letters,
but the names of identifiers are sensitive to the register.  In the text of
resources it is possible to use the directives and comments.


Outside labels (out of procedures)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    The outside labels are placed in the program's data area. If the data and
code are situated in the only segment (that's the usual way for c-- to place
them together) the outside labels become a simple and effective way for
getting the addresses of different program parts.

    Unique identificators may be used for naming the labels. You can use
capital, small and the mixture of them while giving the label a name.


Advanced features of pointers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Since now you can use pointer-typed variables to pass to procedure with
the other parameters. You can use pointers as procedure's local variables
too.  You can also use pointers in structures. The pointers to pointers are
also available. Procedure-pointers support is added too:

void (*proc)();  // procedure-pointer declaration

    By default the pointers on a procedure are the pointers on a procedure in
style 'pascal', irrespective of the register, in which the name of a
procedure and mode of compilation is written.  If it is necessary, that other
type of call was used, it is necessary for indicating for want of declaration
of the pointer a procedure.

    The compiler does not control the contents of the pointer while
initializing it. That is you can make 'char' pointer to be pointed to 'int'
pointer or to make a procedure-pointer to be pointed to a variable, i.e.
there's no type-verify. That's there may be a mistake in the program
concerned with the type confusion.


Declaring procedures in structures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    With the introduction the support for the procedures in structures,
structure becomes a similar to C++ class. That is such procedure becomes a
class-member. Example:

struct Point  // class declaration
{
    int x; // data members of
    int y; //  the Point class
    void SetX(int);  // methods declaration
    void SetY(int);  // belonging to the Point class
};

void Point::SetX(int _x)  //Point class function declaration
{
    IF((_x>=0)&&(_x<=MAX_X)) x=_x;
// x,y variables are the member of the class that is why the access to them
// from the procedures of the class is indirect.
 }

void main()
Point p;  //declaring a structure in stack
{
  p.y = p.x = 0;
  p.SetX(1);
}

    When a class member (procedure) is called  the address of the class
(structure) is implicitly passed to it. In the procedure the address is
accessible via the name of a parametric variable 'this'. This variable is
automatically generated by the compiler. If a procedure (class member) is
defined as 'static' the address of the class is not passed to the procedure
and 'this' variable is not generated for it.

    The procedure declared in a structure can be a dynamic one. For this
purpose a ':' (colon) symbol must be placed before the name of the procedure
in the declaration. But such a procedure cannot be used as a macros.


Inheriting
~~~~~~~~~~
    The C-- supports both simple and multiple inheritings. The declaration of
an inherited structure looks like the following:

struct Derived : Base1, Base2, ... Basen
{
  int x0;
};

    The number of base structures is not restricted. In case of multiple
inheritance a structure can inherit two or more copies of the base structure.
But in this case ambiguity takes place. Example:

struct A
{
  int x0,y;
  . . .
};

struct B : A  //structure 'B' inherits 'A'
{
  . . .

};

struct C : A  //structure 'C' inherits 'A'
{
  . . .
};

struct D : B, C //structure 'D' inherits 'B' and 'C'
{
  . . .
};

void main()
D d;  // allocating a memory block for the 'D' structure in stack and assigning
//a name of 'd' to it
{
  d.x0=0;

    In this example the 'D' structure inherits two copies of the 'A'
structure and the first one contains two elements called 'x0'. The C++
compilers show an error message compiling the string 'd.x0=0'. By default the
C-- treats that record and makes the element of the last inherited structure
to get the value. To get access to the first inherited 'x0' element the '::'
operator must be used:

  d.B::x0=0;

    That is, the records:

  d.x0=0;

    and

  d.C::x0=0;

    are equal.


Passing parameters to stack procedures via registers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    The most compact and the fastest code is made when parameters are passed
via registers. But the contents of the registers can be easyly destroyed. If
a parameter is used once to initialize a register you can pass the value into
the procedure at once via register, by-passing the stage of pushing and
popping the contents with the stack. Example:

int proc (int param1, param2, param3)
{
  (e)BX = param3;
  (e)BX.TAG_STRUCT.var = proc2 (param1,papra2);
  proc3 (param1,param2);
}

    In the example the param3 parameter is only used to initialize (e)BX
register that is why it can be passed via register:

int proc (int param1, param2, (e)BX)
{
  (e)BX.TEG_STRUCT.var = proc2 (param1,papra2);
  proc3 (param1,param2);
}

    As you see, the procedure has become slightly simpler.

    It is neccessory to remember that the contents of registers can be simply
damaged therefore the best thing to do about parameters is to use register
parameters after pushing the stack ones. For 'pascal' procedures register
parameters is better to place after stack ones. For 'cdecl' and 'stdcall'
procedures is better to place register parameters maiden.


Assigning the same value to several variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    If you need to assign the same value to several variables:

  var1=0;
  var2=0;
  var3=0;

    now you can write the same more briefly:

  var1=var2=var3=0;

    The more compact and faster code is generated while using this way.


'static' keyword and '::' operator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    If you specify 'static' keyword before the declaration of a global
variable, a structure or a procedure they will be available only in the file
they are declared in. That means if you include this file with 'include'
directive into another one the variables declared as 'static' will not be
available in the main file and you can declare the variables with the same
names in the main file.

    If a local variable defined in a procedure as 'static' the memory for it
will be allocated not in the stack but in the data area. But the variable
will be available only inside the procedure where it was declared. Making a
local variable to be 'static' gives an opportunity to save the value of the
variable for the next entrance into the procedure.

    Any global object (a variable, a structure or a procedure) can be
declared as 'static'. For the local usage the keyword can be applied only to
variables.

    If there was a global and a local variable with the same name in the
program you had no access to the global one. Now you can get access to the
global variable using '::' operator. Example:

int var;  //declaring a global variable

void proc()
int var;  //declaring a local variable with the name of
         // the existing global variable
{
  (e)AX=var;    //accessing the local variable
  (e)AX=::var;  //accessing the global one
}


Replacement of 'return' with 'goto'
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    In some situations (when compiling a program) 'return' operator will be
replaced with 'goto'. It takes place when code size optimization is enabled
and appliable for 'return' operators which are situated inside the procedure
and the code size for using 'return' is bigger than for 'goto'. This method
is always used for dynamic procedures used as macros. The 'goto' operator
will be executed only in the end of the procedure. If a dynamic procedure is
used as a macros the 'return' operator situated in the end of the procedure
will be by-passed by the compiler.

    Thus, the last limitation for using dynamic procedures as macros is
removed. Now any dynamic procedure can be used as a macros.

    For the 'goto' operator there is a shorter clone - 'GOTO'. For obtaining
more compact code for the 'return' operator a shorter 'RETURN' operator is
introduced too. It can be used if between the place where it is used and the
end of the procedure there is no more than 128 bytes. In the another case the
compiler will display an error message. When using 'return' in the smaller
than 128 bytes distance to the end the compiler will display a warning
message because it is possible to use the 'RETURN' operator.


Bit fields of structures
~~~~~~~~~~~~~~~~~~~~~~~~
    Bit fields are used for memory saving because they let to pack values
densely, they are also used for convenient access to the registers of the
peripherals in which several bits may have independent functional assignment.

    The declaration of a bit field has the following syntax:

<type> [<identifier>]:<constant>;

Example:

int var:5; //declaring a bit field by the size of 5 bits named as 'var'


    A bit field consists of a number of bits which is specified by a
numerical <constant>. Its value must be a positive integer and it must be
below or equal the number of bits in the <type>. In C-- bit fields can
contain only unsigned values. The arrays of bit field and the pointers to
them cannot be used.

    The <identifier> names a bit field. Its presence is not necessary.
Unnamed bit field means a skip of bits before the next structure member. The
unnamed zero-sized bit field has a special assignment: it guarantees that the
memory for the next bit field will be started on the boundary of the type
specified for the unnamed bit field. That is the bitfield will be aligned on
8/16/32 bits.

    In C-- all the bit fields are packed one after another irrespective of
the boundaries of the identifiers' types. If the next field is not a bit
field the rest bits before the boundary will not be used. The maximum size of
a bit field is 32 bits for 'dword/long' type, 16 bits for 'word/int' type and
8 bits for 'byte/char' type. Bit fields can be united, i.e be used with the
'union' operator. The 'sizeof' operator for the bit field will return the
size of the field in bits. When using a bit field, its contents will be
extended into a register as an unsigned integer.


   === === ===
* README.TXT - ENGLISH - SPHINX C-- v0.238 beta 4 *
(C) 2002 Written by Michael Sheker
(C) 2002 Translated from Russian by YBX (exhu@tut.by), FIDONET: 2:454/21.43
PLEASE, SEND ANY COMMENTS, CORRECTIONS, NOTES etc. !!!
