pairs function added with test and doc