add search() method, more tests and docs, refs #2