documented comparators
fixed list-reading helper methods