Skip to content

Commit 9629330

Browse files
committed
Added documentation link, removed expect API primer (to be moved to separate documentation page)
1 parent c54fc72 commit 9629330

File tree

1 file changed

+1
-60
lines changed

1 file changed

+1
-60
lines changed

README.md

Lines changed: 1 addition & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ MPack is a C implementation of an encoder and decoder for the [MessagePack](http
77
* Secure against untrusted data
88
* Lightweight, suitable for embedded
99
* Helpful for debugging
10-
* Extensively documented
10+
* [Extensively documented](http://ludocode.github.io/mpack/)
1111

1212
The core of MPack contains a buffered reader and writer with a custom callback to fill or flush the buffer. Helper functions can be enabled to read values of expected type, to work with files, to allocate strings automatically, to check UTF-8 encoding, and more. The MPack featureset can be configured at compile-time to set which features, components and debug checks are compiled, and what dependencies are available.
1313

@@ -68,65 +68,6 @@ If any error occurs, the writer is placed in an error state and can optionally l
6868

6969
The MPack writer API is imperative in nature. Since it's easy to incorrectly compose structured data with an imperative API, MPack provides a debug mode which tracks reads and writes of compound types to ensure that the correct number of elements and bytes were read and written. This allows for rapid development of high-performance applications that use MessagePack. In release mode, these checks are eliminated for maximum performance.
7070

71-
## The Expect API
72-
73-
The Expect API is used to imperatively parse data of a fixed (hardcoded) schema. It is useful when parsing very large mpack files or parsing in memory-constrained environments. The below example demonstrates shows reading from a file and handling errors with longjmp.
74-
75-
// open a file on disk
76-
FILE* file = fopen("example.mp");
77-
if (file == NULL) {
78-
fprintf(stderr, "An error occurred opening the file!\n");
79-
return;
80-
}
81-
82-
// initialize the reader using fread() and a stack-allocated buffer
83-
mpack_reader_t reader;
84-
mpack_reader_init_stack(&reader, mpack_fread, file);
85-
86-
// catch errors with longjmp
87-
if (MPACK_READER_SETJMP(&reader)) {
88-
fprintf(stderr, "An error occurred decoding the file!\n");
89-
mpack_reader_destroy(&reader);
90-
fclose(file);
91-
return;
92-
}
93-
94-
// we expect the file to contain the example on the msgpack homepage
95-
mpack_expect_map_match(&reader, 2);
96-
mpack_expect_cstr_match(&reader, "compact");
97-
bool compact = mpack_expect_bool(&reader);
98-
mpack_expect_cstr_match(&reader, "schema");
99-
int schema = mpack_expect_int(&reader);
100-
mpack_done_map(&reader);
101-
102-
// clean up
103-
mpack_reader_destroy(&reader);
104-
fclose(file);
105-
106-
// verify and use the data
107-
if (!compact || schema != 0) {
108-
fprintf(stderr, "The file data is invalid!\n");
109-
return;
110-
}
111-
112-
The example expects the map elements to be laid out in a specific order. If you expect map keys to be re-arranged (for example if the data is converted from JSON or encoded from an unordered map), something like this may be more appropriate:
113-
114-
bool compact = false;
115-
int schema = -1;
116-
117-
for (int i = mpack_expect_map(&reader); i > 0; --i) {
118-
char key[20];
119-
mpack_expect_cstr(&reader, key, sizeof(key));
120-
121-
if (strcmp(key, "compact") == 0)
122-
compact = mpack_expect_bool(&reader);
123-
else if (strcmp(key, "schema") == 0)
124-
schema = mpack_expect_int(&reader);
125-
else
126-
mpack_reader_flag_error(&reader, mpack_error_data);
127-
}
128-
mpack_done_map(&reader);
129-
13071
## Why Not Just Use JSON?
13172

13273
Conceptually, MessagePack stores data similarly to JSON: they are both composed of simple values such as numbers and strings, stored hierarchically in maps and arrays. So why not just use JSON instead? The main reason is that JSON is designed to be human-readable, so it is not as efficient as a binary serialization format:

0 commit comments

Comments
 (0)