mf_isfleeting.hlp

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

{smcl}
{* 16mar2005}{...}
{cmd:help mata isfleeting()}
{hline}
{* index isfleeting()}{...}

{title:Title}

{p 4 8 2}
{bf:[M-5] isfleeting() -- Whether argument is temporary}


{title:Syntax}

{p 8 8 2}
{it:real scalar}
{cmd:isfleeting(}{it:polymorphic matrix A}{cmd:)}


{p 4 4 2}
where {it:A} is an argument passed to your function.


{title:Description}

{p 4 4 2}
{cmd:isfleeting(}{it:A}{cmd:)} returns 1 if {it:A} was constructed 
for the sole purpose of passing to your function, and returns 0 otherwise.
If an argument is fleeting, then you may change its contents and be 
assured that the caller will not care or even know.


{title:Remarks}

{p 4 4 2}
Let us assume you have written function {cmd:myfunc(}{it:A}{cmd:)} 
that takes {it:A}: {it:r x c} and returns an {it:r x c} matrix.
Just to fix ideas, we will pretend that the code for {cmd:myfunc()} reads

	{cmd}real matrix myfunc(real matrix A)
	{c -(}
		real scalar	i
		real matrix	B

		B=A
		for (i=1; i<=rows(B); i++) B[i,i] = 1
		return(B)
	{c )-}{txt}

{p 4 4 2}
Function {cmd:myfunc(}{it:A}{cmd:)} returns a matrix equal to {it:A}, but 
with ones along the diagonal.  Now let's imagine {cmd:myfunc()} in use.  
A snippet of the code might read

		...
		{cmd:C = A*myfunc(D)*C}
		...

{p 4 4 2}
In this case, {cmd:D} is passed to {cmd:myfunc()}, and the argument {cmd:D} is
said not to be fleeting.  Now consider another code snippet:

		...
		{cmd:D = A*myfunc(D+E)*D}
		...

{p 4 4 2}
In this code snippet, the argument passed to {cmd:myfunc()} is {cmd:D+E}
and that argument is fleeting.  It is fleeting because it 
was constructed for the sole purpose of being passed to {cmd:myfunc()}, 
and once {cmd:myfunc()} concludes, the matrix 
containing {cmd:D+E} will be discarded.

{p 4 4 2}
Arguments that are fleeting can be reused to save memory.

{p 4 4 2}
Look carefully at the code for {cmd:myfunc()}.  Note that it makes a 
copy of the matrix which it was passed.  It did that so as not to damage the
matrix it was passed.  Making that copy, however, is unnecessary if the
argument received was fleeting, because damaging something that would have
been discarded anyway does not matter.  Had we not made the copy, not only
would we have saved computer time, but we would have saved memory as well.
Function {cmd:myfunc()} could be recoded to read

	{cmd}real matrix myfunc(real matrix A)
	{c -(}
		real scalar	i
		real matrix	B

		if (isfleeting(A)) {c -(}
			for (i=1; i<=rows(A); i++) A[i,i] = 1
			return(A)
		}
		B=A
		for (i=1; i<=rows(B); i++) B[i,i] = 1
		return(B)
	{c )-}{txt}

{p 4 4 2}
In this case, we wrote separate code for the fleeting and nonfleeting cases.
That is not always necessary.  In this case, we could use a pointer to 
combine the two code blocks:

	{cmd}real matrix myfunc(real matrix A)
	{c -(}
		real scalar	i
		real matrix	B
		pointer scalar	p

		if (isfleeting(A)) p = &A
		else {c -(}
			B = A
			p = &B
		{c )-}
		for (i=1; i<=rows(*p); i++) (*p)[i,i] = 1
		return(*p)
	{c )-}{txt}

{p 4 4 2}
Many official library functions come in two flavors:
{cmd:_foo(}{it:A}{cmd:,} ...{cmd:)}, which replaces {it:A} with the
calculated result, and {cmd:foo(}{it:A}{cmd:,} ...{cmd:)}, which returns
the result leaving {it:A} unmodified.  Invariably, the code for 
{cmd:foo()} reads

	{cmd}function foo(A, {txt:...})
	{c -(}
		matrix B

		if (isfleeting(A)) {c -(}
			_foo(A, {txt:...})
			return(A)
		{c )-}
		_foo(B=A, ...)
		return(B)
	{c )-}{txt}

{p 4 4 2}
This makes function {cmd:foo()} whoppingly efficient.  If {cmd:foo()} is 
called with a temporary argument -- an argument that could be modified
without the caller being aware of it -- then no extra copy of the matrix 
is ever made.
	

{title:Conformability}

    {cmd:isfleeting(}{it:A}{cmd:)}:
		{it:A}:  {it:r x c}
	   {it:result}:  1 {it:x} 1


{title:Diagnostics}

{p 4 4 2}
{cmd:isfleeting(}{it:A}{cmd:)} returns 1 if {it:A} is fleeting and not a view.
The value returned is indeterminate if {it:A} is not an argument of the
function in which it appears, and therefore the value of {cmd:isfleeting()} is
also indeterminate when used interactively.


{title:Source code}

{p 4 4 2}
Function is built-in.


{title:Also see}

{p 4 13 2}
Manual:  {hi:[M-5] isfleeting()}

{p 4 13 2}
Online:  help for 
{bf:{help m4_programming:[M-4] programming}}
{p_end}