/src/gdal/gcore/gdal_relationship.h

Source
/******************************************************************************
 *
 * Project:  GDAL
 * Purpose:  Declaration of GDALRelationship class
 * Author:   Nyall Dawson, <nyall dot dawson at gmail dot com>
 *
 ******************************************************************************
 * Copyright (c) 2022, Nyall Dawson <nyall dot dawson at gmail dot comg>
 *
 * SPDX-License-Identifier: MIT
 ****************************************************************************/

#ifndef GDALRELATIONSHIP_H_INCLUDED
#define GDALRELATIONSHIP_H_INCLUDED

#include "cpl_port.h"
#include "gdal.h"

#include <string>
#include <vector>

/************************************************************************/
/*                            Relationships                             */
/************************************************************************/

/**
 * Definition of a table relationship.
 *
 * GDALRelationship describes the relationship between two tables, including
 * properties such as the cardinality of the relationship and the participating
 * tables.
 *
 * Not all relationship properties are supported by all data formats.
 *
 * @since GDAL 3.6
 */
class CPL_DLL GDALRelationship
{
  protected:
    /*! @cond Doxygen_Suppress */
    std::string m_osName{};
    std::string m_osLeftTableName{};
    std::string m_osRightTableName{};
    GDALRelationshipCardinality m_eCardinality =
        GDALRelationshipCardinality::GRC_ONE_TO_MANY;
    std::string m_osMappingTableName{};
    std::vector<std::string> m_osListLeftTableFields{};
    std::vector<std::string> m_osListRightTableFields{};
    std::vector<std::string> m_osListLeftMappingTableFields{};
    std::vector<std::string> m_osListRightMappingTableFields{};
    GDALRelationshipType m_eType = GDALRelationshipType::GRT_ASSOCIATION;
    std::string m_osForwardPathLabel{};
    std::string m_osBackwardPathLabel{};
    std::string m_osRelatedTableType{};

    /*! @endcond */

  public:
    /**
     * Constructor for a relationship between two tables.
     * @param osName relationship name
     * @param osLeftTableName left table name
     * @param osRightTableName right table name
     * @param eCardinality cardinality of relationship
     */
    GDALRelationship(const std::string &osName,
                     const std::string &osLeftTableName,
                     const std::string &osRightTableName,
                     GDALRelationshipCardinality eCardinality =
                         GDALRelationshipCardinality::GRC_ONE_TO_MANY)
        : m_osName(osName), m_osLeftTableName(osLeftTableName),
          m_osRightTableName(osRightTableName), m_eCardinality(eCardinality)
    {
    }

    /** Get the name of the relationship */
    const std::string &GetName() const
    {
        return m_osName;
    }

    /** Get the cardinality of the relationship */
    GDALRelationshipCardinality GetCardinality() const
    {
        return m_eCardinality;
    }

    /** Get the name of the left (or base/origin) table in the relationship.
     *
     * @see GetRightTableName()
     * @see SetLeftTableName()
     */
    const std::string &GetLeftTableName() const
    {
        return m_osLeftTableName;
    }

    /** Sets the name of the left (or base/origin) table in the relationship.
     *
     * @see GetLeftTableName()
     * @since 3.13
     */
    void SetLeftTableName(const std::string &osName)
    {
        m_osLeftTableName = osName;
    }

    /** Get the name of the right (or related/destination) table in the
     * relationship.
     *
     * @see GetLeftTableName()
     * @see SetRightTableName()
     */
    const std::string &GetRightTableName() const
    {
        return m_osRightTableName;
    }

    /** Sets the name of the right (or related/destination) table in the
     * relationship.
     *
     * @see GetRightTableName()
     * @since 3.13
     */
    void SetRightTableName(const std::string &osName)
    {
        m_osRightTableName = osName;
    }

    /** Get the name of the mapping table for many-to-many relationships.
     *
     * @see SetMappingTableName()
     */
    const std::string &GetMappingTableName() const
    {
        return m_osMappingTableName;
    }

