Hics Extension Built-in Functions
The Hics extension extends the number of functions built-in which are always available. These are described below in the following groups:-
| Group | Functions |
|---|---|
| Date Representation | @date, @text, @scheme, @element, @phrase |
| Moveable Days | @easter |
| Scheme Details | @sch:list, @sch:object, @leapyear, @first, @last |
| Format Details | @fmt:object |
Date Representation
The hics extension can uniquely describe a single day in Earth's past or future in three different ways.
- Date A Julian Day Number (jdn). Uses a Field value type.
- Text A character string with a defined calendar scheme and format. Uses a String value type.
- Scheme A scheme object with fields as defined by the scheme definition. Uses an Object value type.
Additionally, a text element and field in a scheme record can be converted using an element function.
Finally, a date set can be represented as a text date phrase which can be converted to a well ordered list (RList type) with the phrase function.
| Function | Description |
|---|---|
| @date.sch:fmt( string_type ) @date( scheme_object_type ) | Converts to a set_type. |
| @text.sch:fmt( set_type ) @text.sch:fmt( scheme_object_type ) | Converts to a string_type. |
| @scheme.sch( set_type ) @scheme.sch:fmt( string_type ) | Converts to a scheme_object_type. |
| @element.qual( field_type ) @element.qual( string_type ) |
Converts field_type to string_type. Converts string_type to field_type. |
| @phrase.sch:fmt( string_type ) | Converts phrase string to a set_type. |
Function: @date.sch:fmt( value )
A date, in this context, means a rlist or an well ordered list of ranges. The date function converts to these types from a text string or a record (scheme object). The date function puts these two record types into a consistent rlist type. The rlist will then be demoted to a range or field if appropriate.
If the original type is a string, then the function will need to know the scheme and format to be used. To convert to a record then the record scheme is required. If these are missing, the system output default settings are used. Note the a string description of an rlist may include embedded range and union symbols, but this is different from a Date Phrase. For instance, only one scheme format can be used for the conversion.
| Example | Result |
|---|---|
| @date( "19sep1948" ) | 2432814 |
| @date( "1940..1950|1945..1955" ) | 2429630..2435473 |
| @date.g:iso( "[1940..1950,1945..1955]" ) | 2429630..2435473 |
| @date( {s:g 1948, 9, 19} ) | 2432814 |
| @date( {s:g 1948} ) | 2432552..2432917 |
| The above examples assume a system input setting of "g:dmy". | |
Function: @text.sch:fmt( value )
The text function converts a field, range, rlist or scheme object type into a string type.
Except for a record type, the scheme code signature must be provided. If the format code is not included in the signature, then the default for that scheme is used.
| Example | Result |
|---|---|
| @text."g:dmy+"( 2432814 ) | "19 September 1948" |
| @text.g( 2429630..2435473 ) | "1940..1955" |
| @text.g:iso( 2429630..2429995 | 2433283..2435473 ) | "[1940,1950..1955]" |
| @text( {s:g 1948, 9, 19} ) | "19 Sep 1948" |
| @text( {s:j 1948} ) | "1948" |
| The above examples assume a system output setting of "g:dmy". | |
Function: @scheme.sch:fmt( value )
The scheme function converts a field (as a julian day number) or string type into a record type. At this time, using the scheme function with a range or rlist type is an error.
If a scheme:format signature is not given, then to convert a field, the output default setting is used, and if converting a string, the input default is used.
Note that a scheme object created from the function always has all fields included, even the optional ones. Only main fields are given values though.
| Example | Result |
|---|---|
| @scheme.g:dmy( "19sep1948" ) | {s:g 1948, 9, 19, 7} |
| @scheme( "21??" ) | {s:g null, null, 21, null} |
| @scheme.:u( "1948year 9month 19day" ) | {s:g 1948, 9, 19, 7} |
| @scheme.j( 2432814 ) | {s:j 1948, 9, 6, 7} |
| @scheme( 2429630..2435473 ) | Error |
| The above examples assume a system input and output setting of "g:dmy". | |
Function: @element.qual( value )
The element function converts between a string and a field. If a lexicon code is given with the function then that lexicon is used to provide the conversion. Using the function on any type other than a field or string results in an error.
| Example | Result |
|---|---|
| @element.w( 7 ) | "Sunday" |
| @element.ws:a( 7 ) | "Sat" |
| @element.w( "wed" ) | 3 |
| @element.:rn( "xiv" ) | 14 |
| @element.:rn( 14 ) | "XIV" |
| @element.:rn:l( 14 ) | "xiv" |
| @element.:os( 2 ) | "2nd" |
| @element.:oa( 2 ) | "nd" |
| @element.:oa:u( 2 ) | "ND" |
| @element( "10" ) | 10 |
| @element( 10 ) | "10" |
Function: @phrase.sch:fmt( string )
A date phrase is a meta language similar to the Glich language but designed to write a period or periods of time in days. A default calendar scheme can be defined for the phrase, and elements within the phrase can use different calendar schemes.
See the Date Phrase Meta Language page for details.
The phrase function takes a date phrase string and converts it to a well ordered rlist.
| Example | Result |
|---|---|
| @phrase.g:dmy( "10nov2023" ) | 2460259 |
| @phrase( "!today&.2023" ) | 2459946..2460258 | 2460260..2460310 |
| @phrase( "8mar1741 | j:dmy# 8mar1741 | ja:dmc# 8mar1741" ) | 2357014 | 2357025 | 2357390 |
| @phrase( "1890..1900 | 1910..1920" ) | 2411369..2415385 | 2418673..2422690 |
| The above examples assume a system input and output setting of "g:dmy" and today = 10 Nov 2023. | |
Moveable Days
| Function | Description |
|---|---|
| @easter.base( year ) | Result is the jdn day of Easter Sunday for year. |
Function @easter.base( year )
The easter function returns Easter Sunday for the given year. The base calendar can be either julian or gregorian. Both the base and the year are required.
| Example | Result |
|---|---|
| @easter.gregorian( 2025 ) | 2460786 |
| @easter.julian( 1750 ) | 2360350 |
Scheme Details
| Function | Description |
|---|---|
| @sch:list | Returns an object with a list of available scheme codes (scodes). |
| @sch:object.scode | Returns a sch: object detailing the scheme. |
| @leapyear.scode( year ) | Returns 'true' if the year is a leap year, otherwise 'false' |
| @first | First value of scheme record field. Development |
| @last | Last value of scheme record field. Development |
Function: @sch:list
Function returns an object containing a list of available scheme codes (scodes).
| Example | Result |
|---|---|
| @sch:list | {: "ay", "c", "eh", "fr", "g", "go", "gw", "h", "i", "if", "ims", "j", "ja", "jap", "jce", "jdn", "je", "jn", "jwn", "jwsn", "mjd", "rd"} |
| @sch:list@size | 22 |
Function: @sch:object
Function returns a sch: object type.
| Example | Result |
|---|---|
| @sch:object.g | {sch: "g", "Gregorian", "gregorian", {: "year", "month", "day", "wday"}, "g", {: "iso", "iso_set", "dmy", "dmy+", "wdmy", "wdmy+", "out", "full", "mdy", "mdy+", "wmdy", "wmdy+", "ymd", "def", "u"}, "dmy", "dmy", true} |
| @sch:object.jce[fieldnames] | {: "year", "month", "day", "ce", "ceyear", "wday"} |
Function: @leapyear
If the calendar is a lunar-solar calendar type, then if there are 13 months in the year, the function returns true. If the calendar is a solar calendar type, the function returns true if there is an extra day in the year. For every other situation, the function returns false.
Format Details
| Function | Description |
|---|---|
| @fmt:object.fcode | Returns a fmt: object detailing the format. |
Function: @fmt:object
Function returns a fmt: object type.
| Example | Result |
|---|---|
| @fmt:object.g:dmy | {fmt: "dmy", "j", "text", true, "day month year", "dd Mon yyyy", true} |
| @fmt:object.jce:dmye[pseudo:out] | dd Mon yyyy CE |
