Update GMT_IS_REFERENCE and GMT_IS_DUPLICATE to allow duplicating strings (#3718) (#3777)

* Debug GMT_Put_Strings

* SHift GMT_IS_DUPLICATE,REFERENCE and allow for string duplication

GMT_Put_Strings only worked by reference.  Now, we can accept a family argument such as GMT_IS_VECTOR|GMT_IS_DUPLICATE (or GMT_IS_REFERENCE which is the default) and it will duplicate the array string if requested.

* Adjust these enums to allow future use in GMT_Put_Vector|Matrix

* Update gmt_enum_dict.h

* Possible clash with GMT_VIA_MODULE_INPUT

* Update gmt_enum_dict.h

* Update gmt_enum_dict.h and testapi_vector_strings2.c

* Update api.rst

* Update gmt_api.c

* Update gmt_api.c

* Add debug messages

* check for directory

* Update gmt_io.c

Co-authored-by: Paul Wessel <[email protected]>

Co-authored-by: Dongdong Tian <[email protected]>
Co-authored-by: Paul Wessel <[email protected]>

Author: 3 people

doc/rst/source/api.rst

@@ -1352,9 +1352,11 @@ array of text strings, one per row.  This is done via
 
 where ``family`` is either GMT_IS_VECTOR or GMT_IS_MATRIX, ``X`` is either a
 :ref:`GMT_VECTOR <struct-vector>` or :ref:`GMT_MATRIX <struct-matrix>`, and
-``array`` is the a pointer to your string array.
+``array`` is the a pointer to your string array.  You may add ``GMT_IS_DUPLICATE`` to
+``family`` to indicate you want the array of strings to be duplicated; the default
+is to just set a pointer to ``array``.
 
-To extract the string array from an output vector or matrix container you will use
+To access the string array from an output vector or matrix container you will use
 
 .. _GMT_Get_Strings:
 

src/gmt_api.c

@@ -138,7 +138,7 @@ static struct GMT_API_DICT gmt_api_enums[GMT_N_API_ENUMS] = {
 	{"GMT_IS_COL_FORMAT", 2},
 	{"GMT_IS_COORD", 7},
 	{"GMT_IS_DATASET", 0},
-	{"GMT_IS_DUPLICATE", 3},
+	{"GMT_IS_DUPLICATE", 16},
 	{"GMT_IS_FDESC", 2},
 	{"GMT_IS_FILE", 0},
 	{"GMT_IS_GRID", 1},
@@ -155,7 +155,7 @@ static struct GMT_API_DICT gmt_api_enums[GMT_N_API_ENUMS] = {
 	{"GMT_IS_POINT", 1},
 	{"GMT_IS_POLY", 4},
 	{"GMT_IS_POSTSCRIPT", 4},
-	{"GMT_IS_REFERENCE", 4},
+	{"GMT_IS_REFERENCE", 32},
 	{"GMT_IS_ROW_FORMAT", 1},
 	{"GMT_IS_STREAM", 1},
 	{"GMT_IS_SURFACE", 8},

src/gmt_enum_dict.h

@@ -120,8 +120,8 @@ enum GMT_enum_method {
 	GMT_IS_FILE	 =    0,	/* Entity is a filename */
 	GMT_IS_STREAM	 =    1,	/* Entity is an open stream */
 	GMT_IS_FDESC	 =    2,	/* Entity is an open file descriptor */
-	GMT_IS_DUPLICATE =    3,	/* Entity is a memory location that should be duplicated */
-	GMT_IS_REFERENCE =    4,	/* Entity is a memory location that should be referenced */
+	GMT_IS_DUPLICATE =   16,	/* Entity is a memory location that should be duplicated */
+	GMT_IS_REFERENCE =   32,	/* Entity is a memory location that should be referenced */
 	GMT_IS_OUTPUT	 = 1024		/* When creating a resource as a container for output */
 };
 

src/gmt_resources.h

@@ -8088,6 +8088,7 @@ struct GMT_PALETTE *gmt_get_palette (struct GMT_CTRL *GMT, char *file, enum GMT_
 		double noise;
 		struct GMT_PALETTE_HIDDEN *PH = NULL;
 
+		GMT_Report (GMT->parent, GMT_MSG_DEBUG, "CPT argument %s understood to be a master table\n", file);
 		if (gmt_M_is_dnan (zmin) || gmt_M_is_dnan (zmax)) {	/* Safety valve 1 */
 			GMT_Report (GMT->parent, GMT_MSG_ERROR, "Passing zmax or zmin == NaN prevents automatic CPT generation!\n");
 			return (NULL);
@@ -8124,6 +8125,7 @@ struct GMT_PALETTE *gmt_get_palette (struct GMT_CTRL *GMT, char *file, enum GMT_
 		gmt_save_current_cpt (GMT, P, 0);	/* Save for use by session, if modern */
 	}
 	else if (file) {	/* Gave a CPT file */
+		GMT_Report (GMT->parent, GMT_MSG_DEBUG, "CPT argument %s understood to be a regular CPT table\n", file);
 		P = GMT_Read_Data (GMT->parent, GMT_IS_PALETTE, GMT_IS_FILE, GMT_IS_NONE, GMT_READ_NORMAL, NULL, &file[first], NULL);
 	}
 	else

src/gmt_support.c

@@ -0,0 +1,58 @@
+#include "gmt.h"
+#include <string.h>
+#include <stdlib.h>
+/*
+ * Testing the use of user data provided via a GMT_VECTOR to pstext,
+ * passing both numerical vectors and a string array.
+ */
+
+/* Dimensions of the test dataset */
+#define NCOLS 3
+#define NROWS 2
+
+int main () {
+	void *API = NULL;							/* The API control structure */
+	struct GMT_VECTOR *V = NULL;				/* Structure to hold input dataset as vectors */
+	char input[GMT_VF_LEN] = {""};     			/* String to hold virtual input filename */
+	char args[128] = {""};            			/* String to hold module command arguments */
+
+	uint64_t dim[4] = {NCOLS, NROWS, 1, 0};		/* ncols, nrows, nlayers, type */
+	/* two data points */
+	double x[2] = {5.0, 5.0};
+	double y[2] = {3.0, 8.0};
+	double angle[2] = {30.0, 60.0};
+	char *strings[NROWS];
+
+	int i;
+	for (i=0; i<NROWS; i++)
+		strings[i] = (char *) malloc(sizeof(char)*128);
+
+	strcpy(strings[0], "ML 18p,1,blue First label");
+	strcpy(strings[1], "MR 32p,2,red Second label");
+
+	/* Initialize the GMT session */
+	API = GMT_Create_Session ("test", 2U, GMT_SESSION_EXTERNAL, NULL);
+	/* Create a dataset */
+	if ((V = GMT_Create_Data (API, GMT_IS_DATASET|GMT_VIA_VECTOR, GMT_IS_POINT, GMT_CONTAINER_ONLY, dim, NULL, NULL, 0, 0, NULL)) == NULL) return (EXIT_FAILURE);
+	/* Hook the three vectors up to this container */
+	GMT_Put_Vector(API, V, 0, GMT_DOUBLE, x);
+	GMT_Put_Vector(API, V, 1, GMT_DOUBLE, y);
+	GMT_Put_Vector(API, V, 2, GMT_DOUBLE, angle);
+	/* Hook the user text array up to this container */
+	GMT_Put_Strings(API, GMT_IS_VECTOR|GMT_IS_DUPLICATE, V, strings);
+
+	for (i=0; i<NROWS; i++) {
+		free(strings[i]);
+	}
+
+	/* Associate our data table with a virtual file */
+	GMT_Open_VirtualFile (API, GMT_IS_DATASET|GMT_VIA_VECTOR, GMT_IS_POINT, GMT_IN, V, input);
+
+	/* Prepare the module arguments */
+	sprintf (args, "%s -JX10c -R0/10/0/10 -Baf -F+a+j+f", input);
+	/* Call the pstext module */
+	GMT_Call_Module (API, "pstext", GMT_MODULE_CMD, args);
+	GMT_Close_VirtualFile (API, input);
+	/* Destroy the GMT session */
+	if (GMT_Destroy_Session (API)) return EXIT_FAILURE;
+};

src/testapi_vector_strings2.c

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Test automatic CPT scaling
 gmt begin imagepluscpt ps
-	gmt grdimage @earth_relief_05m -RMG+r2 -Cgeo -I+
+	gmt grdimage @earth_relief_05m -RMG+r2 -Cgeo -I+d
 	gmt coast -Wthin -N1/thick,red -BWSne -B
 	gmt colorbar -DJTC -B
 gmt end show