Documentation and minor changes.

Author: maxim2266

Makefile

@@ -1,5 +1,5 @@
 SPEC = FIX44
-BIN = uf-test
+BIN = fullfix-test
 
 .PHONY: release debug release32
 release debug release32 : $(BIN)

README.md

@@ -1,29 +1,32 @@
 # FullFIX
 
+###### Platform: Linux
+
+###### Licence: BSD 3-clause
+
 FullFIX is a library for parsing Financial Information eXchange (FIX) messages.
 The main goal of the project is to produce the fastest software solution for FIX protocol.
+The library is written entirely in C for better portability.
 The parser does not rely on any library apart from `libc`, it does not require any
 special memory allocator and it does not impose any I/O or threading model.
-The library is written entirely in C for better portability. Unlike some other well known solutions,
-in this parser the FIX specification gets converted to C code at compile time to achieve the best performance.
+Unlike some other well known solutions, in this parser the FIX specification
+gets converted to C code at compile time to achieve the best performance.
+
+_Supported FIX protocol versions_: up to and including v4.4.
 
 ### Performance
 
-The numbers below are achieved on my 5 years old laptop with Core i5-430M 2.25GHz processor,
-on modern production hardware the results will probably be better.
+The numbers below have been achieved on my 5 years old laptop with Core i5-430M 2.25GHz processor.
+On modern production hardware the results will probably be better.
 
-Compiler: gcc (Ubuntu 4.8.4-2ubuntu1~14.04) 4.8.4
+_Compiler:_ gcc (Ubuntu 4.8.4-2ubuntu1~14.04) 4.8.4
 
-OS: Linux Mint 17.2 64bit
+_OS:_ Linux Mint 17.2 64bit
 
-FIX message type                  | FIX specification                        | Validation | Time to parse one message (average from 100 runs)
+FIX message type                  | FIX specification                        | Validation | Average time to parse one message
 ----------------------------------|------------------------------------------|------------|--------------------------------------------------
 NewOrderSingle('D')               | Hand-coded spec. for this message only   | No         | 0.335 µs/msg
 NewOrderSingle('D')               | Hand-coded spec. for this message only   | Yes        | 0.571 µs/msg
 NewOrderSingle('D')               | Compiled full spec. for FIX.4.4          | Yes        | 0.754 µs/msg
 MarketDataIncrementalRefresh('X') | Hand-coded spec. for this message only   | Yes        | 1.294 µs/msg
 MarketDataIncrementalRefresh('X') | Compiled full spec. for FIX.4.4          | Yes        | 1.435 µs/msg
-
-###### Platform: Linux
-
-###### Licence: BSD 3-clause

doc/doc.md

@@ -0,0 +1,28 @@
+### Frequently Asked Questions
+**Q.**: _This is just a parser, where is the FIX builder / composer?_
+
+**A.**: In its simplest form, composing a FIX message is mostly a `sprintf()`
+exercise, and as such is probably not worth being included into the library.
+More advanced FIX builder would include an API to add individual tag/value pairs and
+to convert the result to a plain string. Although this would be useful, there
+would be certain overhead associated with it, which would impact the performance.
+Another open issue is the amount of validation that needs to be done in this
+composer / builder. In general, the correct code will produce the correct FIX messages,
+which means there will be no need to validate the result. The same time, such a
+validation would be useful for debugging. This leads to the idea of debug-only
+validation, possibly in the spirit of `assert()` macro. Overall, at the moment
+the FIX message builder / composer is an open question.
+
+**Q.**: _How about support for FIX protocol version 5.0?_
+
+**A.**: For some reason, in the version 5.0 they introduced two layers to the
+protocol: session layer and application layer. In my opinion, the declared benefits of the
+split are by far outweighed by the complications of the implementation. Supporting
+the two layers will require one more pass over the input data and one more layer of the
+specification, which will certainly hurt the performance. The FIX protocol
+used to be good for quick exchange of very focused financial data
+and assumed a reasonably simple implementation. Not any more. I think the authors of the
+standard should at some point at least attempt to implement their protocol in
+the real code to assess on the quality of some of their decisions. That does not mean
+the support cannot be added to this library, it all depends on if there is a substantial
+amount of interest in such a support.