    /** Sets the name of the mapping table for many-to-many relationships.
     *
     * @see GetMappingTableName()
     */
    void SetMappingTableName(const std::string &osName)
    {
        m_osMappingTableName = osName;
    }

    /** Get the names of the participating fields from the left table in the
     * relationship.
     *
     * @see GetRightTableFields()
     * @see SetLeftTableFields()
     */
    const std::vector<std::string> &GetLeftTableFields() const
    {
        return m_osListLeftTableFields;
    }

    /** Get the names of the participating fields from the right table in the
     * relationship.
     *
     * @see GetLeftTableFields()
     * @see SetRightTableFields()
     */
    const std::vector<std::string> &GetRightTableFields() const
    {
        return m_osListRightTableFields;
    }

    /** Sets the names of the participating fields from the left table in the
     * relationship.
     *
     * @see GetLeftTableFields()
     * @see SetRightTableFields()
     */
    void SetLeftTableFields(const std::vector<std::string> &osListFields)
    {
        m_osListLeftTableFields = osListFields;
    }

    /** Sets the names of the participating fields from the right table in the
     * relationship.
     *
     * @see GetRightTableFields()
     * @see SetLeftTableFields()
     */
    void SetRightTableFields(const std::vector<std::string> &osListFields)
    {
        m_osListRightTableFields = osListFields;
    }

    /** Get the names of the mapping table fields which correspond to the
     * participating fields from the left table in the relationship.
     *
     * @see GetRightMappingTableFields()
     * @see SetLeftMappingTableFields()
     */
    const std::vector<std::string> &GetLeftMappingTableFields() const
    {
        return m_osListLeftMappingTableFields;
    }

    /** Get the names of the mapping table fields which correspond to the
     * participating fields from the right table in the relationship.
     *
     * @see GetLeftMappingTableFields()
     * @see SetRightMappingTableFields()
     */
    const std::vector<std::string> &GetRightMappingTableFields() const
    {
        return m_osListRightMappingTableFields;
    }

    /** Sets the names of the mapping table fields which correspond to the
     * participating fields from the left table in the relationship.
     *
     * @see GetLeftMappingTableFields()
     * @see SetRightMappingTableFields()
     */
    void SetLeftMappingTableFields(const std::vector<std::string> &osListFields)
    {
        m_osListLeftMappingTableFields = osListFields;
    }

    /** Sets the names of the mapping table fields which correspond to the
     * participating fields from the right table in the relationship.
     *
     * @see GetRightMappingTableFields()
     * @see SetLeftMappingTableFields()
     */
    void
    SetRightMappingTableFields(const std::vector<std::string> &osListFields)
    {
        m_osListRightMappingTableFields = osListFields;
    }

    /** Get the type of the relationship.
     *
     * @see SetType()
     */
    GDALRelationshipType GetType() const
    {
        return m_eType;
    }

    /** Sets the type of the relationship.
     *
     * @see GetType()
     */
    void SetType(GDALRelationshipType eType)
    {
        m_eType = eType;
    }

    /** Get the label of the forward path for the relationship.
     *
     * The forward and backward path labels are free-form, user-friendly strings
     * which can be used to generate descriptions of the relationship between
     * features from the right and left tables.
     *
     * E.g. when the left table contains buildings and the right table contains
     * furniture, the forward path label could be "contains" and the backward
     * path label could be "is located within". A client could then generate a
     * user friendly description string such as "fire hose 1234 is located
     * within building 15a".
     *
     * @see SetForwardPathLabel()
     * @see GetBackwardPathLabel()
     */
    const std::string &GetForwardPathLabel() const
    {
        return m_osForwardPathLabel;
    }

