1. Jens Alfke
  2. fudge-cpp

Commits

Jens Alfke  committed 74ff211

Tweaks to the readme.

  • Participants
  • Parent commits f0d86ec
  • Branches default

Comments (0)

Files changed (1)

File README.md

View file
 
 by Jens Alfke -- (c)2011
 
-**Fudge-Cpp** is a C++ library for reading and writing [Fudge](http://fudgemsg.org/), "a binary messaging system designed to scale from ad-hoc messages to long-term persistance." Fudge is somewhat similar in semantics to JSON, but uses a binary encoding that's more compact and faster to parse.
+**Fudge-Cpp** is a C++ library for reading and writing [Fudge](http://fudgemsg.org/), "a binary
+messaging system designed to scale from ad-hoc messages to long-term persistance." Fudge is somewhat
+similar in semantics to JSON, but uses a binary encoding that's more compact and faster to parse.
 
-Fudge-Cpp's advantages over the existing Fudge-C library are:
+Fudge-Cpp's advantages over the existing [Fudge-C](http://github.com/vrai/Fudge-C) library are:
 
 * Simpler, idiomatic C++ API using classes.
 * Integrates with STL and iostreams.
-* Uses less memory -- in fact, it allocates _no heap space at all_ unless you use STL string accessors. When you access the fields in a message, the objects returned to you are really pointers directly into the existing binary message data. When you write a message, the library writes directly to the output stream without needing any heap space for bookkeeping.
+* Uses less memory -- in fact, it allocates _no heap space at all_ unless you use STL string
+  accessors. When you access the fields in a message, the objects returned to you are really
+  pointers directly into the existing binary message data. When you write a message, the library
+  writes directly to the output stream without needing any heap space for bookkeeping.
 
-**Fudge-Cpp** is intended to be cross-platform, but the current version still has some OS X dependencies, primarily for byte-swapping. Fixes for these are welcome :)
+**Fudge-Cpp** is intended to be cross-platform, but the current version still has some OS X
+dependencies, primarily for byte-swapping. Fixes for these are welcome :)
+
+## Examples ##
+
+Writing a simple message with a few fields into an in-memory string object:
+
+    std::stringstream out;
+    Writer writer(out);
+    writer.addInt(1234);
+    writer.addString("Fudge!");
+    writer.end();
+    std::string fudgeData = out.str();   // binary 'string', not human-readable
+
+Writing a JSON-style dictionary directly to a file:
+
+    std::ofstream out("/tmp/fudgetest.dat");
+    Writer writer(out);
+    writer.setNextName("key1");
+    writer.addString("value1");
+    writer.setNextName("key2");
+    Message nested = writer.beginMessage();
+    nested.addDouble(3.14159);
+    nested.addDouble(2.71828);
+    nested.end();
+    writer.end();
+    out.close();
+
+Parsing the Fudge message generated by the first example:
+
+    const Envelope* envelope = Envelope::FromBytes(fudgeData);
+    Message msg = envelope->message();
+    Message::iterator i = msg.begin();
+    int value = i->asInt32();
+
+Writing the above Fudge message as JSON:
+
+    WriteJSON(envelope, std::cout);
+
+The test cases in the "test" subdirectory show many examples of using the complete API.