From: Peter Verthez Date: Fri, 1 Nov 2002 13:46:21 +0000 (+0000) Subject: Document the new cross-reference handling functions. X-Git-Url: https://git.dlugolecki.net.pl/?a=commitdiff_plain;h=b9c6fb3bbed07eceb019666e101b55265a8abdc3;p=gedcom-parse.git Document the new cross-reference handling functions. --- diff --git a/doc/interface.html b/doc/interface.html index 16e66e9..5e9d8b2 100644 --- a/doc/interface.html +++ b/doc/interface.html @@ -2234,11 +2234,54 @@ an error is produced).  The first two checks are done at the end of the parsing, because cross-references can be defined after their usage in GEDCOM.

-An xref_value can also be retrieved by its key via the following function:
- -
struct xref_value* gedcom_get_by_xref (char *key)
+The following functions are available to manipulate xref_value objects:
+
struct xref_value* gedcom_get_by_xref (const char *key)
+
 Retrieve an xref_value by its key.  Returns NULL if the given key isn't a valid cross-reference key (see below) or isn't used.
+
+ struct xref_value* gedcom_add_xref (Xref_type type, const char* key, Gedcom_ctxt object)
+
Add an xref_value of the given type (see list above), with the given key, to the given object, with a use count equal to 0.  Returns the new xref_value if success.  Returns NULL in one of the following cases:
+
    +
  • the key isn't a valid cross-reference key (see below)
    • +
  • there is already an xref_value with the same key
    • +
  • there was a memory allocation error
    • +
+
+ int gedcom_delete_xref (const char* key)
+ +
Delete the xref_value corresponding to the given key.  Returns 0 if success.  Returns 1 in one of the following cases:
+
    +
  • the key isn't a valid cross-reference key (see below)
    • +
  • there is no xref_value with the given key
    • +
  • the xref_value is still in use, i.e. its use count is not 0 (see gedcom_link_xref and gedcom_unlink_xref below)
    • +
+
+ struct xref_value* gedcom_link_xref (Xref_type type, const char* key)
+struct xref_value* gedcom_unlink_xref (Xref_type type, const char* key)
+
Declare the xref_value corresponding to the given key as being +used/no longer used (linked to or unlinked) as the given type.  The +use of these functions is not mandatory, but it can aid in spotting places in the code where xref_value objects are deleted while they are still referenced.
+
+Returns the xref_value object if success, and its use count is incremented/decremented.  Returns NULL in one of the following cases:
+
    +
  • the key isn't a valid cross-reference key (see below)
    • +
  • there is no xref_value with the given key
    • +
  • the xref_value was previously added as another type than the type provided here
    +
    • +
+
+
+
-The function returns NULL if the given key isn't used.
+ +A cross-reference key must be a string of maximum 22 characters, of the following format:
+ +An example would thus be: "@This is an xref_val@".
+ 
$Id$
$Name$
@@ -2248,4 +2291,5 @@ The function returns NULL if the given key isn't used.



- +
+ \ No newline at end of file