Change sample type for text encoding to 't', value 'a' still supported

Author: chad-earthscope

ChangeLog

@@ -1,5 +1,6 @@
 2023.160:
 	- Add FAQ to documentation and update example code to match API changes.
+	- Change sample type for text encoding to 't', value 'a' still supported.
 
 2023.159:
 	WARNING: API change as follows:

example/lm_pack.c

@@ -191,7 +191,7 @@ main (int argc, char **argv)
   {
     msr->numsamples  = strlen (textdata);
     msr->datasamples = textdata;
-    msr->sampletype  = 'a';
+    msr->sampletype  = 't';
   }
   else if (encoding == DE_FLOAT32)
   {

example/lm_parse.c

@@ -109,25 +109,25 @@ main (int argc, char **argv)
         {
           ms_log (2, "Unrecognized sample type: '%c'\n", msr->sampletype);
         }
-        if (msr->sampletype == 'a')
+        if (msr->sampletype == 't')
         {
-          char *ascii = (char *)msr->datasamples;
+          char *text = (char *)msr->datasamples;
           int length  = msr->numsamples;
 
-          ms_log (0, "ASCII Data:\n");
+          ms_log (0, "Text data:\n");
 
           /* Print maximum log message segments */
           while (length > (MAX_LOG_MSG_LENGTH - 1))
           {
-            ms_log (0, "%.*s", (MAX_LOG_MSG_LENGTH - 1), ascii);
-            ascii += MAX_LOG_MSG_LENGTH - 1;
+            ms_log (0, "%.*s", (MAX_LOG_MSG_LENGTH - 1), text);
+            text += MAX_LOG_MSG_LENGTH - 1;
             length -= MAX_LOG_MSG_LENGTH - 1;
           }
 
-          /* Print any remaining ASCII and add a newline */
+          /* Print any remaining TEXT and add a newline */
           if (length > 0)
           {
-            ms_log (0, "%.*s\n", length, ascii);
+            ms_log (0, "%.*s\n", length, text);
           }
           else
           {

example/lm_read_recordlist.c

@@ -154,7 +154,7 @@ main (int argc, char **argv)
         {
           ms_log (0, "DATA (%" PRId64 " samples) of type '%c':\n", seg->numsamples, seg->sampletype);
 
-          if (sampletype == 'a')
+          if (sampletype == 't')
           {
             printf ("%*s",
                     (seg->numsamples > INT_MAX) ? INT_MAX : (int)seg->numsamples,

libmseed.h

@@ -331,7 +331,7 @@ extern int ms_md2doy (int year, int month, int mday, int *yday);
     @brief Data sample types used by the library.
 
     Sample types are represented using a single character as follows:
-    - \c 'a' - Text (ASCII) data samples
+    - \c 't' - Text data samples
     - \c 'i' - 32-bit integer data samples
     - \c 'f' - 32-bit float (IEEE) data samples
     - \c 'd' - 64-bit float (IEEE) data samples

lookup.c

@@ -27,7 +27,7 @@
  *
  * @param[in] sampletype Library sample type code:
  * @parblock
- *   - \c 'a' - Text/ASCII data type
+ *   - \c 't' - Text data type
  *   - \c 'i' - 32-bit integer data type
  *   - \c 'f' - 32-bit float data type
  *   - \c 'd' - 64-bit float (double) data type
@@ -40,6 +40,7 @@ ms_samplesize (const char sampletype)
 {
   switch (sampletype)
   {
+  case 't':
   case 'a':
     return 1;
     break;
@@ -78,7 +79,7 @@ ms_encoding_sizetype (const uint8_t encoding, uint8_t *samplesize, char *samplet
     if (samplesize)
       *samplesize = 1;
     if (sampletype)
-      *sampletype = 'a';
+      *sampletype = 't';
     break;
   case DE_INT16:
   case DE_INT32:

pack.c

@@ -71,7 +71,7 @@ static uint32_t ms_timestr2btime (const char *timestr, uint8_t *btime, char *sid
  *
  * The following data encodings and expected @ref MS3Record.sampletype
  * are supported:
- *   - ::DE_TEXT (0), Text, expects type \c 'a'
+ *   - ::DE_TEXT (0), Text, expects type \c 't'
  *   - ::DE_INT16 (1), 16-bit integer, expects type \c 'i'
  *   - ::DE_INT32 (3), 32-bit integer, expects type \c 'i'
  *   - ::DE_FLOAT32 (4), 32-bit float (IEEE), expects type \c 'f'
@@ -229,7 +229,7 @@ msr3_pack_mseed3 (MS3Record *msr, void (*record_handler) (char *, int, void *),
   /* Short cut: if there are no samples, record packing is complete */
   if (msr->numsamples <= 0)
   {
-    /* Set encoding to ASCII for consistency and to reduce expectations */
+    /* Set encoding to text for consistency and to reduce expectations */
     *pMS3FSDH_ENCODING(rawrec) = DE_TEXT;
 
     /* Calculate CRC (with CRC field set to 0) and set */
@@ -662,7 +662,7 @@ msr3_pack_mseed2 (MS3Record *msr, void (*record_handler) (char *, int, void *),
   /* Short cut: if there are no samples, record packing is complete */
   if (msr->numsamples <= 0)
   {
-    /* Set encoding to ASCII for consistency and to reduce expectations */
+    /* Set encoding to text for consistency and to reduce expectations */
     *pMS2B1000_ENCODING (rawrec + 48) = DE_TEXT;
 
     /* Set empty part of record to zeros */
@@ -1580,15 +1580,15 @@ msr_pack_data (void *dest, void *src, int maxsamples, int maxdatabytes,
   switch (encoding)
   {
   case DE_TEXT:
-    if (sampletype != 'a')
+    if (sampletype != 't' && sampletype != 'a')
     {
-      ms_log (2, "%s: Sample type must be ascii (a) for ASCII text encoding not '%c'\n",
+      ms_log (2, "%s: Sample type must be text (t) for text encoding not '%c'\n",
               sid, sampletype);
       return -1;
     }
 
     if (verbose > 1)
-      ms_log (0, "%s: Packing ASCII data\n", sid);
+      ms_log (0, "%s: Packing text data\n", sid);
 
     nsamples = msr_encode_text ((char *)src, maxsamples, (char *)dest, maxdatabytes);
 

packdata.c

@@ -1,5 +1,5 @@
 /***********************************************************************
- * Routines for packing text/ASCII, INT_16, INT_32, FLOAT_32, FLOAT_64,
+ * Routines for packing Text, INT_16, INT_32, FLOAT_32, FLOAT_64,
  * STEIM1 and STEIM2 data records.
  *
  * This file is part of the miniSEED Library.

test/test-write.c

@@ -52,7 +52,7 @@ TEST (write, msr)
   msr->encoding    = DE_TEXT;
   msr->numsamples  = strlen (textdata);
   msr->datasamples = textdata;
-  msr->sampletype  = 'a';
+  msr->sampletype  = 't';
 
   rv = msr3_writemseed (msr, TESTFILE_TEXT_V3, 1, flags, 0);
   REQUIRE (rv > 0, "msr3_writemseed() return unexpected value");
@@ -131,7 +131,7 @@ TEST (write, msr)
   msr->encoding    = DE_TEXT;
   msr->numsamples  = strlen (textdata);
   msr->datasamples = textdata;
-  msr->sampletype  = 'a';
+  msr->sampletype  = 't';
 
   rv = msr3_writemseed (msr, TESTFILE_TEXT_V2, 1, flags, 0);
   REQUIRE (rv > 0, "msr3_writemseed() return unexpected value");

tracelist.c

@@ -1366,7 +1366,7 @@ mstl3_add_recordptr (MS3TraceSeg *seg, MS3Record *msr, nstime_t endtime, int8_t
  * @brief Convert the data samples associated with an MS3TraceSeg to another
  * data type
  *
- * ASCII data samples cannot be converted, if supplied or requested an
+ * Text data samples cannot be converted, if supplied or requested an
  * error will be returned.
  *
  * When converting float & double sample types to integer type a
@@ -1413,9 +1413,9 @@ mstl3_convertsamples (MS3TraceSeg *seg, char type, int8_t truncate)
   if (seg->sampletype == type)
     return 0;
 
-  if (seg->sampletype == 'a' || type == 'a')
+  if (seg->sampletype == 't' || type == 't' || seg->sampletype == 'a' || type == 'a')
   {
-    ms_log (2, "Cannot convert ASCII samples to/from numeric type\n");
+    ms_log (2, "Cannot convert text samples to/from numeric type\n");
     return -1;
   }
 
@@ -1929,7 +1929,7 @@ mstl3_unpack_recordlist (MS3TraceID *id, MS3TraceSeg *seg, void *output,
  * record_handler() returns.
  *
  * The requested \a encoding value is currently only used for integer
- * data samples. The encoding is set automatially for text (ASCII) and
+ * data samples. The encoding is set automatially for text and
  * floating point data samples as there is only a single encoding for
  * them.  A value of \c -1 can be used to request the default.
  *
@@ -2037,7 +2037,7 @@ mstl3_pack (MS3TraceList *mstl, void (*record_handler) (char *, int, void *),
       /* Set encoding for data types with only one encoding, otherwise requested */
       switch (seg->sampletype)
       {
-      case 'a':
+      case 't':
         msr->encoding = DE_TEXT;
         break;
       case 'f':