NetLogo: the meaning of TO-REPORT explained for dummies?

Question

I have a problem to understand the role of to-report and report in NetLogo, even it seems pretty useful and I can't really find a help written in "human style" language.

In NetLogo dictionnary http://ccl.northwestern.edu/netlogo/docs/dictionary.html#report I can find definitions for to-report :

to-report procedure-name
to-report procedure-name [input1 ...]
Used to begin a reporter procedure.

The body of the procedure should use report to report a value for the procedure. See report. 

and for report:

report value
Immediately exits from the current to-report procedure and reports value as the result of that procedure. report and to-report are always used in conjunction with each other. See to-report for a discussion of how to use them.

So, it seems to-report and report calculate some value and report it.

Thus, when I try add

to-report average [a b c]
  report (a + b + c) / 2
end

to my code, and then use the average variable somewhere in my code p.e.:

to go 
  ...
  print average 
  tick
end

I've got an error: AVERAGE expected 3 inputs. When I try to create my variables [a b c] in globals [a b c] I've got an error There is already a global variable called A. If I define my variables [a b c] within to-report procedure:

to-report average [a b c]
    set a 1
  set b 2
  set c 3
  report (a + b + c) / 2
end

My error is again AVERAGE expected 3 inputs.

Thus, how can I simply test the usefulness of to-report procedure? And where to place it correctly in my code to see what it is really doing? From Urban Suite - Economic Disparity (http://ccl.northwestern.edu/netlogo/models/UrbanSuite-EconomicDisparity) I see that to-report is used to calculate values related to each patch:

to-report patch-utility-for-poor
    report ( ( 1 / (sddist / 100 + 0.1) ) ^ ( 1 - poor-price-priority ) ) * ( ( 1 / price ) ^ ( 1 + poor-price-priority ) )
end

however this reported value is not directly defined as patch variable which increase my confusion...

Thank you !

Answer 1

A function can take some input (usually one or more variables or values) and return some output (usually a single value). You can specify that a function returns a value using to-report in your function header and report returns the actual value.

Your error is due to the fact that you never passed in arguments to your average function

to go 
  ...
  print average 
  tick
end

should be

to go 
  ...
  print average 5 2 3 ;;a = 5, b = 2, c =3
  tick
end

Inside your average function, you should not reassign values of a,b,and c.

You should use report whenever you want to return a result from a function.