add new comparison method rgb_difference that resembles arithmetical difference per...
[imager.git] / tags.c
diff --git a/tags.c b/tags.c
index de2815a..1d759e7 100644 (file)
--- a/tags.c
+++ b/tags.c
@@ -48,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>
@@ -60,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
@@ -78,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.
 
@@ -94,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.
 
@@ -149,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;
@@ -162,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) {
@@ -175,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) {
@@ -188,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);*/
@@ -206,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;
@@ -224,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;
@@ -238,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;
@@ -260,6 +355,16 @@ 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);
@@ -268,6 +373,8 @@ int i_tags_set_float(i_img_tags *tags, char const *name, int code,
 /*
 =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.
 
@@ -295,6 +402,20 @@ int i_tags_set_float2(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;
@@ -323,7 +444,7 @@ static int parse_long(char *data, char **end, long *out) {
 
   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;
@@ -380,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;
@@ -406,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];
@@ -420,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;
@@ -442,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);