doc/faq.md

@@ -175,6 +175,9 @@ const fix_error_details* get_fix_group_error_details(const fix_group* const grou
 // tag as string
 fix_error get_fix_tag_as_string(const fix_group* const group, unsigned tag, fix_string* const result);
 
+// copy tag as string
+fix_error copy_fix_tag_as_string(const fix_group* const group, unsigned tag, char** const result);
+
 // tag as group
 fix_error get_fix_tag_as_group(const fix_group* const group, unsigned tag, fix_group** const result);
 
@@ -190,27 +193,27 @@ fix_error get_fix_tag_as_double(const fix_group* const group, unsigned tag, doub
 // tag as boolean
 fix_error get_fix_tag_as_boolean(const fix_group* const group, unsigned tag, bool* const result);
 
-// tag as UTCTimestamp
+// tag as utc_timestamp
 typedef struct
 {
 	unsigned short year;
 	unsigned char month, day, hour, minute, second;
 	unsigned short millisecond;
-} UTC_timestamp;
+} utc_timestamp;
 
-fix_error get_fix_tag_as_UTC_timestamp(const fix_group* const group, unsigned tag, UTC_timestamp* const result);
+fix_error get_fix_tag_as_utc_timestamp(const fix_group* const group, unsigned tag, utc_timestamp* const result);
 
-// tag as TZTimestamp
+// tag as tz_timestamp
 typedef struct
 {
-	UTC_timestamp utc;
+	utc_timestamp utc;
 	short offset_minutes;
-} TZ_Timestamp;
+} tz_timestamp;
 
-fix_error get_fix_tag_as_TZ_timestamp(const fix_group* const group, unsigned tag, TZ_Timestamp* const result);
+fix_error get_fix_tag_as_tz_timestamp(const fix_group* const group, unsigned tag, tz_timestamp* const result);
 
 // tag as LocalMktDate
-fix_error get_fix_tag_as_LocalMktDate(const fix_group* const group, unsigned tag, UTC_timestamp* const result);
+fix_error get_fix_tag_as_LocalMktDate(const fix_group* const group, unsigned tag, utc_timestamp* const result);
 
 // tag as FIX version (for ApplVerID, DefaultApplVerID and RefApplVerID)
 typedef enum
@@ -238,15 +241,14 @@ fix_error get_fix_tag_as_fix_version(const fix_group* const group, unsigned tag,
 	double*			: get_fix_tag_as_double,	\
 	bool*			: get_fix_tag_as_boolean,	\
 	char*			: get_fix_tag_as_char,	\
-	UTC_timestamp*	: get_fix_tag_as_UTC_timestamp,	\
 	fix_group**		: get_fix_tag_as_group		\
 	fix_version*	: get_fix_tag_as_fix_version	\
 	)((g), (t), (p))
 #endif
 
 // utilities -------------------------------------------------------------------------------------
-// UTC_timestamp to struct timeval converter
-fix_error UTC_timestamp_to_timeval(const UTC_timestamp* const utc, struct timeval* const result);
+// utc_timestamp to struct timeval converter
+fix_error utc_timestamp_to_timeval(const utc_timestamp* const utc, struct timeval* const result);
 
 // error message string from fix_error_details
 const char* compose_fix_error_message(const fix_error_details* const details) NOINLINE;

include/fix.h

@@ -32,6 +32,30 @@ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 #define RETURN(r)	return group->error->code = (r)
 
