accesslib: Introducing sort_by_roleassignment_authority()

accesslib: Introducing sort_by_roleassignment_authority()

This will help us bridge the gap from olden-style order-by
user_teachers.id. From the phpdoc...

 Will re-sort a $users results array (from get_users_by_capability(), usually)
 based on a sorting policy. This is to support the odd practice of
 sorting teachers by 'authority', where authority was "lowest id of the role
 assignment".

 Will execute 1 database query. Only suitable for small numbers of users, as it
 uses an u.id IN() clause.

 Notes about the sorting criteria.

 As a default, we cannot rely on role.sortorder because then
 admins/coursecreators will always win. That is why the sane
 rule "is locality matters most", with sortorder as 2nd
 consideration.

 If you want role.sortorder, use the 'sortorder' policy, and
 name explicitly what roles you want to cover. It's probably
 a good idea to see what roles have the capabilities you want
 (array_diff() them against roiles that have 'can-do-anything'
 to weed out admin-ish roles. Or fetch a list of roles from
 variables like $CFG->coursemanagers .

MDL-12452