NAME

tags.c - functions for manipulating an images tags list

SYNOPSIS

  i_img_tags tags;
  i_tags_new(&tags);
  i_tags_destroy(&tags);
  i_tags_addn(&tags, "name", code, idata);
  i_tags_add(&tags, "name", code, data, data_size, idata);
  if (i_tags_find(&tags, name, start, &entry)) { found }
  if (i_tags_findn(&tags, code, start, &entry)) { found }
  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);

DESCRIPTION

Provides functions which give write access to the tags list of an image.

For read access directly access the fields (do not write any fields directly).

A tag is represented by an i_img_tag structure:

  typedef enum {
    itt_double,
    iit_text
  } i_tag_type;

  typedef struct {
    char *name; // name of a given tag, might be NULL 
    int code; // number of a given tag, -1 if it has no meaning 
    char *data; // value of a given tag if it's not an int, may be NULL 
    int size; // size of the data 
    int idata; // value of a given tag if data is NULL 
  } i_img_tag;

i_tags_new(i_img_tags *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()

i_tags_addn(i_img_tags *tags, char *name, int code, int idata)

Adds a tag that has an integer value. A simple wrapper around i_tags_add().

Use i_tags_setn() instead, this function may be removed in the future.

Returns non-zero on success.

i_tags_add(i_img_tags *tags, char *name, int code, char *data, int size, i_tag_type type, int idata)

Adds a tag to the tags list.

Use i_tags_set() instead, this function may be removed in the future.

Returns non-zero on success.

i_tags_destroy(tags)

Destroys the given tags structure. Called by i_img_destroy().

i_tags_find(tags, name, start, &entry)

Searches for a tag of the given name starting from index start.

On success returns true and sets *entry.

On failure returns false.

i_tags_findn(tags, code, start, &entry)

Searches for a tag of the given code starting from index start.

On success returns true and sets *entry.

On failure returns false.

i_tags_delete(tags, index)

Delete a tag by index.

Returns true on success.

i_tags_delbyname(tags, name)

Delete any tags with the given name.

Returns the number of tags deleted.

i_tags_delbycode(tags, code)

Delete any tags with the given code.

Returns the number of tags deleted.

i_tags_get_float(tags, name, code, value)

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 *value and returns true.

On failure returns false.

i_tags_set_float(tags, name, code, value)

Equivalent to i_tags_set_float2(tags, name, code, value, 30).

i_tags_set_float2(tags, name, code, value, places)

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 places.

i_tags_get_int(tags, name, code, &value)

Retrieve a tag specified by name or code as an integer.

On success sets the int *value to the integer and returns true.

On failure returns false.

i_tags_get_color(tags, name, code, &value)

Retrieve a tag specified by name or code as color.

On success sets the i_color *value to the color and returns true.

On failure returns false.

i_tags_set_color(tags, name, code, &value)

Stores the given color as a tag with the given name and code.

i_tags_get_string(tags, name, code, value, value_size)

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 NUL terminated.

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 data

If size is -1 then the strlen(data) bytes are stored.

Even on failure, if an existing tag name exists, it will be removed.

i_tags_setn(tags, name, 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 idata

Even on failure, if an existing tag name exists, it will be removed.

AUTHOR

Tony Cook <tony@develop-help.com>

SEE ALSO

Imager(3)