+// copy tag as string
+fix_error copy_fix_tag_as_string(const fix_group* const group, unsigned tag, char** const result)
+{
+	fix_string value;
+	const fix_error err = get_fix_tag_as_string(group, tag, &value);
+
+	if(err != FE_OK)
+		return err;
+
+	if(result)
+	{
+		const size_t n = fix_string_length(value);
+		char* const p = *result = malloc(n + 1);
+
+		if(!p)
+			RETURN( FE_OUT_OF_MEMORY );
+
+		memcpy(p, value.begin, n);
+		*(p + n) = 0;
+	}
+
+	return FE_OK;
+}
+
 // tag as long integer
 fix_error get_fix_tag_as_long(const fix_group* const group, unsigned tag, long* const result)
 {
@@ -225,7 +249,7 @@ fix_error get_fix_tag_as_boolean(const fix_group* const group, unsigned tag, boo
 
 // helper to read the 'YYYYMMDD' part of the time-stamp
 static
-fix_error read_date_part(const fix_group* const group, fix_string* const ps, UTC_timestamp* const ts)
+fix_error read_date_part(const fix_group* const group, fix_string* const ps, utc_timestamp* const ts)
 {
 	// format 'YYYYMMDD', where YYYY = 0000-9999, MM = 01-12, DD = 01-31
 	const char* s = ps->begin;
@@ -252,7 +276,7 @@ fix_error read_date_part(const fix_group* const group, fix_string* const ps, UTC
 
 // helper to read 'HH:MM:SS' part of the time-stamp
 static
-fix_error read_time_part(const fix_group* const group, fix_string* const ps, UTC_timestamp* const ts)
+fix_error read_time_part(const fix_group* const group, fix_string* const ps, utc_timestamp* const ts)
 {
 	// format 'HH:MM:SS.sss', where HH = 00-23, MM = 00-59, SS = 00-60 (60 only if UTC leap second).
 	const char* s = ps->begin;
@@ -283,7 +307,7 @@ fix_error read_time_part(const fix_group* const group, fix_string* const ps, UTC
 
 // helper to read 'HH:MM:SS.sss' part of the time-stamp
 static
-fix_error read_time_ms_part(const fix_group* const group, fix_string* const ps, UTC_timestamp* const ts)
+fix_error read_time_ms_part(const fix_group* const group, fix_string* const ps, utc_timestamp* const ts)
 {
 	fix_error err = read_time_part(group, ps, ts);
 
@@ -308,7 +332,7 @@ fix_error read_time_ms_part(const fix_group* const group, fix_string* const ps,
 
 // helper to read both date and time parts of the time-stamp string
 static
-fix_error read_timestamp_part(const fix_group* const group, fix_string* const ps, UTC_timestamp* const ts)
+fix_error read_timestamp_part(const fix_group* const group, fix_string* const ps, utc_timestamp* const ts)
 {
 	fix_error err = read_date_part(group, ps, ts);
 
@@ -324,8 +348,8 @@ fix_error read_timestamp_part(const fix_group* const group, fix_string* const ps
 	return FE_OK;
 }
 
-// tag as UTCTimestamp
-fix_error get_fix_tag_as_UTC_timestamp(const fix_group* const group, unsigned tag, UTC_timestamp* const result)
+// tag as utc_timestamp
+fix_error get_fix_tag_as_utc_timestamp(const fix_group* const group, unsigned tag, utc_timestamp* const result)
 {
 	// from the spec:
 	// 	string field representing Time/date combination represented in UTC (Universal Time Coordinated, also known as "GMT")
@@ -340,7 +364,7 @@ fix_error get_fix_tag_as_UTC_timestamp(const fix_group* const group, unsigned ta
 	if(err != FE_OK)
 		return err;
 
-	UTC_timestamp ts;
+	utc_timestamp ts;
 
 	err = read_timestamp_part(group, &value, &ts);
 
@@ -356,8 +380,8 @@ fix_error get_fix_tag_as_UTC_timestamp(const fix_group* const group, unsigned ta
 	return FE_OK;
 }
 
-// tag as TZTimestamp
-fix_error get_fix_tag_as_TZ_timestamp(const fix_group* const group, unsigned tag, TZ_Timestamp* const result)
+// tag as tz_timestamp
+fix_error get_fix_tag_as_tz_timestamp(const fix_group* const group, unsigned tag, tz_timestamp* const result)
 {
 	// from the spec:
 	// string field representing a time/date combination representing local time with an offset to UTC to allow
@@ -371,7 +395,7 @@ fix_error get_fix_tag_as_TZ_timestamp(const fix_group* const group, unsigned tag
 	if(err != FE_OK)
 		return err;
 
-	TZ_Timestamp ts;
+	tz_timestamp ts;
 
 	// date
 	err = read_date_part(group, &value, &ts.utc);
@@ -432,7 +456,7 @@ fix_error get_fix_tag_as_TZ_timestamp(const fix_group* const group, unsigned tag
 }
 
 // tag as LocalMktDate
-fix_error get_fix_tag_as_LocalMktDate(const fix_group* const group, unsigned tag, UTC_timestamp* const result)
+fix_error get_fix_tag_as_LocalMktDate(const fix_group* const group, unsigned tag, utc_timestamp* const result)
 {
 	// from the spec (FIX.5.0SP2_EP194):
 	// string field representing a Date of Local Market (as oppose to UTC) in YYYYMMDD format.

src/converters.c

@@ -70,8 +70,8 @@ void set_fatal_error(fix_parser* const parser, fix_error code)
 	details->context = EMPTY_STR;
 }
 
-// UTC_timestamp to struct timespec converter
-fix_error UTC_timestamp_to_timeval(const UTC_timestamp* const utc, struct timeval* const result)
+// utc_timestamp to struct timespec converter
+fix_error utc_timestamp_to_timeval(const utc_timestamp* const utc, struct timeval* const result)
 {
 	if(!utc
 		|| utc->year > 9999

src/utils.c

@@ -87,7 +87,7 @@ fix_string make_n_copies_of_multiple_messages(size_t n, const fix_string src[],
 	return (fix_string){ msg, msg + len };
 }
 
-bool equal_utc_timestamps(const UTC_timestamp* ts1, const UTC_timestamp* ts2)
+bool equal_utc_timestamps(const utc_timestamp* ts1, const utc_timestamp* ts2)
 {
 	return ts1->year == ts2->year
 		&& ts1->month == ts2->month
@@ -194,11 +194,11 @@ bool valid_boolean(fix_group* group, unsigned tag, const bool expected)
 	return true;
 }
 
-bool valid_timestamp(fix_group* group, unsigned tag, const UTC_timestamp* expected)
+bool valid_timestamp(fix_group* group, unsigned tag, const utc_timestamp* expected)
 {
-	UTC_timestamp value = { 0, 0, 0, 0, 0, 0, 0 };
+	utc_timestamp value = { 0, 0, 0, 0, 0, 0, 0 };
 
-	GET_TAG(group, tag, value, get_fix_tag_as_UTC_timestamp);
+	GET_TAG(group, tag, value, get_fix_tag_as_utc_timestamp);
 	ENSURE(equal_utc_timestamps(&value, expected), "Tag %u - value mismatch: timestamps", tag);
 	return true;
 }
@@ -405,7 +405,7 @@ bool valid_simple_message(fix_group* const group)
 
 	return valid_long(group, 		34, 	215)
 		&& valid_string(group, 		49, 	CONST_LIT("CLIENT12"))
-		&& valid_timestamp(group, 	52, 	&(UTC_timestamp){ 2010, 2, 25, 19, 41, 57, 316 })
+		&& valid_timestamp(group, 	52, 	&(utc_timestamp){ 2010, 2, 25, 19, 41, 57, 316 })
 		&& valid_char(group, 		56, 	'B')
 		&& valid_string(group, 		1, 		CONST_LIT("Marcel"))
 		&& valid_long(group, 		11, 	13346)
@@ -414,7 +414,7 @@ bool valid_simple_message(fix_group* const group)
 		&& valid_long(group, 		44, 	5)
 		&& valid_long(group, 		54, 	1)
 		&& valid_long(group, 		59, 	0)
-		&& valid_timestamp(group, 	60, 	&(UTC_timestamp){ 2010, 2, 25, 19, 39, 52, 20 });
+		&& valid_timestamp(group, 	60, 	&(utc_timestamp){ 2010, 2, 25, 19, 39, 52, 20 });
 }
 
 bool valid_message_with_groups(fix_group* const group)
@@ -427,7 +427,7 @@ bool valid_message_with_groups(fix_group* const group)
 	bool ret = valid_char(group, 		49,		'A')
 			&& valid_char(group, 		56,		'B')
 			&& valid_long(group,		34,		12)
-			&& valid_timestamp(group,	52,		&(UTC_timestamp){ 2010, 3, 18, 3, 21, 11, 364 })
+			&& valid_timestamp(group,	52,		&(utc_timestamp){ 2010, 3, 18, 3, 21, 11, 364 })
 			&& valid_char(group,		262,	'A');
 
 	if(!ret)

test/test_utils.c

@@ -52,7 +52,7 @@ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 void* check_ptr(void* p);
 fix_string make_n_copies(size_t n, const fix_string src);
 fix_string make_n_copies_of_multiple_messages(size_t n, const fix_string src[], size_t n_src);
-bool equal_utc_timestamps(const UTC_timestamp* ts1, const UTC_timestamp* ts2);
+bool equal_utc_timestamps(const utc_timestamp* ts1, const utc_timestamp* ts2);
 void print_times(const char* test_name, size_t num_messages,
 				 const struct timespec* start, const struct timespec* stop);
 
@@ -76,7 +76,7 @@ bool valid_long(fix_group* group, unsigned tag, const long expected);
 bool valid_double(fix_group* group, unsigned tag, const double expected);
 bool valid_char(fix_group* group, unsigned tag, const char expected);
 bool valid_boolean(fix_group* group, unsigned tag, const bool expected);
-bool valid_timestamp(fix_group* group, unsigned tag, const UTC_timestamp* expected);
+bool valid_timestamp(fix_group* group, unsigned tag, const utc_timestamp* expected);
 
 // parser invocations -------------------------------------------------------------------------
 // message function

test/test_utils.h

@@ -33,7 +33,7 @@ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #include <string.h>
 
 static
-bool test_UTC_timestamp_to_timeval()
+bool test_utc_timestamp_to_timeval()
 {
 	struct tm now;	// in UTC
 	const time_t t = time(NULL);
@@ -44,7 +44,7 @@ bool test_UTC_timestamp_to_timeval()
 
 	strftime(orig, sizeof(orig), "%F %T", &now);
 
-	UTC_timestamp utc =
+	utc_timestamp utc =
 	{
 		.year = now.tm_year + 1900,
 		.month = now.tm_mon + 1,
@@ -57,7 +57,7 @@ bool test_UTC_timestamp_to_timeval()
 
 	struct timeval result;
 
-	ENSURE(UTC_timestamp_to_timeval(&utc, &result) == FE_OK, "Failed conversion to timeval");
+	ENSURE(utc_timestamp_to_timeval(&utc, &result) == FE_OK, "Failed conversion to timeval");
 	ENSURE(strftime(converted, sizeof(converted), "%F %T", gmtime(&result.tv_sec)) > 0, "Failed to convert resulting time_t");
 	ENSURE(strcmp(converted, orig) == 0, "Time mismatch: original \"%s\", converted \"%s\"", orig, converted);
 	ENSURE(utc.millisecond * 1000 == result.tv_usec, "Millisecond value mismatch");
@@ -69,6 +69,6 @@ void utils_test()
 {
 	puts("# Utils tests:");
 
-	test_UTC_timestamp_to_timeval();
+	test_utc_timestamp_to_timeval();
 }
 

test/utils_test.c

@@ -52,7 +52,7 @@ if num_runs <= 0 or num_runs > 1000:
 # test invocation
 def test_results():
 	try:
-		output = subprocess.check_output('./uf-test', universal_newlines = True)
+		output = subprocess.check_output('./fullfix-test', universal_newlines = True)
 	except OSError as e:
 		die(str(e))
 	prefix = '-- '