data.tags and main.tagged_images. More...

#include "metadata/tags.h"
#include <glib.h>
#include <stdint.h>

Include dependency graph for tag_repository.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	dt_tag_count_t

Typedefs
typedef enum dt_tag_kind_t	dt_tag_kind_t

typedef struct dt_tag_count_t	dt_tag_count_t

Enumerations
enum	dt_tag_kind_t { DT_TAG_KIND_ANY = 0 , DT_TAG_KIND_INTERNAL , DT_TAG_KIND_USER }

Functions
G_BEGIN_DECLS GList *	dt_tag_repository_get_attached_names (const int32_t imgid)
	Names of the tags attached to an image.

guint	dt_tag_repository_find_by_name (const char *name)
	The id of the tag named `name`, or 0 when there is none.

guint	dt_tag_repository_find_by_name_nocase (const char *name)
	The id of the tag whose name matches `name` case-INSENSITIVELY, or 0.

guint	dt_tag_repository_insert (const char *name)
	Insert a tag named `name` and return its new id, or 0 on failure.

gchar *	dt_tag_repository_get_name (const guint tagid)
	The name of `tagid`, newly allocated, or NULL.

void	dt_tag_repository_rename (const guint tagid, const char *new_name)
	Rename `tagid`. The caller checks first that the new name is free.

int	dt_tag_repository_count_attachments (const guint tagid)
	How many attachment ROWS `tagid` has, or -1 if the count could not be read. See dt_tag_repository_count_distinct_images() for the other question.

void	dt_tag_repository_delete (const guint tagid)
	Delete `tagid`, its attachments, and its `memory.darktable_tags` entry.

void	dt_tag_repository_delete_batch (const char *id_list)
	Delete every tag in `id_list` and its attachments.

void	dt_tag_repository_mark_internal (const guint tagid)
	Record `tagid` as an internal tag.

void	dt_tag_repository_rebuild_internal (void)
	Rebuild the whole internal-tag cache from `data.tags`.

gint	dt_tag_repository_get_flags (const guint tagid)
	The flags word of `tagid`, or 0.

void	dt_tag_repository_set_flags (const guint tagid, const gint flags)
	Replace the flags word of `tagid`.

void	dt_tag_repository_update_flags (const guint tagid, const gint set, const gint keep_mask)
	Set the bits in `set` and clear those absent from `keep_mask:` `flags = (IFNULL(flags,0) & keep_mask) \| set`.

gchar *	dt_tag_repository_get_synonyms (const guint tagid)
	The synonyms of `tagid`, newly allocated, or NULL.

void	dt_tag_repository_set_synonyms (const guint tagid, const char *synonyms)
	Replace the synonyms of `tagid`.

gboolean	dt_tag_repository_attach (const guint tagid, const int32_t imgid)
	Attach `tagid` to `imgid`, at the end of the tag order.

gboolean	dt_tag_repository_is_attached (const guint tagid, const int32_t imgid)
	TRUE when `tagid` is attached to `imgid`.

GList *	dt_tag_repository_get_images (const guint tagid)
	Images carrying `tagid`, `GINT_TO_POINTER`. Free with g_list_free().

GList *	dt_tag_repository_get_images_in_list (const guint tagid, const char *imgid_list)
	Images carrying `tagid`, restricted to `imgid_list` – a comma-separated list of decimal image ids composed by the caller.

uint32_t	dt_tag_repository_count_distinct_images (const guint tagid)
	Distinct images carrying `tagid`.

void	dt_tag_repository_detach_batch (const int32_t imgid, const char *tagid_list)
	Detach every tag in `tagid_list` from `imgid`.

void	dt_tag_repository_attach_batch (const char *values)
	Attach rows given as the VALUES clause of the insert – `"(imgid,tagid,pos),…"`. The position expression is the caller's, which is why this takes text.

GList *	dt_tag_repository_get_attached (const int32_t imgid, const gboolean ignore_internal)
	Tags attached to one image or to the current selection, ordered by name.

GList *	dt_tag_repository_get_attached_for_export (const int32_t imgid)
	Tags attached to `imgid` for export, plus every ancestor on their paths.

GList *	dt_tag_repository_get_ids_for_images (const char *imgid_list, const dt_tag_kind_t kind)
	Ids of the tags on a set of images, optionally restricted by kind.

GList *	dt_tag_repository_get_with_usage (const uint32_t nb_selected)
	Every user tag with how often it is used and how much of the selection carries it.