    /** Sets the label of the forward path for the relationship.
     *
     * The forward and backward path labels are free-form, user-friendly strings
     * which can be used to generate descriptions of the relationship between
     * features from the right and left tables.
     *
     * E.g. when the left table contains buildings and the right table contains
     * furniture, the forward path label could be "contains" and the backward
     * path label could be "is located within". A client could then generate a
     * user friendly description string such as "fire hose 1234 is located
     * within building 15a".
     *
     * @see GetForwardPathLabel()
     * @see SetBackwardPathLabel()
     */
    void SetForwardPathLabel(const std::string &osLabel)
    {
        m_osForwardPathLabel = osLabel;
    }

    /** Get the label of the backward path for the relationship.
     *
     * The forward and backward path labels are free-form, user-friendly strings
     * which can be used to generate descriptions of the relationship between
     * features from the right and left tables.
     *
     * E.g. when the left table contains buildings and the right table contains
     * furniture, the forward path label could be "contains" and the backward
     * path label could be "is located within". A client could then generate a
     * user friendly description string such as "fire hose 1234 is located
     * within building 15a".
     *
     * @see SetBackwardPathLabel()
     * @see GetForwardPathLabel()
     */
    const std::string &GetBackwardPathLabel() const
    {
        return m_osBackwardPathLabel;
    }

    /** Sets the label of the backward path for the relationship.
     *
     * The forward and backward path labels are free-form, user-friendly strings
     * which can be used to generate descriptions of the relationship between
     * features from the right and left tables.
     *
     * E.g. when the left table contains buildings and the right table contains
     * furniture, the forward path label could be "contains" and the backward
     * path label could be "is located within". A client could then generate a
     * user friendly description string such as "fire hose 1234 is located
     * within building 15a".
     *
     * @see GetBackwardPathLabel()
     * @see SetForwardPathLabel()
     */
    void SetBackwardPathLabel(const std::string &osLabel)
    {
        m_osBackwardPathLabel = osLabel;
    }

    /** Get the type string of the related table.
     *
     * This a free-form string representing the type of related features, where
     * the exact interpretation is format dependent. For instance, table types
     * from GeoPackage relationships will directly reflect the categories from
     * the GeoPackage related tables extension (i.e. "media", "simple
     * attributes", "features", "attributes" and "tiles").
     *
     * @see SetRelatedTableType()
     */
    const std::string &GetRelatedTableType() const
    {
        return m_osRelatedTableType;
    }

    /** Sets the type string of the related table.
     *
     * This a free-form string representing the type of related features, where
     * the exact interpretation is format dependent. For instance, table types
     * from GeoPackage relationships will directly reflect the categories from
     * the GeoPackage related tables extension (i.e. "media", "simple
     * attributes", "features", "attributes" and "tiles").
     *
     * @see GetRelatedTableType()
     */
    void SetRelatedTableType(const std::string &osType)
    {
        m_osRelatedTableType = osType;
    }

    /** Convert a GDALRelationship* to a GDALRelationshipH.
     */
    static inline GDALRelationshipH ToHandle(GDALRelationship *poRelationship)
    {
        return static_cast<GDALRelationshipH>(poRelationship);
    }

    /** Convert a GDALRelationshipH to a GDALRelationship*.
     */
    static inline GDALRelationship *FromHandle(GDALRelationshipH hRelationship)
    {
        return static_cast<GDALRelationship *>(hRelationship);
    }
};

#endif

Coverage Report

Created: 2026-04-01 06:20

