X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Finterface.html;h=5e9d8b23cb980f4eaef7fa1002067c3e40331fc8;hb=a5bd4c3c89f5cb433a615c436947b8b0f44c3661;hp=65626e929686faeae53225ccde7dc1a3ad92d71f;hpb=697e964cef3b6c7d485c4ee2b6e7e823963e03f0;p=gedcom-parse.git diff --git a/doc/interface.html b/doc/interface.html index 65626e9..5e9d8b2 100644 --- a/doc/interface.html +++ b/doc/interface.html @@ -14,11 +14,11 @@
  • Gedcom_val types
    • @@ -1865,13 +1865,13 @@ the value that is returned by GEDCOM_STRING(val) is always the s raw_value passed to the start callback, and is thus in fact redundant.

    The date value is used for all elements that return a date.  See -here for the definition.
    +here for the definition.

    The xref value is for cross-references between records in the file.  See -here for the definition.
    +here for the definition.

    -

    struct date_value

    +

    struct date_value

    This struct describes a date as given in the GEDCOM file, and has the following definition:
    @@ -1999,7 +1999,7 @@ the value that is returned by GEDCOM_STRING(val) is always the s
    -

    struct date
    +

    struct date

    The date1 and date2 also have a strict syntax:
    @@ -2184,7 +2184,7 @@ The modifier can be one of the following:
  • AGE_NO_MODIFIER : no modifier
  • AGE_LESS_THAN  : the modifier '<' is added
  • AGE_GREATER_THAN : the modifier '>' is added

    • -

    struct xref_value

    +

    struct xref_value

    This struct represents a cross-reference in the GEDCOM file (but note that the Gedcom_val contains a pointer to such a struct, not the struct @@ -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