Libgedcom interface details

Index

• Record identifiers
• Element identifiers
• Gedcom_val types
• struct date_value
• struct date
• struct age_value
  
• struct xref_value
  

Record identifiers

Element identifiers

Gedcom_val types

struct date_value

struct date_value {
  Date_value_type  type;
  struct date      date1;
  struct date      date2;
  char             phrase[MAX_PHRASE_LEN + 1];
};

struct date_value* gedcom_new_date_value (const struct date_value* copy_from);


struct date

struct date {
  Calendar_type  cal;
  char           day_str[MAX_DAY_LEN + 1];
  char           month_str[MAX_MONTH_LEN + 1];
  char           year_str[MAX_YEAR_LEN + 1];

  int            day;
  int            month;
  int            year;
  Year_type      year_type;

  Date_type      type;
  long int       sdn1;
  long int       sdn2;
};

• CAL_GREGORIAN : the Gregorian calendar
• CAL_JULIAN : the Julian calendar
• CAL_HEBREW : the Hebrew (Jewish) calendar
• CAL_FRENCH_REV : the calendar used after the French Revolution
• CAL_UNKNOWN : an unknown calendar type

• the day is just the numeric representation of the day_str (starting from 1), -1 if the day_str is empty
• the month is the month number of month_str in the given calendar type (also starting from 1), -1 if the month_str is empty
• the year is the numeric representation of the year_str

• Exact dates (e.g. "25 MAR 1990"):

These are represented by a serial day number in sdn1 and a Date_type equal to DATE_EXACT.

• Incomplete dates (e.g. "MAR 1990"):

These are represented by 2 serial day numbers (sdn1 and sdn2) and a Date_type equal to DATE_BOUNDED.

For example, the Gregorian date "MAR 1990" is represented by the serial day numbers for "1 MAR 1990" and "31 MAR 1990", and the Gregorian date "1990" is represented by the serial day numbers for "1 JAN 1990" and "31 DEC 1990".  Similarly for the other calendar types.

int gedcom_normalize_date (Date_input compute_from, struct date_value* value);


struct date_value* dv = gedcom_new_date_value(NULL);
dv->date1.cal = CAL_GREGORIAN;
dv->date1.day   = 4;
dv->date1.month = 2;
dv->date1.year  = 1799;
dv->date1.year_type = YEAR_SINGLE;
gedcom_normalize_date(DI_FROM_NUMBERS, dv);

dv->date1.cal = CAL_FRENCH_REV;
gedcom_normalize_date(DI_FROM_SDN, dv);
/* the day, month and year are now filled in according to the French Revolution calendar */

struct age_value

struct age_value {
  Age_type      type;
  Age_modifier  mod;
  int           years;
  int           months;
  int           days;
  char          phrase[MAX_PHRASE_LEN + 1];
};

• AGE_NO_MODIFIER : no modifier
• AGE_LESS_THAN  : the modifier '<' is added
• AGE_GREATER_THAN : the modifier '>' is added

struct age_value* gedcom_new_age_value (const struct age_value* copy_from);


struct xref_value

struct xref_value {
  Xref_type   type,
  char*       string,
  Gedcom_ctxt object
};

• XREF_NONE (used as default value)
• XREF_FAM
• XREF_INDI
• XREF_NOTE
• XREF_OBJE
• XREF_REPO
• XREF_SOUR
• XREF_SUBM
• XREF_SUBN
• XREF_ANY (if the type is not known, see below)
  
• XREF_USER (for application-specific cross-references)
  

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
  

• an at sign ('@')
• followed by an alphanumeric character (A-Z, a-z, 0-9 or underscore)
• followed by zero or more characters, which can be any character except an at sign
• terminated by an at sign ('@')

$Id$
$Name$