API: retrive all users who have term $tid associacted

The main application of this function is to show list of users (who have associated certain term to them) in a taxonomy node listing page (taxonomy/term/x). The function can either be called programmatically or in future can be a basis of "Related user(s)" block(s).

Similar function:

http://api.drupal.org/api/5/function/taxonomy_select_nodes

Proposed Name:

user_tags_get_user (or "users"?)

Parameters:

$tid - my requirements need only single $tid, but in order to support the taxonomy composite views future, $tids = array() and $operator = or could be added

$depth = 0 - see the taxonomy_select_nodes for usage

Return values

1. with simple single-instance vocabulary as we have now (pseudo code):

array of $user objects

that can be passed directly to http://api.drupal.org/api/5/function/theme_user_list

2. with relation id stuff we need a 2-level array to return, relation being in first level (pseudo code)

$relations[rid] = 1
$relations[title] = "Users who have been here"
$relations[users] = array of $user objects

$relations[rid] = 2
$relations[title] = "Users who want to go here"
$relations[users] = array of $user objects

to theme the result, following pseudo code should be invoked:

foreach ($relations as $relation) {
  print theme_user_list($relation[users], $relation[title]);
}