Add an encoder optimized for in-memory buffers.

git-svn-id: https://svn.kapsi.fi/jpa/nanopb-dev@1088 e3a754e5-d11d-0410-8d38-ebb782a927b9

docs/index.rst

@@ -14,6 +14,7 @@ Overall structure
 
 For the runtime program, you always need *pb.h* for type declarations.
 Depending on whether you want to encode, decode, or both, you also need *pb_encode.h/c* or *pb_decode.h/c*.
+If you only encode into in-memory buffers, *pb_decode_buffer.h/c* should be slightly faster and smaller.
 
 If your *.proto* file encodes submessages or other fields using pointers, you must compile *pb_decode.c* with a preprocessor macro named *MALLOC_HEADER* that is the name of a header with definitions (either as functions or macros) for *calloc()*, *realloc()* and *free()*.  For a typical hosted configuration, this should be *<stdlib.h>*.
 
@@ -27,6 +28,7 @@ So a typical project might include these files:
     - pb.h
     - pb_decode.h and pb_decode.c (needed for decoding messages)
     - pb_encode.h and pb_encode.c (needed for encoding messages)
+    - pb_encode_buffer.h and pb_encode_buffer.c (for encoding specifically into in-memory buffers)
 2) Protocol description (you can have many):
     - person.proto (just an example)
     - person.pb.c (autogenerated, contains initializers for message descriptors)
@@ -89,6 +91,17 @@ Now in your main program do this to encode a message::
 
 After that, buffer will contain the encoded message.
 The number of bytes in the message is stored in *stream.bytes_written*.
+
+Using *pb_encode_buffer.h/c* interface is very similar::
+
+ Example mymessage = {42};
+ uint8_t buffer[10];
+ pb_strstream_t stream = pb_str_from_buffer(buffer, sizeof(buffer));
+ pb_encode_buffer(&stream, Example_msg, &mymessage);
+
+The encoded message will start at *stream.last* and continue until the
+end of *buffer* (that is, it has length *buffer - stream.last*).
+
 You can feed the message to *protoc --decode=Example message.proto* to verify its validity.
 
 For complete examples of the simple cases, see *tests/test_decode1.c* and *tests/test_encode1.c*. For an example with network interface, see the *example* subdirectory.
@@ -112,6 +125,5 @@ This also generates a file called *breakpoints* which includes all lines returni
 
 Wishlist
 ========
-#) A specialized encoder for encoding to a memory buffer. Should serialize in reverse order to avoid having to determine submessage size beforehand.
 #) A cleaner rewrite of the Python-based source generator.
 #) Better performance for 16- and 8-bit platforms: use smaller datatypes where possible.