added clear() method, documentation and example.