GList *	dt_tag_repository_get_collection_tags (void)
	User tags attached to at least one image of the current collection, by name.

GList *	dt_tag_repository_get_names_under (const int32_t imgid, const char *category)
	Names of the tags on `imgid` that start with `category`.

void	dt_tag_repository_count_similar (const char keyword, int tag_count, int *img_count)
	How many tags match `keyword`, and how many images carry any of them.

void	dt_tag_repository_get_similar (const char keyword, GList tags, GList *imgids)
	The tags matching `keyword` and the images carrying any of them.

GList *	dt_tag_repository_get_suggestions (const uint32_t nb_selected, const int confidence, const char *recent_tags, const int nb_recent)
	Tags worth suggesting for the current selection.

void	dt_tag_repository_get_agreement (GList imgids, gboolean same_tags, gboolean *same_categories)
	Do all of `imgids` carry exactly the same tags? The same categories?

void	dt_tag_repository_cleanup (void)
	Finalise whatever this repository still caches – today, nothing. See dt_colorlabel_repository_cleanup() for why the hook stays.

void	dt_tag_count_free (gpointer data)
	Release one dt_tag_count_t, name included. Suits `g_list_free_full()`.

GList *	dt_tag_repository_get_by_path_with_counts (const char path, const char path_prefix)
	Tags at `path` or below it, each with the number of distinct images carrying it.

Detailed Description

data.tags and main.tagged_images.

A tag is a row in data.tags (id, name, flags, synonyms) and an attachment is a row in main.tagged_images (imgid, tagid, position). memory.darktable_tags caches which tags are internal (darktable|…), so the collection query can exclude them cheaply.

Warning: Partial. common/tags.c still holds the tag listing machinery – the suggestion, usage-count and similar-tag queries, several of which are multi-level SELECTs assembled from conditional fragments. Those belong here too. Extend this file; do not start a second tag repository.

Definition in file tag_repository.h.

Typedef Documentation

◆ dt_tag_count_t

typedef struct dt_tag_count_t dt_tag_count_t

One row of dt_tag_repository_get_by_path_with_counts().

◆ dt_tag_kind_t

typedef enum dt_tag_kind_t dt_tag_kind_t

Which tags a listing should include. Its own enum rather than common/tags.c's dt_tag_type_t, which is private to that file – a repository borrowing a caller's private type would make the caller impossible to move.

Enumeration Type Documentation

◆ dt_tag_kind_t

enum dt_tag_kind_t

Which tags a listing should include. Its own enum rather than common/tags.c's dt_tag_type_t, which is private to that file – a repository borrowing a caller's private type would make the caller impossible to move.

Enumerator
DT_TAG_KIND_ANY	every tag
DT_TAG_KIND_INTERNAL	only `darktable\|…`, i.e. those in `memory.darktable_tags`
DT_TAG_KIND_USER	everything that is not internal

Definition at line 186 of file tag_repository.h.

Function Documentation

◆ dt_tag_count_free()

void dt_tag_count_free ( gpointer data )

Release one dt_tag_count_t, name included. Suits g_list_free_full().

Definition at line 61 of file tag_repository.c.

References dt_free, IS_NULL_PTR, and t.

Referenced by dt_map_location_get_locations_by_path().

◆ dt_tag_repository_attach()

gboolean dt_tag_repository_attach	(	const guint	tagid,
		const int32_t	imgid
	)

Attach tagid to imgid, at the end of the tag order.

Definition at line 896 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_BIND_INT, DT_DEBUG_SQLITE3_PREPARE_V2, and L.

Referenced by _exif_import_tags(), and test_tag_agreement().

◆ dt_tag_repository_attach_batch()

void dt_tag_repository_attach_batch ( const char * values )

Attach rows given as the VALUES clause of the insert – "(imgid,tagid,pos),…". The position expression is the caller's, which is why this takes text.

Definition at line 416 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_PREPARE_V2, dt_free, IS_NULL_PTR, and L.

Referenced by _bulk_add_tags().

◆ dt_tag_repository_cleanup()

void dt_tag_repository_cleanup ( void )

Finalise whatever this repository still caches – today, nothing. See dt_colorlabel_repository_cleanup() for why the hook stays.

Definition at line 963 of file tag_repository.c.

Referenced by dt_tags_cleanup(), and testdb_teardown().

◆ dt_tag_repository_count_attachments()

