add some documentation and fixes
diff --git a/inc/qcbor/qcbor_encode.h b/inc/qcbor/qcbor_encode.h
index cce971d..86f2d11 100644
--- a/inc/qcbor/qcbor_encode.h
+++ b/inc/qcbor/qcbor_encode.h
@@ -730,7 +730,7 @@
this is always UTC and does not include the time zone. Use
QCBOREncode_AddDateString() if you want to include the time zone.
- The integer encoding rules apply here so the date will be encoded in
+ The preferred integer encoding rules apply here so the date will be encoded in
a minimal number of bytes. Until about the year 2106 these dates will
encode in 6 bytes -- one byte for the tag, one byte for the type and
4 bytes for the integer. After that it will encode to 10 bytes.
@@ -775,8 +775,22 @@
+/**
+ @brief Add an epoch-based day-count date.
+ @param[in] pCtx The encoding context to add the date to.
+ @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ @ref QCBOR_ENCODE_AS_BORROWED.
+ @param[in] nDays Number of days before or after 1970-01-0.
+ This date format is described in
+ [RFC 8943] (https://tools.ietf.org/html/rfc3339).
+
+ The integer encoding rules apply here so the date will be encoded in
+ a minimal number of bytes. Until about the year 2149 these dates will
+ encode in 4 bytes -- one byte for the tag, one byte for the type and
+ 2 bytes for the integer.
+*/
static void QCBOREncode_AddTDaysEpoch(QCBOREncodeContext *pCtx,
uint8_t uTagRequirement,
int64_t nDays);
@@ -794,8 +808,6 @@
-
-
/**
@brief Add a byte string to the encoded output.
@@ -1424,6 +1436,8 @@
CBOR will be incorrect and the receiver may not be able to handle it.
Error handling is the same as QCBOREncode_AddInt64().
+
+ See also QCBOREncode_AddTDayString().
*/
static void QCBOREncode_AddTDateString(QCBOREncodeContext *pCtx,
uint8_t uTagRequirement,
@@ -1451,7 +1465,32 @@
int64_t nLabel,
const char *szDate);
-// TODO: document this
+
+/**
+ @brief Add a date-only string.
+
+ @param[in] pCtx The encoding context to add the date to.
+ @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ @ref QCBOR_ENCODE_AS_BORROWED.
+ @param[in] szDate Null-terminated string with date to add.
+
+ This date format is described in
+ [RFC 8943] (https://tools.ietf.org/html/rfc3339), but that mainly
+ references RFC 3339. The string szDate must be in the forrm
+ specified the ABNF for a full-date in
+ [RFC 3339] (https://tools.ietf.org/html/rfc3339). Examples of this
+ are "1985-04-12" and "1937-01-01". The time and the time zone are
+ never included.
+
+ Note that this function doesn't validate the format of the date
+ string at all. If you add an incorrect format date string, the
+ generated CBOR will be incorrect and the receiver may not be able to
+ handle it.
+
+ Error handling is the same as QCBOREncode_AddInt64().
+
+ See also QCBOREncode_AddTDateString().
+ */
static void
QCBOREncode_AddTDaysString(QCBOREncodeContext *pCtx,
uint8_t uTagRequirement,
diff --git a/src/qcbor_decode.c b/src/qcbor_decode.c
index 409b746..dcc955b 100644
--- a/src/qcbor_decode.c
+++ b/src/qcbor_decode.c
@@ -3882,13 +3882,19 @@
}
+
+/*
+ * Common processing for the RFC 8943 Day-count tag. Mostly
+ * make sure the tag content is correct and copy forward any
+ * further other tag numbers.
+ */
static void ProcessEpochDays(QCBORDecodeContext *pMe,
- QCBORItem *pItem,
- uint8_t uTagRequirement,
- int64_t *pnTime)
+ QCBORItem *pItem,
+ uint8_t uTagRequirement,
+ int64_t *pnDays)
{
if(pMe->uLastError != QCBOR_SUCCESS) {
- // Already in error state, do nothing
+ /* Already in error state, do nothing */
return;
}
@@ -3913,53 +3919,64 @@
}
}
- // Save the tags in the last item's tags in the decode context
- // for QCBORDecode_GetNthTagOfLast()
+ /* Save the tags in the last item's tags in the decode context
+ * for QCBORDecode_GetNthTagOfLast()
+ */
CopyTags(pMe, pItem);
- *pnTime = pItem->val.epochDate.nSeconds;
+ *pnDays = pItem->val.epochDays;
Done:
pMe->uLastError = (uint8_t)uErr;
}
+
+/*
+ * Public function, see header qcbor/qcbor_decode.h
+ */
void QCBORDecode_GetEpochDays(QCBORDecodeContext *pMe,
uint8_t uTagRequirement,
- int64_t *pnTime)
+ int64_t *pnDays)
{
if(pMe->uLastError != QCBOR_SUCCESS) {
- // Already in error state, do nothing
+ /* Already in error state, do nothing */
return;
}
QCBORItem Item;
pMe->uLastError = (uint8_t)QCBORDecode_GetNext(pMe, &Item);
- ProcessEpochDays(pMe, &Item, uTagRequirement, pnTime);
+ ProcessEpochDays(pMe, &Item, uTagRequirement, pnDays);
}
+/*
+ * Public function, see header qcbor/qcbor_decode.h
+ */
void
QCBORDecode_GetEpochDaysInMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
uint8_t uTagRequirement,
- int64_t *pnTime)
+ int64_t *pnDays)
{
QCBORItem Item;
QCBORDecode_GetItemInMapN(pMe, nLabel, QCBOR_TYPE_ANY, &Item);
- ProcessEpochDays(pMe, &Item, uTagRequirement, pnTime);
+ ProcessEpochDays(pMe, &Item, uTagRequirement, pnDays);
}
+/*
+ * Public function, see header qcbor/qcbor_decode.h
+ */
void
QCBORDecode_GetEpochDaysInMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
uint8_t uTagRequirement,
- int64_t *pnTime)
+ int64_t *pnDays)
{
QCBORItem Item;
QCBORDecode_GetItemInMapSZ(pMe, szLabel, QCBOR_TYPE_ANY, &Item);
- ProcessEpochDays(pMe, &Item, uTagRequirement, pnTime);
+ ProcessEpochDays(pMe, &Item, uTagRequirement, pnDays);
}
diff --git a/test/qcbor_decode_tests.c b/test/qcbor_decode_tests.c
index 2c2f2a7..283199d 100644
--- a/test/qcbor_decode_tests.c
+++ b/test/qcbor_decode_tests.c
@@ -2827,12 +2827,12 @@
uTag2 = QCBORDecode_GetNthTagOfLast(&DC, 0);
/* The days format is much simpler than the date format
- because it can't be a floating point value. The test
- of the spiffy decode functions sufficiently covers
- the test of the non-spiffy decode days date decoding.
- There is no full fan out of the error conditions
- and decode options as that is implemented by code
- that is tested well by the date testing above.
+ * because it can't be a floating point value. The test
+ * of the spiffy decode functions sufficiently covers
+ * the test of the non-spiffy decode days date decoding.
+ * There is no full fan out of the error conditions
+ * and decode options as that is implemented by code
+ * that is tested well by the date testing above.
*/
QCBORDecode_GetDaysStringInMapSZ(&DC, "SDS", QCBOR_TAG_REQUIREMENT_TAG,
&StringDays1);