m2_declarations.hlp

是一个经济学管理应用软件 很难找的 但是经济学学生又必须用到

{smcl}
{* 18mar2005}{...}
{cmd:help m2 declarations}
{hline}
{* index declarations}{...}
{* index externals}{...}
{* index global variable}{...}
{* index external tt}{...}
{* index real tt}{...}
{* index complex tt}{...}
{* index numeric tt}{...}
{* index string tt}{...}
{* index transmorphic tt}{...}
{* index scalar tt}{...}
{* index vector tt}{...}
{* index rowvector tt}{...}
{* index colvector tt}{...}
{* index matrix tt}{...}
{* index arguments, program}{...}
{* index eltype it}{...}
{* index type it}{...}
{* index orgtype it}{...}
{* index function}{...}
{* index variable}{...}
{* index void function}{...}

{title:Title}

{p 4 4 2}
{hi:[M-2] declarations -- Declarations and types}


{title:Syntax}

	{it:declaration1} {it:fcnname}{cmd:(}{it:declaration2}{cmd:)}
	{cmd:{c -(}}
		{it:declaration3}

		...
	{cmd:{c )-}}

{p 4 4 2}
such as 

	{cmd:real matrix} myfunction({cmd:real matrix X, real scalar i})
	{
		{cmd:real scalar     j, k}
		{cmd:real vector     v}
		
		...
	}

{p 4 4 2}
{it:declaration1} is one of

		{cmd:function}
		{it:type} [{cmd:function}]
		{cmd:void} [{cmd:function}]

{p 4 4 2}
{it:declaration2} is

		[{it:type}] {it:argname} [{cmd:,} [{it:type}] {it:argname} [{cmd:,} ...]]

{p 4 4 2}
where {it:argname} is the name you wish to assign to the argument.  

{p 4 4 2}
{it:declaration3} are lines of the form of either of

		{it:type}             {it:varname} [{cmd:,} {it:varname} [{cmd:,} ...]]
		{cmd:external} [{it:type}]  {it:varname} [{cmd:,} {it:varname} [{cmd:,} ...]]

{p 4 4 2}
{it:type} is defined as one of 

		{it:eltype} {it:orgtype}{col 40}such as {cmd:real vector}
		{it:eltype} {col 40}such as {cmd:real}
		{it:orgtype}{col 40}such as {cmd:vector}

{p 4 4 2}
{it:eltype} and {it:orgtype} are each one of

		{it:eltype              orgtype}
		{hline 12}        {hline 10}{cmd}
		transmorphic        matrix
		numeric             vector 
		real                rowvector
		complex             colvector
		string              scalar
		pointer{txt}             {hline 10}
		{hline 12}

{p 4 4 2}
If {it:eltype}{bind:  }is not specified, {cmd:transmorphic} is assumed.{break}
If {it:orgtype} is not specified,{bind:    }{cmd:matrix}{bind:    }is assumed.


{title:Description}