int dt_tag_repository_count_attachments ( const guint tagid )

How many attachment ROWS tagid has, or -1 if the count could not be read. See dt_tag_repository_count_distinct_images() for the other question.

Definition at line 198 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_BIND_INT, DT_DEBUG_SQLITE3_PREPARE_V2, and L.

Referenced by dt_map_location_get_images_count(), and dt_tag_remove().

◆ dt_tag_repository_count_distinct_images()

uint32_t dt_tag_repository_count_distinct_images ( const guint tagid )

Distinct images carrying tagid.

Warning: Not the same question as dt_tag_repository_count_attachments(), which counts ROWS. They differ if an image ever gets the same tag twice, and the two callers ask for different reasons – one for "is this tag still in use", one to show a number to the user.

Definition at line 385 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_BIND_INT, DT_DEBUG_SQLITE3_PREPARE_V2, and L.

Referenced by dt_tag_images_count().

◆ dt_tag_repository_count_similar()

void dt_tag_repository_count_similar	(	const char *	keyword,
		int *	tag_count,
		int *	img_count
	)

How many tags match keyword, and how many images carry any of them.

Definition at line 726 of file tag_repository.c.

References _clear_similar_tags(), _fill_similar_tags(), _scalar(), IS_NULL_PTR, and L.

Referenced by dt_tag_count_tags_images().

◆ dt_tag_repository_delete()

void dt_tag_repository_delete ( const guint tagid )

Delete tagid, its attachments, and its memory.darktable_tags entry.

Definition at line 213 of file tag_repository.c.

References _run_for_id().

Referenced by dt_tag_remove().

◆ dt_tag_repository_delete_batch()

void dt_tag_repository_delete_batch ( const char * id_list )

Delete every tag in id_list and its attachments.

Parameters

id_list a comma-separated list of decimal tag ids, composed by the caller.

Definition at line 220 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_PREPARE_V2, dt_free, IS_NULL_PTR, and L.

Referenced by dt_tag_delete_tag_batch().

◆ dt_tag_repository_detach_batch()

void dt_tag_repository_detach_batch	(	const int32_t	imgid,
		const char *	tagid_list
	)

Detach every tag in tagid_list from imgid.

Parameters

tagid_list comma-separated decimal tag ids. Does nothing when NULL.

Definition at line 401 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_PREPARE_V2, dt_free, IS_NULL_PTR, and L.

Referenced by _bulk_remove_tags().

◆ dt_tag_repository_find_by_name()

guint dt_tag_repository_find_by_name ( const char * name )

The id of the tag named name, or 0 when there is none.

Definition at line 138 of file tag_repository.c.

References _first_id_for_text(), and name.

Referenced by _exif_import_tags(), dt_tag_exists(), dt_tag_new(), and dt_tag_repository_insert().

◆ dt_tag_repository_find_by_name_nocase()

guint dt_tag_repository_find_by_name_nocase ( const char * name )

The id of the tag whose name matches name case-INSENSITIVELY, or 0.

Definition at line 143 of file tag_repository.c.

References _first_id_for_text(), and name.

Referenced by dt_tag_get_tag_id_by_name().

◆ dt_tag_repository_get_agreement()

void dt_tag_repository_get_agreement	(	GList *	imgids,
		gboolean *	same_tags,
		gboolean *	same_categories
	)

Do all of imgids carry exactly the same tags? The same categories?

A tag is shared when every image in the set carries it, so the test is per tag: count the distinct images attached to it and compare against the size of the set. Any tag short of that means the images disagree. Tags flagged DT_TF_CATEGORY are answered separately because the panel shows them on their own row. Darktable's internal darktable|* namespace is excluded, as it always was.

Both out-parameters are set to TRUE for an empty or unreadable set – vacuously, nothing disagrees. Either may be NULL.

Definition at line 914 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_PREPARE_V2, dt_free, DT_TF_CATEGORY, FALSE, L, and TRUE.

Referenced by _concatenate_multiple_images(), and test_tag_agreement().

◆ dt_tag_repository_get_attached()

GList * dt_tag_repository_get_attached	(	const int32_t	imgid,
		const gboolean	ignore_internal
	)

Tags attached to one image or to the current selection, ordered by name.

Parameters

imgid	a positive image id, or <= 0 to read the selection (joining `main.selected_images` rather than binding an id).
ignore_internal	exclude tags in `memory.darktable_tags`.

