X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Finterface.html;h=906aeea95a226a7d5c42ff8dfb988c55523d1d8e;hb=c80fb171c952d002191509a343bb4c3747dffc35;hp=d41fe7ff9d1b781f7b19970aa077964e1f80021a;hpb=d069cfbd954ca8d53d780ce97d7da1d363bb51fe;p=gedcom-parse.git diff --git a/doc/interface.html b/doc/interface.html index d41fe7f..906aeea 100644 --- a/doc/interface.html +++ b/doc/interface.html @@ -2312,6 +2312,9 @@ the value that is returned by GEDCOM_STRING(val) is always the s
+The following function creates a new date_value struct and initializes it properly, or copies an existing date value: +
struct date_value* gedcom_new_date_value (struct date_value* copy_from);
+If the parameter copy_from is NULL, a new value is created and given initial values.  If it is non-NULL, the value is copied into a new date value.

struct date

@@ -2415,10 +2418,85 @@ to DATE_BOUNDED.
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.
+ +
+ +
+To ensure that an updated date value is consistent, i.e. all +its struct fields are consistent with each other, the following function +can be used:
+
int gedcom_normalize_date (Date_input compute_from, struct date_value* value);
+ +The compute_from parameter determines which fields +will be taken as input to compute the other fields.  The following table +gives an overview of the input and output parameters (the calendar type cal is always an input parameter, and should not be CAL_UNKNOWN):
+
+ + + + + + + + + + + + + + + + + + + + + + + +
compute_from
+ 		input parameters
+ 		output parameters
+
DI_FROM_STRINGS
+ 		day_str, month_str, year_str
+ 		day, month, year, year_type
+type, sdn1, sdn2
+
DI_FROM_NUMBERS
+ 		day, month, year, year_type
+ 		day_str, month_str, year_str
+ +type, sdn1, sdn2
+
DI_FROM_SDN
+ 		type, sdn1, sdn2
+ 		day, month, year
+day_str, month_str, year_str
+
+
+If the type in the date value is DV_PHRASE, no conversions take +place, otherwise one or both of the date structs are processed according +to the table above, depending on the type.  The function returns 0 in case of success, non-zero in case of an error.
+
+This function could also be used to convert a date from one calendar to another, +because the serial day number is calendar independent (error handling is +ignored in this example):
+
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

This struct describes an age as given in the GEDCOM file, and has the @@ -2497,7 +2575,10 @@ The modifier can be one of the following:
-
+The following function creates a new age_value struct and initializes it properly, or copies an existing age value: +
struct age_value* gedcom_new_age_value (struct age_value* copy_from);
+ +If the parameter copy_from is NULL, a new value is created and given initial values.  If it is non-NULL, the value is copied into a new age value.

struct xref_value

This struct represents a cross-reference in the GEDCOM file (but note that @@ -2609,4 +2690,5 @@ An example would thus be: "@This is an xref_val@".



+
\ No newline at end of file