Meaning of in, out and inout

May 10, 2005
Re: Meaning of in, out and inout
Posted by Derek Parnell
in reply to Oliver
Permalink
Derek Parnell
Posted in reply to Oliver
Permalink
On Tue, 10 May 2005 00:30:57 +0000 (UTC), Oliver wrote:

> Hello D-ers
> 
> The documentation is very short on the keywords in, out and inout.
> Is is inout sth like a reference ? But then, what is in and what is out?


in:
The argument is preserved, such that when control returns to the caller,
the argument as passed by the caller is unchanged. This means that the
called function can do anything it likes to the argument but those changes
are never returned back to the caller. There is a bit of confusion here
when it comes to passing class objects and dynamic arrays. In both these
cases, a reference to the data is passed. Which means that for 'in'
references, the called function is free to modify the reference data (which
is what is actually passed) in the full knowledge that any changes will
*not* be returned to the caller. However, if you make any changes to the
data being referenced, that modified data is 'returned'. Which means that,
for example, if you pass a char[] variable, the reference will be preserved
but the data in the string can be changed.

out:
The argument is always initialized automatically by the called function
before its code is executed. Any changes to the argument by the called
function are returned to the caller. The called function never gets to see
the value of the argument as it was before the called function gets
control. The argument must a RAM item and not a literal or temporary value.

inout:
The argument is passed to the called function without before its code is
executed. Any changes to the argument by the called function are returned
to the caller. In other words, the called function can see what value was
passed to it before changing it.  The argument must a RAM item and not a
literal or temporary value.


Examples:

  char[] a;
  int    b;

  void func_one(in char[] X, in int Y)
  {
      X[0] = 'a';   // Modifies the string contents.
      X = "zxcvb";  // Modifies the string reference but is not returned.

      Y = 3; // Modifies the data but is not returned.
  }


  a = "qwerty";
  b = 1;
  func_one(a,b);

  writefln("%s %d", a,b); // --> awerty 1

  void func_two(out char[] X, out int Y)
  {
      X[0] = 'a';   // Modifies the string contents.
      X = "zxcvb";  // Modifies the string reference.
      if (b == 1)
        Y = 3; // never executed because Y is always zero on entry.
      else
        Y = 4; // Modifies the data.
  }


  a = "qwerty";
  b = 1;
  func_two(a,b);

  writefln("%s %d", a,b); // --> zxcvb 4

  void func_three(inout char[] X, inout int Y)
  {
      X[0] = 'a';   // Modifies the string contents.
      X = "zxcvb";  // Modifies the string reference.
      if (b == 1)
        Y = 3; // Modifies the data.
      else
        Y = 4; // Modifies the data.
  }


  a = "qwerty";
  b = 1;
  func_two(a,b);

  writefln("%s %d", a,b); // --> zxcvb 3

-- 
Derek
Melbourne, Australia
10/05/2005 10:46:13 AM
Forums
