GnuCash  5.6-150-g038405b370+
Files | Data Structures | Macros | Functions

Globally Unique IDs provide a way to uniquely identify something. More...

Files

file  guid.h
 globally unique ID User API
 

Data Structures

struct  GncGUID
 The type used to store guids in C. More...
 

Macros

#define GUID_DATA_SIZE   16
 
#define GNC_TYPE_GUID   (gnc_guid_get_type())
 
#define GNC_VALUE_HOLDS_GUID(value)   G_VALUE_HOLDS(value, GNC_TYPE_GUID)
 
#define GUID_ENCODING_LENGTH   32
 Number of characters needed to encode a guid as a string not including the null terminator. More...
 

Functions

GType gnc_guid_get_type (void)
 
const GncGUIDgnc_value_get_guid (const GValue *value)
 gnc_value_get_guid More...
 
void guid_replace (GncGUID *guid)
 Generate a new guid. More...
 
GncGUID guid_new_return (void)
 Generate a new id. More...
 
const GncGUIDguid_null (void)
 Returns a GncGUID which is guaranteed to never reference any entity. More...
 
GncGUIDguid_malloc (void)
 Allocate memory for a GUID. More...
 
GncGUIDguid_new (void)
 Allocate and construct a new GUID. More...
 
void guid_free (GncGUID *guid)
 
GncGUIDguid_copy (const GncGUID *guid)
 Returns a newly allocated GncGUID that matches the passed-in GUID. More...
 
gchar * guid_to_string (const GncGUID *guid)
 The guid_to_string() routine returns a null-terminated string encoding of the id. More...
 
gchar * guid_to_string_buff (const GncGUID *guid, gchar *buff)
 The guid_to_string_buff() routine puts a null-terminated string encoding of the id into the memory pointed at by buff. More...
 
gboolean string_to_guid (const gchar *string, GncGUID *guid)
 Given a string, replace the given guid with the parsed one unless the given value is null. More...
 
gboolean guid_equal (const GncGUID *guid_1, const GncGUID *guid_2)
 Given two GUIDs, return TRUE if they are non-NULL and equal. More...
 
gint guid_compare (const GncGUID *g1, const GncGUID *g2)
 
guint guid_hash_to_guint (gconstpointer ptr)
 Hash function for a GUID. More...
 
gint guid_g_hash_table_equal (gconstpointer guid_a, gconstpointer guid_b)
 Equality function for two GUIDs in a GHashTable. More...
 
GHashTable * guid_hash_table_new (void)
 Returns a GHashTable with <GUID*> as key and a <gpointer> as value and no destructor functions for key or value set. More...
 

Detailed Description

Globally Unique IDs provide a way to uniquely identify something.

A GncGUID is a unique, cryptographically random 128-bit value. The identifier is so random that it is safe to assume that there is no other such item on the planet Earth, and indeed, not even in the Galaxy or beyond.

QOF GncGUIDs can be used independently of any other subsystem in QOF. In particular, they do not require the use of other parts of the object subsystem. New GncGUIDs are usually created by initializing a new entity using qof_instance_init, rather than calling GncGUID functions directly.

Macro Definition Documentation

◆ GUID_ENCODING_LENGTH

#define GUID_ENCODING_LENGTH   32

Number of characters needed to encode a guid as a string not including the null terminator.

Definition at line 84 of file guid.h.

Function Documentation

◆ gnc_value_get_guid()

const GncGUID* gnc_value_get_guid ( const GValue *  value)

gnc_value_get_guid

Parameters
valuea GValue whose value we want to get.
Returns
the value stored in value

Definition at line 72 of file guid.cpp.

73 {
74  if (!value) return nullptr;
75  GncGUID *val;
76 
77  g_return_val_if_fail (value && G_IS_VALUE (value), nullptr);
78  g_return_val_if_fail (GNC_VALUE_HOLDS_GUID (value), nullptr);
79 
80  val = (GncGUID*) g_value_get_boxed (value);
81 
82  return val;
83 }
The type used to store guids in C.
Definition: guid.h:75

◆ guid_copy()

GncGUID* guid_copy ( const GncGUID guid)

Returns a newly allocated GncGUID that matches the passed-in GUID.

The returned pointer must be freed using guid_free.

Definition at line 120 of file guid.cpp.

121 {
122  if (!guid) return nullptr;
123  auto ret = guid_malloc ();
124  *ret = *guid;
125  return ret;
126 }
GncGUID * guid_malloc(void)
Allocate memory for a GUID.
Definition: guid.cpp:104

◆ guid_equal()

gboolean guid_equal ( const GncGUID guid_1,
const GncGUID guid_2 
)

Given two GUIDs, return TRUE if they are non-NULL and equal.

Return FALSE, otherwise.

Definition at line 204 of file guid.cpp.

205 {
206  if (!guid_1 || !guid_2)
207  return !guid_1 && !guid_2;
208  gnc::GUID temp1 {*guid_1};
209  gnc::GUID temp2 {*guid_2};
210  return temp1 == temp2;
211 }

◆ guid_g_hash_table_equal()

gint guid_g_hash_table_equal ( gconstpointer  guid_a,
gconstpointer  guid_b 
)

Equality function for two GUIDs in a GHashTable.

Definition at line 247 of file guid.cpp.

248 {
249  return guid_equal (reinterpret_cast<const GncGUID*> (guid_a),
250  reinterpret_cast<const GncGUID*> (guid_b));
251 }
gboolean guid_equal(const GncGUID *guid_1, const GncGUID *guid_2)
Given two GUIDs, return TRUE if they are non-NULL and equal.
Definition: guid.cpp:204

