In many cases, a single return value for a method is not enough. You need a way to return more than one item from a method.
Use the out
keyword on
parameters that will act as return parameters. The following method
accepts an inputShape
parameter and calculates
height
, width
, and
depth
from that
value:
public void ReturnDimensions(int inputShape, out int height, out int width, out int depth) { height = 0; width = 0; depth = 0; // Calculate height, width, depth from the inputShape value }
This method would be called in the following manner:
// Declare output parameters int height; int width; int depth; // Call method and return the height, width, and depth Obj.ReturnDimensions(1, out height, out width, out depth);
Another method is to return a class or structure containing all the
return values. The previous method has been modified to return a
structure instead of using out
arguments:
public Dimensions ReturnDimensions(int inputShape) { // The default ctor automatically defaults this structure's members to 0 Dimensions objDim = new Dimensions( ); // Calculate objDim.Height, objDim.Width, objDim.Depth from the inputShape value return (objDim); }
where Dimensions
is defined as follows:
public struct Dimensions { int Height; int Width; int Depth; }
This method would now be called in this manner:
// Call method and return the Height, Width, and Depth Dimensions objDim = obj.ReturnDimensions(1);
Marking a parameter in a method signature with the
out
keyword indicates that this parameter will be
initialized and returned by this method. This trick is useful when a
method is required to return more than one value. A method can, at
most, have only one return value, but through the use of the
out
keyword, we can mark several parameters as a
kind of return value.
To set up an out
parameter, the parameter in the
method signature is marked with the out
keyword,
shown here:
public void ReturnDimensions(int inputShape, out int height, out int width, out int depth) { ... }
To call this method, we must also mark the calling
method’s arguments with the out
keyword, shown here:
obj.ReturnDimensions(1, out height, out width, out depth);
The out
arguments in this method call do not have
to be initialized; they can simply be declared and passed in to the
ReturnDimensions
method. Regardless of whether
they are initialized before the method call, they must be initialized
before they are used within the ReturnDimensions
method. Even if they are not used through every path in the
ReturnDimensions
method, they still must be
initialized. That is why this method starts out with the following
three lines of code:
height = 0; width = 0; depth = 0;
You may be wondering why you couldn’t use a
ref
parameter instead of the
out
parameter, as they both allow a method to
change the value of an argument marked as such. The answer is that an
out
parameter makes the code somewhat
self-documenting. You know that when an out
parameter is encountered, this parameter is acting as a return value.
In addition, an out
parameter does not require the
extra work to be initialized before it is passed in to the method,
which a ref
parameter does.
The out
parameter was originally designed for
marshaling scenarios. An out
parameter does not
have to be marshaled when the method is called; rather, it is
marshaled once when the method returns the data to the caller. Any
other type of call (by-value or by-reference) requires that the value
be marshaled in both directions. Using the out
keyword in marshaling scenarios improves performance.