Many functions have a single return value. For instance, empty_string_p returns a number: 1 or 0. Other functions need to return a composite value. For instance, consider a function that looks up a user's name and email address, given an ID. One way to implement this is to return a three-element list and document that the first element contains the name, and the second contains the email address. The problem with this technique is that, because Tcl does not support constants, calling procedures that returns lists in this way necessitates the use of magic numbers, e.g.:
set user_info [ad_get_user_info $user_id]
set first_name [lindex $user_info 0]
set email [lindex $user_info 1]
AOLserver/Tcl generally has three mechanisms that we like, for returning more than one value from a function. When to use which depends on the circumstances.
Using Arrays and Pass-By-Value
The one we generally prefer is returning an array get-formatted list. It has all the nice properties of pass-by-value, and it uses Tcl arrays, which have good native support.
ad_proc ad_get_user_info { user_id } {
db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
return [list name "$first_names $last_name" email $email namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" emaillink "<a href=\"mailto:$email\">$email</a>"]
}
array set user_info [ad_get_user_info $user_id]
doc_body_append "$user_info(namelink) ($user_info(emaillink))"
You could also have done this by using an array internally and using array get:
ad_proc ad_get_user_info { user_id } {
db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
set user_info(name) "$first_names $last_name"
set user_info(email) $email
set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>"
return [array get user_info]
}
Using Arrays and Pass-By-Reference
Sometimes pass-by-value incurs too much overhead, and you'd rather pass-by-reference. Specifically, if you're writing a proc that uses arrays internally to build up some value, there are many entries in the array, and you're planning on iterating over the proc many times. In this case, pass-by-value is expensive, and you'd use pass-by-reference.
The transformation of the array into a list and back to an array takes, in our test environment, approximately 10 microseconds per entry of 100 character's length. Thus you can process about 100 entries per milisecond. The time depends almost completely on the number of entries, and almost not at all on the size of the entries.
You implement pass-by-reference in Tcl by taking the name of an array as an argument and upvar it.
ad_proc ad_get_user_info {
-array:required
user_id
} {
upvar $array user_info
db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
set user_info(name) "$first_names $last_name"
set user_info(email) $email
set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>"
}
ad_get_user_info -array user_info $user_id
doc_body_append "$user_info(namelink) ($user_info(emaillink))"
We prefer pass-by-value over pass-by-reference. Pass-by-reference makes the code harder to read and debug, because changing a value in one place has side effects in other places. Especially if have a chain of upvars through several layers of the call stack, you'll have a hard time debugging.
Multisets: Using ns_sets and Pass-By-Reference
An array is a type of set, which means you can't have multiple entries with the same key. Data structures that can have multiple entries for the same key are known as a multiset or bag.
If your data can have multiple entries with the same key, you should use the AOLserver built-in ns_set. You can also do a case-insensitive lookup on an ns_set, something you can't easily do on an array. This is especially useful for things like HTTP headers, which happen to have these exact properties.
You always use pass-by-reference with ns_sets, since they don't have any built-in way of generating and reconstructing themselves from a string representation. Instead, you pass the handle to the set.
ad_proc ad_get_user_info {
-set:required
user_id
} {
db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
ns_set put $set name "$first_names $last_name"
ns_set put $set email $email
ns_set put $set namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
ns_set put $set emaillink "<a href=\"mailto:$email\">$email</a>"
}
set user_info [ns_set create]
ad_get_user_info -set $user_info $user_id
doc_body_append "[ns_set get $user_info namelink] ([ns_set get $user_info emaillink])"
We don't recommend ns_set as a general mechanism for passing sets (as opposed to multisets) of data. Not only do they inherently use pass-by-reference, which we dis-like, they're also somewhat clumsy to use, since Tcl doesn't have built-in syntactic support for them.
Consider for example a loop over the entries in a ns_set as compared to an array:
# ns_set variant
set size [ns_set size $myset]
for { set i 0 } { $i < $size } { incr i } {
puts "[ns_set key $myset $i] = [ns_set value $myset $i]"
}
# array variant
foreach name [array names myarray] {
puts "$myarray($name) = $myarray($name)"
}
And this example of constructing a value:
# ns_set variant
set myset [ns_set create]
ns_set put $myset foo $foo
ns_set put $myset baz $baz
return $myset
# array variant
return [list
foo $foo
baz $baz
]
ns_sets are designed to be lightweight, so memory consumption should not be a problem. However, when using ns_set get to perform lookup by name, they perform a linear lookup, whereas arrays use a hash table, so ns_sets are slower than arrays when the number of entries is large.