◆ guid_hash_table_new()

GHashTable* guid_hash_table_new ( void  )

Returns a GHashTable with <GUID*> as key and a <gpointer> as value and no destructor functions for key or value set.

Definition at line 254 of file guid.cpp.

255 {
256  return g_hash_table_new (guid_hash_to_guint, guid_g_hash_table_equal);
257 }
guint guid_hash_to_guint(gconstpointer ptr)
Hash function for a GUID.
Definition: guid.cpp:228
gint guid_g_hash_table_equal(gconstpointer guid_a, gconstpointer guid_b)
Equality function for two GUIDs in a GHashTable.
Definition: guid.cpp:247

◆ guid_hash_to_guint()

guint guid_hash_to_guint ( gconstpointer  ptr)

Hash function for a GUID.

Given a GncGUID *, hash it to a guint

Definition at line 228 of file guid.cpp.

229 {
230  if (!ptr)
231  {
232  PERR ("received nullptr guid pointer.");
233  return 0;
234  }
235  GncGUID const & guid = * reinterpret_cast <GncGUID const *> (ptr);
236  gnc::GUID const & temp {guid};
237 
238  guint hash {0};
239  std::for_each (temp.begin (), temp.end (), [&hash] (unsigned char a) {
240  hash <<=4;
241  hash |= a;
242  });
243  return hash;
244 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
The type used to store guids in C.
Definition: guid.h:75

◆ guid_malloc()

GncGUID* guid_malloc ( void  )

Allocate memory for a GUID.

This does not construct a GUID. In other words, the returned pointer has not necessarily been initialized. The returned pointer must be freed with * guid_free.

Definition at line 104 of file guid.cpp.

105 {
106  return new GncGUID;
107 }
The type used to store guids in C.
Definition: guid.h:75

◆ guid_new()

GncGUID* guid_new ( void  )

Allocate and construct a new GUID.

The returned pointer must be released with guid_free.

Definition at line 151 of file guid.cpp.

152 {
153  auto ret = guid_new_return ();
154  return guid_copy (&ret);
155 }
GncGUID guid_new_return(void)
Generate a new id.
Definition: guid.cpp:158
GncGUID * guid_copy(const GncGUID *guid)
Returns a newly allocated GncGUID that matches the passed-in GUID.
Definition: guid.cpp:120

◆ guid_new_return()

GncGUID guid_new_return ( void  )

Generate a new id.

Returns
guid A data structure containing a copy of a newly constructed GncGUID.

Definition at line 158 of file guid.cpp.

159 {
160  return gnc::GUID::create_random ();
161 }

◆ guid_null()

const GncGUID* guid_null ( void  )

Returns a GncGUID which is guaranteed to never reference any entity.

Do not free this value! The same pointer is returned on each call.

Definition at line 130 of file guid.cpp.

131 {
132  return s_null_gncguid;
133 }

◆ guid_replace()

void guid_replace ( GncGUID guid)

Generate a new guid.

Parameters
guidA pointer to an allocated guid data structure. The existing value will be replaced with a new value.

Definition at line 143 of file guid.cpp.

144 {
145  if (!guid) return;
146  gnc::GUID temp_random {gnc::GUID::create_random ()};
147  guid_assign (*guid, temp_random);
148 }

◆ guid_to_string()

gchar* guid_to_string ( const GncGUID guid)

The guid_to_string() routine returns a null-terminated string encoding of the id.

String encodings of identifiers are hex numbers printed only with the characters '0' through '9' and 'a' through 'f'. The encoding will always be GUID_ENCODING_LENGTH characters long (not including the null terminator).

Parameters
guidThe guid to print.
Returns
A pointer to the starting character of the string. The returned memory is owned by the calling routine and must be freed using g_free.

Definition at line 164 of file guid.cpp.

165 {
166  if (!guid) return nullptr;
167  gnc::GUID temp {*guid};
168  auto temp_str = temp.to_string ();
169  return g_strdup (temp_str.c_str ());
170 }

◆ guid_to_string_buff()

gchar* guid_to_string_buff ( const GncGUID guid,
gchar *  buff 
)

The guid_to_string_buff() routine puts a null-terminated string encoding of the id into the memory pointed at by buff.

The buffer must be at least GUID_ENCODING_LENGTH+1 characters long. This routine is handy for avoiding a malloc/free cycle. It returns a pointer to the >>end<< of what was written. (i.e. it can be used like 'stpcpy' during string concatenation)

Parameters
guidThe guid to print.
buffThe buffer to print it into.
Returns
A pointer to the terminating null character of the string, or, if no copy took place, NULL.

Definition at line 173 of file guid.cpp.

174 {
175  if (!str || !guid) return nullptr;
176 
177  gnc::GUID temp {*guid};
178  auto val = temp.to_string ();
179  /*We need to be sure to copy the terminating null character.
180  * The standard guarantees that std::basic_string::c_str ()
181  * returns with a terminating null character, too.*/
182  std::copy (val.c_str (), val.c_str () + val.size () + 1, str);
183  return str + val.size ();
184 }

◆ string_to_guid()

gboolean string_to_guid ( const gchar *  string,
GncGUID guid 
)

Given a string, replace the given guid with the parsed one unless the given value is null.

If null is passed as guid or string, false is returned and nothing is done, otherwise, the function returns true. This function accepts both uppor and lower case hex digits. If letters outside the range of [a-fA-F] are passed, they are silently replaced. If non-alphanumeric digits are given, this function will either return false or replace those values with others.