{p 4 4 2}
Types and the use of declarations is explained.
Also discussed is the calling convention (functions are called by address, 
not by value, and so may change the caller's arguments), and the use 
of external globals.

{p 4 4 2}
Declarations are optional but, for careful work, their use is recommended.


{title:Remarks}

{p 4 4 2}
Remarks are presented under the headings

	{bf:The purpose of declarations}
	{bf:Types, element types, and organizational types}
	{bf:Implicit declarations}
	{bf:Element types}
	{bf:Organizational types}
	{bf:Function declarations}
	{bf:Argument declarations}
	{bf:The by-address calling convention}
	{bf:Variable declarations}
	{bf:Linking to external globals}


{title:The purpose of declarations}

{p 4 4 2}
Declarations occur in three places:  in front of function definitions, inside
the parentheses defining the function's arguments, and at the top of the body
of the function, defining private variables the function will use.  For
instance, consider the function

	{cmd}real matrix swaprows(real matrix A, real scalar i1, real scalar i2)
	{c -(}
		real matrix     B
		real rowvector  v

		B = A
		v = B[i1, .]
		B[i1, .] = B[i2, .]
		B[i2, .] = v
		return(B)
	{c )-}{txt}

{p 4 4 2}
This function returns a copy of matrix {cmd:A} with rows {cmd:i1} and 
{cmd:i2} swapped.

{p 4 4 2}
There are three sets of declarations in the above function.  First, there is 
a declaration in front of the function name:

	{cmd:real matrix} swaprows(...)
	{
		...
	}

{p 4 4 2}
That declaration states that this function will return a real matrix.

{p 4 4 2}
The second set of declarations occur inside the parentheses:

	... swaprows({cmd:real matrix A, real scalar i1, real scalar i2})
	{c -(}
		...
	{c )-}

{p 4 4 2}
Those declarations state that this function expects to receive three
arguments, which we chose to call {cmd:A}, {cmd:i1}, and {cmd:i2}, and which
we expect to be a real matrix, a real scalar, and a real scalar, respectively.

{p 4 4 2}
The third set of declarations occur at the top of the body of the function:

	... swaprows(...)
	{c -(}
		{cmd:real matrix     B}
		{cmd:real rowvector  v}

		...
	{c )-}

{p 4 4 2}
Those declarations state that we will use variables {cmd:B} and {cmd:v} inside
our function and that, as a matter of fact, {cmd:B} will be a real matrix and
{cmd:v} a real rowvector.

{p 4 4 2}
We could have omitted all those declarations.  Our function could have read

	{cmd}function swaprows(A, i1, i2)
	{c -(}
		B = A
		v = B[i1, .]
		B[i1, .] = B[i2, .]
		B[i2, .] = v
		return(B)
	{c )-}{txt}

{p 4 4 2}
and it would have worked just fine.  So why include the declarations?

{p 8 12 2}
    1.  By including the outside declaration, we announced to other 
        programs what to expect.  They can depend on {cmd:swaprows()} 
        returning a real matrix because, when {cmd:swaprows()} is done, Mata 
        will verify that the function really is returning a real matrix and, 
        if it is not, abort execution.

{p 12 12 2}
        Without the outside declaration, anything goes.  Our function 
        could return a real scalar in one case, a complex rowvector in 
        another, and nothing at all in yet another case.

{p 12 12 2}
        Including the outside declaration makes debugging easier.

{p 8 12 2}
    2.  By including the argument declaration, we announced to other 
        programmers what they are expected to pass to our function. 
        We have made it easier to understand our function.

{p 12 12 2}
        We have also told Mata what to expect and, if some other program 
        attempts to use our function incorrectly, Mata will stop execution.

{p 12 12 2}
        Just as in (1), we have made debugging easier.

{p 8 12 2}
    3.  By including the inside declaration, we have told Mata what 
        variables we will need and how we will be using them.  Mata
        can do two things with that information:  First, it can make 
        sure that we are using the variables correctly (making debugging 
        easier again), and second, Mata can produce more efficient code
        (making our function run faster).

{p 4 4 2}
Interactively, we admit that we sometimes define functions without
declarations.  For more careful work, however, we include them.


{title:Types, element types, and organizational types}

{p 4 4 2}
When you use Mata interactively, you just willy-nilly create new variables:

	: {cmd:n = 2}
	: {cmd:A = (1,2 \ 3,4)}
	: {cmd:z = (sqrt(-4+0i), sqrt(4))}

{p 4 4 2}
When you create a variable, you may not think about the type, but Mata does.
{cmd:n} above is, to Mata, a real scalar.  {cmd:A} is a real matrix.
{cmd:z} is a complex row vector.

{p 4 4 2}
Mata thinks of the type of a variable as having two parts: 

{p 8 12 2}
    1.  the type of the elements the variable contains (such as real or
        complex), and

{p 8 12 2}
    2.  how those elements are organized (such as a row vector or a matrix).

{p 4 4 2}
We call those two types the {it:eltype} -- element type -- and {it:orgtype} --
organizational type.  The {it:eltypes} and {it:orgtypes} are

		{it:eltype              orgtype}
		{hline 12}        {hline 10}{cmd}
		transmorphic        matrix
		numeric             vector 
		real                rowvector
		complex             colvector
		string              scalar
		pointer{txt}             {hline 10}
		{hline 12}

{p 4 4 2}
You may choose one of each and so describe all the types Mata understands.


{title:Implicit declarations}

{p 4 4 2} When you do not declare an object, Mata behaves as if you declared
it to be {cmd:transmorphic} {cmd:matrix}:

{p 8 12 2}
    1.  {cmd:transmorphic} means that the matrix can be {cmd:real},
        {cmd:complex}, {cmd:string}, or {cmd:pointer}.

{p 8 12 2}
    2.  {cmd:matrix} means that the organization is to be {it:r} {it:x}
        {it:c}, {it:r}>=0 and {it:c}>=0.

{p 4 4 2}
At one point in your function, a {cmd:transmorphic} matrix might be a
{cmd:real} {cmd:scalar} ({cmd:real} being a special case of
{cmd:transmorphic}, and {cmd:scalar} being a special case of a {cmd:matrix}
when {it:r}={it:c}=1), and at another point, it might be a {cmd:string}
{cmd:colvector} ({cmd:string} being a special case of {cmd:transmorphic}, and
{cmd:colvector} being a special case of a {cmd:matrix} when {cmd:c}=1).

{p 4 4 2}
Consider our {cmd:swaprows()} function without declarations, 

	{cmd}function swaprows(A, i1, i2)
	{c -(}
		B = A
		v = B[i1, .]
		B[i1, .] = B[i2, .]
		B[i2, .] = v
		return(B)
	{c )-}{txt}

{p 4 4 2}
The result of compiling this function is just as if the function read

	{cmd}transmorphic matrix swaprows(transmorphic matrix A, 
				     transmorphic matrix i1, 
				     transmorphic matrix i2)
	{c -(}
		transmorphic matrix     B
		transmorphic matrix     v

		B = A
		v = B[i1, .]
		B[i1, .] = B[i2, .]
		B[i2, .] = v
		return(B)
	{c )-}{txt}

{p 4 4 2}
When we declare a variable, we put restrictions on it.


{title:Element types}

{p 4 4 2}