Returns: GList of dt_tag_t *; count is the number of DISTINCT images each tag is on. Free with dt_tag_free_result().

Definition at line 490 of file tag_repository.c.

References _attached_query, _tag_from_row(), dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_BIND_INT, DT_DEBUG_SQLITE3_PREPARE_V2, IS_NULL_PTR, L, t, and TRUE.

Referenced by dt_tag_get_attached().

◆ dt_tag_repository_get_attached_for_export()

GList * dt_tag_repository_get_attached_for_export ( const int32_t imgid )

Tags attached to imgid for export, plus every ancestor on their paths.

The ancestors are what lets the caller check whether a node in the path is a category, so a hierarchical tag exports the right way. Internal tags are always excluded and count is not filled – the export does not use it.

Definition at line 512 of file tag_repository.c.

References _tag_from_row(), dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_BIND_INT, DT_DEBUG_SQLITE3_PREPARE_V2, FALSE, L, and t.

Referenced by _tag_get_attached_export().

◆ dt_tag_repository_get_attached_names()

G_BEGIN_DECLS GList * dt_tag_repository_get_attached_names ( const int32_t imgid )

Names of the tags attached to an image.

Parameters

imgid the image, or a negative value for every selected image – the convention dt_metadata_get() uses, which is this function's only caller. Across a selection the same name appears once per image carrying it, and that is deliberate: the caller counts occurrences.

Returns: a GList of newly allocated names. Free with g_list_free_full(l, g_free).

Definition at line 28 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_BIND_INT, DT_DEBUG_SQLITE3_PREPARE_V2, and L.

Referenced by dt_metadata_get().

◆ dt_tag_repository_get_by_path_with_counts()

GList * dt_tag_repository_get_by_path_with_counts	(	const char *	path,
		const char *	path_prefix
	)

Tags at path or below it, each with the number of distinct images carrying it.

Parameters

path	exact name to match.
path_prefix	names starting with this also match; normally `path` plus a `\|`.

Returns: a GList of newly allocated dt_tag_count_t. Free with g_list_free_full(l, dt_tag_count_free).

Definition at line 69 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_BIND_TEXT, DT_DEBUG_SQLITE3_PREPARE_V2, L, name, and t.

Referenced by dt_map_location_get_locations_by_path().

◆ dt_tag_repository_get_collection_tags()

GList * dt_tag_repository_get_collection_tags ( void )

User tags attached to at least one image of the current collection, by name.

Returns: GList of dt_tag_t * with tag and id set only – the caller shows names.

Definition at line 632 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_PREPARE_V2, L, and t.

Referenced by dt_tag_get_collection_tags().

◆ dt_tag_repository_get_flags()

gint dt_tag_repository_get_flags ( const guint tagid )

The flags word of tagid, or 0.

Definition at line 267 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_BIND_INT, DT_DEBUG_SQLITE3_PREPARE_V2, flags, and L.

Referenced by dt_tag_get_flags(), and dt_tag_get_tag_order_by_id().

◆ dt_tag_repository_get_ids_for_images()

GList * dt_tag_repository_get_ids_for_images	(	const char *	imgid_list,
		const dt_tag_kind_t	kind
	)

Ids of the tags on a set of images, optionally restricted by kind.

Parameters

imgid_list	a comma-separated list of decimal image ids, composed by the caller – one id for a single image, or the selection's, which `common/selection.c` already knows how to spell.
kind	all tags, only the internal `darktable\|…` ones, or only the others.

Returns: GList of tag ids as GINT_TO_POINTER. Free with g_list_free().

Definition at line 546 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_PREPARE_V2, DT_TAG_KIND_ANY, DT_TAG_KIND_INTERNAL, IS_NULL_PTR, kind, and L.

Referenced by _tag_get_tags().

◆ dt_tag_repository_get_images()

GList * dt_tag_repository_get_images ( const guint tagid )

Images carrying tagid, GINT_TO_POINTER. Free with g_list_free().

Definition at line 362 of file tag_repository.c.

References _collect_imgids(), dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_BIND_INT, DT_DEBUG_SQLITE3_PREPARE_V2, and L.

Referenced by dt_tag_get_images().

◆ dt_tag_repository_get_images_in_list()

GList * dt_tag_repository_get_images_in_list	(	const guint	tagid,
		const char *	imgid_list
	)

Images carrying tagid, restricted to imgid_list – a comma-separated list of decimal image ids composed by the caller.

