unpack: new msgpack_unpacker_next_with_size() function

This new function is an extension of the original msgpack_unpacker_next()
where it now adds third argument to store the number of parsed bytes for
the returned buffer upon a MSGPACK_UNPACK_SUCCESS case.

This is useful for cases where the caller needs to optimize memory usage
in the original buffer,s so upon success retrieval of the object, it can
later deprecate the already 'parsed' bytes.

For more details about the origins of this function please refer to the
following issue on github:

  https://github.com/msgpack/msgpack-c/issues/514

Signed-off-by: Eduardo Silva <eduardo@treasure-data.com>

include/msgpack/unpack.h

@@ -146,6 +146,18 @@ static inline void   msgpack_unpacker_buffer_consumed(msgpack_unpacker* mpac, si
 MSGPACK_DLLEXPORT
 msgpack_unpack_return msgpack_unpacker_next(msgpack_unpacker* mpac, msgpack_unpacked* pac);
 
+/**
+ * Deserializes one object and set the number of parsed bytes involved.
+ * Returns true if it successes. Otherwise false is returned.
+ * @param mpac    pointer to an initialized msgpack_unpacker object.
+ * @param result  pointer to an initialized msgpack_unpacked object.
+ * @param p_bytes pointer to variable that will be set with the number of parsed bytes.
+ */
+MSGPACK_DLLEXPORT
+msgpack_unpack_return msgpack_unpacker_next_with_size(msgpack_unpacker* mpac,
+                                                      msgpack_unpacked* result,
+                                                      size_t *p_bytes);
+
 /**
  * Initializes a msgpack_unpacked object.
  * The initialized object must be destroyed by msgpack_unpacked_destroy(msgpack_unpacker*).
@@ -267,4 +279,3 @@ static inline msgpack_zone* msgpack_unpacked_release_zone(msgpack_unpacked* resu
 #endif
 
 #endif /* msgpack/unpack.h */
-