Line	Count	Source
1		/******************************************************************************
2		*
3		* Project: GDAL
4		* Purpose: Declaration of GDALRelationship class
5		* Author: Nyall Dawson, <nyall dot dawson at gmail dot com>
6		*
7		******************************************************************************
8		* Copyright (c) 2022, Nyall Dawson <nyall dot dawson at gmail dot comg>
9		*
10		* SPDX-License-Identifier: MIT
11		****************************************************************************/
12
13		#ifndef GDALRELATIONSHIP_H_INCLUDED
14		#define GDALRELATIONSHIP_H_INCLUDED
15
16		#include "cpl_port.h"
17		#include "gdal.h"
18
19		#include <string>
20		#include <vector>
21
22		/************************************************************************/
23		/* Relationships */
24		/************************************************************************/
25
26		/**
27		* Definition of a table relationship.
28		*
29		* GDALRelationship describes the relationship between two tables, including
30		* properties such as the cardinality of the relationship and the participating
31		* tables.
32		*
33		* Not all relationship properties are supported by all data formats.
34		*
35		* @since GDAL 3.6
36		*/
37		class CPL_DLL GDALRelationship
38		{
39		protected:
40		/! @cond Doxygen_Suppress /
41		std::string m_osName{};
42		std::string m_osLeftTableName{};
43		std::string m_osRightTableName{};
44		GDALRelationshipCardinality m_eCardinality =
45		GDALRelationshipCardinality::GRC_ONE_TO_MANY;
46		std::string m_osMappingTableName{};
47		std::vector<std::string> m_osListLeftTableFields{};
48		std::vector<std::string> m_osListRightTableFields{};
49		std::vector<std::string> m_osListLeftMappingTableFields{};
50		std::vector<std::string> m_osListRightMappingTableFields{};
51		GDALRelationshipType m_eType = GDALRelationshipType::GRT_ASSOCIATION;
52		std::string m_osForwardPathLabel{};
53		std::string m_osBackwardPathLabel{};
54		std::string m_osRelatedTableType{};
55
56		/! @endcond /
57
58		public:
59		/**
60		* Constructor for a relationship between two tables.
61		* @param osName relationship name
62		* @param osLeftTableName left table name
63		* @param osRightTableName right table name
64		* @param eCardinality cardinality of relationship
65		*/
66		GDALRelationship(const std::string &osName,
67		const std::string &osLeftTableName,
68		const std::string &osRightTableName,
69		GDALRelationshipCardinality eCardinality =
70		GDALRelationshipCardinality::GRC_ONE_TO_MANY)
71		: m_osName(osName), m_osLeftTableName(osLeftTableName),
72		m_osRightTableName(osRightTableName), m_eCardinality(eCardinality)
73	0	{
74	0	}
75
76		/** Get the name of the relationship */
77		const std::string &GetName() const
78	0	{
79	0	return m_osName;
80	0	}
81
82		/** Get the cardinality of the relationship */
83		GDALRelationshipCardinality GetCardinality() const
84	0	{
85	0	return m_eCardinality;
86	0	}
87
88		/** Get the name of the left (or base/origin) table in the relationship.
89		*
90		* @see GetRightTableName()
91		* @see SetLeftTableName()
92		*/
93		const std::string &GetLeftTableName() const
94	0	{
95	0	return m_osLeftTableName;
96	0	}
97
98		/** Sets the name of the left (or base/origin) table in the relationship.
99		*
100		* @see GetLeftTableName()
101		* @since 3.13
102		*/
103		void SetLeftTableName(const std::string &osName)
104	0	{
105	0	m_osLeftTableName = osName;
106	0	}
107
108		/** Get the name of the right (or related/destination) table in the
109		* relationship.
110		*
111		* @see GetLeftTableName()
112		* @see SetRightTableName()
113		*/
114		const std::string &GetRightTableName() const
115	0	{
116	0	return m_osRightTableName;
117	0	}
118
119		/** Sets the name of the right (or related/destination) table in the
120		* relationship.
121		*
122		* @see GetRightTableName()
123		* @since 3.13
124		*/
125		void SetRightTableName(const std::string &osName)
126	0	{
127	0	m_osRightTableName = osName;
128	0	}
129
130		/** Get the name of the mapping table for many-to-many relationships.
131		*
132		* @see SetMappingTableName()
133		*/
134		const std::string &GetMappingTableName() const
135	0	{
136	0	return m_osMappingTableName;
137	0	}
138
139		/** Sets the name of the mapping table for many-to-many relationships.
140		*
141		* @see GetMappingTableName()
142		*/
143		void SetMappingTableName(const std::string &osName)
144	0	{
145	0	m_osMappingTableName = osName;
146	0	}
147
148		/** Get the names of the participating fields from the left table in the
149		* relationship.
150		*
151		* @see GetRightTableFields()
152		* @see SetLeftTableFields()
153		*/
154		const std::vector<std::string> &GetLeftTableFields() const
155	0	{
156	0	return m_osListLeftTableFields;
157	0	}
158
159		/** Get the names of the participating fields from the right table in the
160		* relationship.
161		*
162		* @see GetLeftTableFields()
163		* @see SetRightTableFields()
164		*/
165		const std::vector<std::string> &GetRightTableFields() const
166	0	{
167	0	return m_osListRightTableFields;
168	0	}
169
170		/** Sets the names of the participating fields from the left table in the
171		* relationship.
172		*
173		* @see GetLeftTableFields()
174		* @see SetRightTableFields()
175		*/
176		void SetLeftTableFields(const std::vector<std::string> &osListFields)
177	0	{
178	0	m_osListLeftTableFields = osListFields;
179	0	}
180
181		/** Sets the names of the participating fields from the right table in the
182		* relationship.
183		*
184		* @see GetRightTableFields()
185		* @see SetLeftTableFields()
186		*/
187		void SetRightTableFields(const std::vector<std::string> &osListFields)
188	0	{
189	0	m_osListRightTableFields = osListFields;
190	0	}
191
192		/** Get the names of the mapping table fields which correspond to the
193		* participating fields from the left table in the relationship.
194		*
195		* @see GetRightMappingTableFields()
196		* @see SetLeftMappingTableFields()
197		*/
198		const std::vector<std::string> &GetLeftMappingTableFields() const
199	0	{
200	0	return m_osListLeftMappingTableFields;
201	0	}
202
203		/** Get the names of the mapping table fields which correspond to the
204		* participating fields from the right table in the relationship.
205		*
206		* @see GetLeftMappingTableFields()
207		* @see SetRightMappingTableFields()
208		*/
209		const std::vector<std::string> &GetRightMappingTableFields() const
210	0	{
211	0	return m_osListRightMappingTableFields;
212	0	}
213
214		/** Sets the names of the mapping table fields which correspond to the
215		* participating fields from the left table in the relationship.
216		*
217		* @see GetLeftMappingTableFields()
218		* @see SetRightMappingTableFields()
219		*/
220		void SetLeftMappingTableFields(const std::vector<std::string> &osListFields)
221	0	{
222	0	m_osListLeftMappingTableFields = osListFields;
223	0	}
224
225		/** Sets the names of the mapping table fields which correspond to the
226		* participating fields from the right table in the relationship.
227		*
228		* @see GetRightMappingTableFields()
229		* @see SetLeftMappingTableFields()
230		*/
231		void
232		SetRightMappingTableFields(const std::vector<std::string> &osListFields)
233	0	{
234	0	m_osListRightMappingTableFields = osListFields;
235	0	}
236
237		/** Get the type of the relationship.
238		*
239		* @see SetType()
240		*/
241		GDALRelationshipType GetType() const
242	0	{
243	0	return m_eType;
244	0	}
245
246		/** Sets the type of the relationship.
247		*
248		* @see GetType()
249		*/
250		void SetType(GDALRelationshipType eType)
251	0	{
252	0	m_eType = eType;
253	0	}
254
255		/** Get the label of the forward path for the relationship.
256		*
257		* The forward and backward path labels are free-form, user-friendly strings
258		* which can be used to generate descriptions of the relationship between
259		* features from the right and left tables.
260		*
261		* E.g. when the left table contains buildings and the right table contains
262		* furniture, the forward path label could be "contains" and the backward
263		* path label could be "is located within". A client could then generate a
264		* user friendly description string such as "fire hose 1234 is located
265		* within building 15a".
266		*
267		* @see SetForwardPathLabel()
268		* @see GetBackwardPathLabel()
269		*/
270		const std::string &GetForwardPathLabel() const
271	0	{
272	0	return m_osForwardPathLabel;
273	0	}
274
275		/** Sets the label of the forward path for the relationship.
276		*
277		* The forward and backward path labels are free-form, user-friendly strings
278		* which can be used to generate descriptions of the relationship between
279		* features from the right and left tables.
280		*
281		* E.g. when the left table contains buildings and the right table contains
282		* furniture, the forward path label could be "contains" and the backward
283		* path label could be "is located within". A client could then generate a
284		* user friendly description string such as "fire hose 1234 is located
285		* within building 15a".
286		*
287		* @see GetForwardPathLabel()
288		* @see SetBackwardPathLabel()
289		*/
290		void SetForwardPathLabel(const std::string &osLabel)
291	0	{
292	0	m_osForwardPathLabel = osLabel;
293	0	}
294
295		/** Get the label of the backward path for the relationship.
296		*
297		* The forward and backward path labels are free-form, user-friendly strings
298		* which can be used to generate descriptions of the relationship between
299		* features from the right and left tables.
300		*
301		* E.g. when the left table contains buildings and the right table contains
302		* furniture, the forward path label could be "contains" and the backward
303		* path label could be "is located within". A client could then generate a
304		* user friendly description string such as "fire hose 1234 is located
305		* within building 15a".
306		*
307		* @see SetBackwardPathLabel()
308		* @see GetForwardPathLabel()
309		*/
310		const std::string &GetBackwardPathLabel() const
311	0	{
312	0	return m_osBackwardPathLabel;
313	0	}
314
315		/** Sets the label of the backward path for the relationship.
316		*
317		* The forward and backward path labels are free-form, user-friendly strings
318		* which can be used to generate descriptions of the relationship between
319		* features from the right and left tables.
320		*
321		* E.g. when the left table contains buildings and the right table contains
322		* furniture, the forward path label could be "contains" and the backward
323		* path label could be "is located within". A client could then generate a
324		* user friendly description string such as "fire hose 1234 is located
325		* within building 15a".
326		*
327		* @see GetBackwardPathLabel()
328		* @see SetForwardPathLabel()
329		*/
330		void SetBackwardPathLabel(const std::string &osLabel)
331	0	{
332	0	m_osBackwardPathLabel = osLabel;
333	0	}
334
335		/** Get the type string of the related table.
336		*
337		* This a free-form string representing the type of related features, where
338		* the exact interpretation is format dependent. For instance, table types
339		* from GeoPackage relationships will directly reflect the categories from
340		* the GeoPackage related tables extension (i.e. "media", "simple
341		* attributes", "features", "attributes" and "tiles").
342		*
343		* @see SetRelatedTableType()
344		*/
345		const std::string &GetRelatedTableType() const
346	0	{
347	0	return m_osRelatedTableType;
348	0	}
349
350		/** Sets the type string of the related table.
351		*
352		* This a free-form string representing the type of related features, where
353		* the exact interpretation is format dependent. For instance, table types
354		* from GeoPackage relationships will directly reflect the categories from
355		* the GeoPackage related tables extension (i.e. "media", "simple
356		* attributes", "features", "attributes" and "tiles").
357		*
358		* @see GetRelatedTableType()
359		*/
360		void SetRelatedTableType(const std::string &osType)
361	0	{
362	0	m_osRelatedTableType = osType;
363	0	}
364
365		/** Convert a GDALRelationship* to a GDALRelationshipH.
366		*/
367		static inline GDALRelationshipH ToHandle(GDALRelationship *poRelationship)
368	0	{
369	0	return static_cast<GDALRelationshipH>(poRelationship);
370	0	}
371
372		/** Convert a GDALRelationshipH to a GDALRelationship*.
373		*/
374		static inline GDALRelationship *FromHandle(GDALRelationshipH hRelationship)
375	0	{
376	0	return static_cast<GDALRelationship *>(hRelationship);
377	0	}
378		};
379
380		#endif