Definition at line 371 of file tag_repository.c.

References _collect_imgids(), dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_PREPARE_V2, dt_free, IS_NULL_PTR, and L.

Referenced by dt_tag_get_images_from_list().

◆ dt_tag_repository_get_name()

gchar * dt_tag_repository_get_name ( const guint tagid )

The name of tagid, newly allocated, or NULL.

Definition at line 170 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_BIND_INT, DT_DEBUG_SQLITE3_PREPARE_V2, L, and name.

Referenced by dt_tag_get_name().

◆ dt_tag_repository_get_names_under()

GList * dt_tag_repository_get_names_under	(	const int32_t	imgid,
		const char *	category
	)

Names of the tags on imgid that start with category.

Returns: GList of newly allocated full tag names, in query order. The caller slices them into path components; that is string work, not storage.

Definition at line 663 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_BIND_INT, DT_DEBUG_SQLITE3_BIND_TEXT, DT_DEBUG_SQLITE3_PREPARE_V2, IS_NULL_PTR, and L.

Referenced by dt_tag_get_subtags().

◆ dt_tag_repository_get_similar()

void dt_tag_repository_get_similar	(	const char *	keyword,
		GList **	tags,
		GList **	imgids
	)

The tags matching keyword and the images carrying any of them.

Parameters

tags	receives `dt_tag_t *` with `id` and `tag` set; appended, not replaced.
imgids	receives image ids as `GINT_TO_POINTER`; appended, not replaced.

Definition at line 746 of file tag_repository.c.

References _clear_similar_tags(), _fill_similar_tags(), dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_PREPARE_V2, IS_NULL_PTR, L, and t.

Referenced by dt_tag_get_tags_images().

◆ dt_tag_repository_get_suggestions()

GList * dt_tag_repository_get_suggestions	(	const uint32_t	nb_selected,
		const int	confidence,
		const char *	recent_tags,
		const int	nb_recent
	)

Tags worth suggesting for the current selection.

Two sources unioned: tags that co-occur with the selection's tags often enough to clear confidence, and the user's recent-tag list. Tags already on every selected image are rejected from both – suggesting one would be a no-op.

Parameters

nb_selected	how many images are selected. Also used to fold `select`, for the same reason as dt_tag_repository_get_with_usage().
confidence	percentage, 0..100. At 100 the co-occurrence half is skipped entirely and only the recent list is returned – a different query, not a stricter filter.
recent_tags	the recent-tag names, already quoted and comma-separated by the caller, dropped into an `IN (…)`. It comes from the user's own configuration.
nb_recent	how many of them to keep.

Returns: GList of dt_tag_t *; leave is left to the caller.

Definition at line 789 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_EXEC, DT_DEBUG_SQLITE3_PREPARE_V2, dt_free, DT_TS_ALL_IMAGES, DT_TS_NO_IMAGE, DT_TS_SOME_IMAGES, L, and t.

Referenced by dt_tag_get_suggestions().

◆ dt_tag_repository_get_synonyms()

gchar * dt_tag_repository_get_synonyms ( const guint tagid )

The synonyms of tagid, newly allocated, or NULL.

Definition at line 306 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_BIND_INT, DT_DEBUG_SQLITE3_PREPARE_V2, and L.

Referenced by dt_tag_get_synonyms().

◆ dt_tag_repository_get_with_usage()

GList * dt_tag_repository_get_with_usage ( const uint32_t nb_selected )

Every user tag with how often it is used and how much of the selection carries it.

Parameters

nb_selected how many images are selected, which common/selection.c knows and the database does not.

Returns: GList of dt_tag_t * ordered by name, with count = total attachments and select already folded into the tri-state. leave is left to the caller.

Note: This one fills select itself, where dt_tag_repository_get_attached() leaves it. There, count IS the per-image number, so the caller can fold it afterwards; here count is the tag's global usage and the per-selection number appears only inside the query. Rather than hand back a second parallel list for it, or park it in a field whose units then lie, the fold happens where the number exists.

Definition at line 574 of file tag_repository.c.

References dt_database_get_sqlite3_global(), DT_DEBUG_SQLITE3_EXEC, DT_DEBUG_SQLITE3_PREPARE_V2, DT_TS_ALL_IMAGES, DT_TS_NO_IMAGE, DT_TS_SOME_IMAGES, L, and t.

Referenced by dt_tag_get_with_usage().