changed foreach; updated documentation and examples