add new comparison method rgb_difference that resembles arithmetical difference per...
[imager.git] / tags.c
diff --git a/tags.c b/tags.c
index f844080..1d759e7 100644 (file)
--- a/tags.c
+++ b/tags.c
@@ -15,6 +15,10 @@ tags.c - functions for manipulating an images tags list
   i_tags_delete(&tags, index);
   count = i_tags_delbyname(tags, name);
   count = i_tags_delbycode(tags, code);
+  if (i_tags_get_float(&tags, name, code, &float_value)) { found }
+  i_tags_set_float(&tags, name, code, value);
+  i_tags_set_float2(&tags, name, code, value, sig_digits);
+  i_tags_get_int(&tags, name, code, &int_value);
 
 =head1 DESCRIPTION
 
@@ -44,7 +48,7 @@ A tag is represented by an i_img_tag structure:
 =cut
 */
 
-#include "image.h"
+#include "imager.h"
 #include <string.h>
 #include <stdlib.h>
 #include <errno.h>
@@ -56,9 +60,14 @@ void i_tags_print(i_img_tags *tags);
 /*
 =item i_tags_new(i_img_tags *tags)
 
+=category Tags
+
 Initialize a tags structure.  Should not be used if the tags structure
 has been previously used.
 
+This should be called tags member of an i_img object on creation (in
+i_img_*_new() functions).
+
 To destroy the contents use i_tags_destroy()
 
 =cut
@@ -74,7 +83,7 @@ void i_tags_new(i_img_tags *tags) {
 
 Adds a tag that has an integer value.  A simple wrapper around i_tags_add().
 
-Duplicate tags can be added.
+Use i_tags_setn() instead, this function may be removed in the future.
 
 Returns non-zero on success.
 
@@ -90,7 +99,7 @@ int i_tags_addn(i_img_tags *tags, char const *name, int code, int idata) {
 
 Adds a tag to the tags list.
 
-Duplicate tags can be added.
+Use i_tags_set() instead, this function may be removed in the future.
 
 Returns non-zero on success.
 
@@ -125,6 +134,8 @@ int i_tags_add(i_img_tags *tags, char const *name, int code, char const *data,
     strcpy(work.name, name);
   }
   if (data) {
+    if (size == -1)
+      size = strlen(data);
     work.data = mymalloc(size+1);
     if (!work.data) {
       if (work.name) myfree(work.name);
@@ -143,6 +154,16 @@ int i_tags_add(i_img_tags *tags, char const *name, int code, char const *data,
   return 1;
 }
 
+/*
+=item i_tags_destroy(tags)
+
+=category Tags
+
+Destroys the given tags structure.  Called by i_img_destroy().
+
+=cut
+*/
+
 void i_tags_destroy(i_img_tags *tags) {
   if (tags->tags) {
     int i;
@@ -156,6 +177,20 @@ void i_tags_destroy(i_img_tags *tags) {
   }
 }
 
+/*
+=item i_tags_find(tags, name, start, &entry)
+
+=category Tags
+
+Searches for a tag of the given I<name> starting from index I<start>.
+
+On success returns true and sets *I<entry>.
+
+On failure returns false.
+
+=cut
+*/
+
 int i_tags_find(i_img_tags *tags, char const *name, int start, int *entry) {
   if (tags->tags) {
     while (start < tags->count) {
@@ -169,6 +204,20 @@ int i_tags_find(i_img_tags *tags, char const *name, int start, int *entry) {
   return 0;
 }
 
+/*
+=item i_tags_findn(tags, code, start, &entry)
+
+=category Tags
+
+Searches for a tag of the given I<code> starting from index I<start>.
+
+On success returns true and sets *I<entry>.
+
+On failure returns false.
+
+=cut
+*/
+
 int i_tags_findn(i_img_tags *tags, int code, int start, int *entry) {
   if (tags->tags) {
     while (start < tags->count) {
@@ -182,6 +231,17 @@ int i_tags_findn(i_img_tags *tags, int code, int start, int *entry) {
   return 0;
 }
 
+/*
+=item i_tags_delete(tags, index)
+
+=category Tags
+
+Delete a tag by index.
+
+Returns true on success.
+
+=cut
+*/
 int i_tags_delete(i_img_tags *tags, int entry) {
   /*printf("i_tags_delete(tags %p [count %d], entry %d)\n",
     tags, tags->count, entry);*/
@@ -200,6 +260,18 @@ int i_tags_delete(i_img_tags *tags, int entry) {
   return 0;
 }
 
+/*
+=item i_tags_delbyname(tags, name)
+
+=category Tags
+
+Delete any tags with the given name.
+
+Returns the number of tags deleted.
+
+=cut
+*/
+
 int i_tags_delbyname(i_img_tags *tags, char const *name) {
   int count = 0;
   int i;
@@ -218,6 +290,18 @@ int i_tags_delbyname(i_img_tags *tags, char const *name) {
   return count;
 }
 
+/*
+=item i_tags_delbycode(tags, code)
+
+=category Tags
+
+Delete any tags with the given code.
+
+Returns the number of tags deleted.
+
+=cut
+*/
+
 int i_tags_delbycode(i_img_tags *tags, int code) {
   int count = 0;
   int i;
@@ -232,6 +316,23 @@ int i_tags_delbycode(i_img_tags *tags, int code) {
   return count;
 }
 
+/*
+=item i_tags_get_float(tags, name, code, value)
+
+=category Tags
+
+Retrieves a tag as a floating point value.  
+
+If the tag has a string value then that is parsed as a floating point
+number, otherwise the integer value of the tag is used.
+
+On success sets *I<value> and returns true.
+
+On failure returns false.
+
+=cut
+*/
+
 int i_tags_get_float(i_img_tags *tags, char const *name, int code, 
                      double *value) {
   int index;
@@ -254,11 +355,45 @@ int i_tags_get_float(i_img_tags *tags, char const *name, int code,
   return 1;
 }
 
+/*
+=item i_tags_set_float(tags, name, code, value)
+
+=category Tags
+
+Equivalent to i_tags_set_float2(tags, name, code, value, 30).
+
+=cut
+*/
+
 int i_tags_set_float(i_img_tags *tags, char const *name, int code, 
                      double value) {
+  return i_tags_set_float2(tags, name, code, value, 30);
+}
+
+/*
+=item i_tags_set_float2(tags, name, code, value, places)
+
+=category Tags
+
+Sets the tag with the given name and code to the given floating point
+value.
+
+Since tags are strings or ints, we convert the value to a string before
+storage at the precision specified by C<places>.
+
+=cut
+*/
+
+int i_tags_set_float2(i_img_tags *tags, char const *name, int code, 
+                      double value, int places) {
   char temp[40];
 
-  sprintf(temp, "%.30g", value);
+  if (places < 0) 
+    places = 30;
+  else if (places > 30) 
+    places = 30;
+
+  sprintf(temp, "%.*g", places, value);
   if (name)
     i_tags_delbyname(tags, name);
   else
@@ -267,6 +402,20 @@ int i_tags_set_float(i_img_tags *tags, char const *name, int code,
   return i_tags_add(tags, name, code, temp, strlen(temp), 0);
 }
 
+/*
+=item i_tags_get_int(tags, name, code, &value)
+
+=category Tags
+
+Retrieve a tag specified by name or code as an integer.
+
+On success sets the int *I<value> to the integer and returns true.
+
+On failure returns false.
+
+=cut
+*/
+
 int i_tags_get_int(i_img_tags *tags, char const *name, int code, int *value) {
   int index;
   i_img_tag *entry;
@@ -289,45 +438,23 @@ int i_tags_get_int(i_img_tags *tags, char const *name, int code, int *value) {
 }
 
 static int parse_long(char *data, char **end, long *out) {
-#if 0
-  /* I wrote this without thinking about strtol */
-  long x = 0;
-  int neg = *data == '-';
-
-  if (neg)
-    ++data;
-  if (!isdigit(*data))
-    return 0;
-  while (isdigit(*data)) {
-    /* this check doesn't guarantee we don't overflow, but it helps */
-    if (x > LONG_MAX / 10)
-      return 0; 
-    x = x * 10 + *data - '0';
-    ++data;
-  }
-  if (neg)
-    x = -x;
-
-  *end = data;
-
-  return 1;
-#else
   long result;
   int savederr = errno;
   char *myend;
 
   errno = 0;
   result = strtol(data, &myend, 10);
-  if ((result == LONG_MIN || result == LONG_MAX) && errno == ERANGE
+  if (((result == LONG_MIN || result == LONG_MAX) && errno == ERANGE)
       || myend == data) {
+    errno = savederr;
     return 0;
   }
 
+  errno = savederr;
   *out = result;
   *end = myend;
 
   return 1;
-#endif
 }
 
 /* parse a comma-separated list of integers
@@ -374,6 +501,20 @@ static int parse_color(char *data, char **end, i_color *value) {
   return 1;
 }
 
+/*
+=item i_tags_get_color(tags, name, code, &value)
+
+=category Tags
+
+Retrieve a tag specified by name or code as color.
+
+On success sets the i_color *I<value> to the color and returns true.
+
+On failure returns false.
+
+=cut
+*/
+
 int i_tags_get_color(i_img_tags *tags, char const *name, int code, 
                      i_color *value) {
   int index;
@@ -400,6 +541,16 @@ int i_tags_get_color(i_img_tags *tags, char const *name, int code,
   return 1;
 }
 
+/*
+=item i_tags_set_color(tags, name, code, &value)
+
+=category Tags
+
+Stores the given color as a tag with the given name and code.
+
+=cut
+*/
+
 int i_tags_set_color(i_img_tags *tags, char const *name, int code, 
                      i_color const *value) {
   char temp[80];
@@ -414,6 +565,26 @@ int i_tags_set_color(i_img_tags *tags, char const *name, int code,
   return i_tags_add(tags, name, code, temp, strlen(temp), 0);
 }
 
+/*
+=item i_tags_get_string(tags, name, code, value, value_size)
+
+=category Tags
+
+Retrieves a tag by name or code as a string.
+
+On success copies the string to value for a max of value_size and
+returns true.
+
+On failure returns false.
+
+value_size must be at least large enough for a string representation
+of an integer.
+
+The copied value is always C<NUL> terminated.
+
+=cut
+*/
+
 int i_tags_get_string(i_img_tags *tags, char const *name, int code, 
                       char *value, size_t value_size) {
   int index;
@@ -436,12 +607,55 @@ int i_tags_get_string(i_img_tags *tags, char const *name, int code,
     value[cpsize] = '\0';
   }
   else {
-    sprintf(value, "%d", entry->data);
+    sprintf(value, "%d", entry->idata);
   }
 
   return 1;
 }
 
+/*
+=item i_tags_set(tags, name, data, size)
+=synopsis i_tags_set(&img->tags, "i_comment", -1);
+=category Tags
+
+Sets the given tag to the string I<data>
+
+If size is -1 then the strlen(I<data>) bytes are stored.
+
+Even on failure, if an existing tag I<name> exists, it will be
+removed.
+
+=cut
+*/
+
+int
+i_tags_set(i_img_tags *tags, char const *name, char const *data, int size) {
+  i_tags_delbyname(tags, name);
+
+  return i_tags_add(tags, name, 0, data, size, 0);
+}
+
+/*
+=item i_tags_setn(C<tags>, C<name>, C<idata>)
+=synopsis i_tags_setn(&img->tags, "i_xres", 204);
+=synopsis i_tags_setn(&img->tags, "i_yres", 196);
+=category Tags
+
+Sets the given tag to the integer C<idata>
+
+Even on failure, if an existing tag C<name> exists, it will be
+removed.
+
+=cut
+*/
+
+int
+i_tags_setn(i_img_tags *tags, char const *name, int idata) {
+  i_tags_delbyname(tags, name);
+
+  return i_tags_addn(tags, name, 0, idata);
+}
+
 void i_tags_print(i_img_tags *tags) {
   int i;
   printf("Alloc %d\n", tags->alloc);