Json cleanup and improvements

[aochagavia]

Breaking changes:

• Removed unnecessary box from enum variant (Object(Box<Object>) becomes Object(Object))
• Deprecated Encoder::str_encode

Other changes:

• Tried to make the code more idiomatic
• Renamed the wr field of the Encoder and PrettyEncoder structs to writer
• Replaced some from_utf8 by from_utf8_owned to avoid unnecessary allocations
• Removed unnecessary unsafe code
• Added encode and decode shortcut functions
• Implemented FromStr for Json
• Implemented ToJson for tuples of arity up to 12
• Fixed some details in the documentation

Questions

• The encode shortcut function does the same as the Encoder::str_encode function. It seems wrong to me that two functions do exactly the same. Should we deprecate Encoder::str_encode?
• Do we really want the ToJson trait for tuples? At the moment we have it for (), (A, B), (A, B, C). I would like to remove them.
• We are using String as key in the TreeMap representing a Json object. It would be better to use &str, but this would require to annotate lots of lifetimes. Is there any easy solution for this?
• There is a lot of duplicated code (PrettyEncoder copies about 50 lines from Encoder). In an OO language this could be solved very elegantly by using inheritance and overriding. What can we do here to reduce the amount of boilerplate?

[breaking-change]

[huonw]

• Deprecated the ToJson trait implementation for the Json struct. People should use Clone instead.
• Do we really want the ToJson trait for tuples? At the moment we have it for (), (A, B), (A, B, C). I would like to remove them.

Why?

We are using String as key in the TreeMap representing a Json object. It would be better to use &str, but this would require to annotate lots of lifetimes. Is there any easy solution for this?

It's not feasible to use &str, as then a Json object isn't able to be freely passed around: it will require all the keys to be owned by something outside it, and so will be "controlled" by that object (e.g. it would not be (easily) possible to pass a Json object between tasks, or return it from the stack frame containing the "key owner").

[aochagavia]

Calling to_json() in a Json object is equivalent to calling clone(). I thought this was enough reason to remove it. Do you think we should keep it?

Now I consider it again, I think it is good to keep ToJson for tuples, because they can be used to build Json lists of elements of different types. Maybe we could implement this trait for longer tuples by using a macro. If you think this is a good idea I can give it a try (however, I don't know if I can do it with my current macro skills).

[huonw]

Calling to_json() in a Json object is equivalent to calling clone(). I thought this was enough reason to remove it. Do you think we should keep it?

Its main purpose would be generic code, allowing Json to be used in the same manner as other things (e.g. the same reason that &str implements Str).

Maybe we could implement this trait for longer tuples by using a macro. If you think this is a good idea I can give it a try (however, I don't know if I can do it with my current macro skills).

That would be the desirable approach. Here's an example you can build from, if you do wish to try.

[aochagavia]

@huonw I have addressed your comments. ToJson is no longer deprecated for Json and it is now implemented for tuples of arity up to 12.

[alexcrichton]

This seems like a legitimate possibility for a decode error, why unwrap here?

[aochagavia]

You are right.... I should use try! here instead of unwrap

[aochagavia]

It looks like the Travis build timed out

[aochagavia]

It looks like the code snippets in the documentation had unused imports. I have removed them, so everything should be fine now.