From 345296659bc1d9c40bfd4bc5aa1c838a3b4cf491 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Thu, 15 Dec 2022 19:19:20 -0600 Subject: [PATCH] Update: Add formal specification for Time and EpochTime and use IKI in the files. --- documents/time.txt | 58 ++++++----- level_3/controller/documents/time.txt | 58 ++++++----- level_3/controller/specifications/time.txt | 155 +++++++++++++++++++++++++++++ specifications/time.txt | 155 +++++++++++++++++++++++++++++ 4 files changed, 376 insertions(+), 50 deletions(-) create mode 100644 level_3/controller/specifications/time.txt create mode 100644 specifications/time.txt diff --git a/documents/time.txt b/documents/time.txt index 53f8027..05a3a28 100644 --- a/documents/time.txt +++ b/documents/time.txt @@ -2,24 +2,30 @@ # # license: open-standard-license-1.0 # +# This file (assumed to be named time.txt) can be more easily read using the following iki_read commands: +# iki_read time.txt +Q -r UTC UTC -w -WW character "'" "'" code '"' '"' +# +# To read the "IKI Specification: 0000 - Unrestricted" section of this file, use this command sequence: +# fss_basic_list_read time.txt +Q -cn "Time Specification" | iki_read +Q -r UTC UTC -w -WW character "'" "'" code '"' '"' +# Time Documentation: - The FLL project and relating programs might utilize the unit of measurement called a "Time", represented with uppercase "T". - For comparison, a unit of Time is equivalent to a nanosecond, or 10^-9 seconds. - A MegaTime (MT) is therefore equivalent to a millisecond such that a millisecond is 10^-3 seconds. + This documents a unit of measurement called a bold:"Time", represented with uppercase bold:"T". + For comparison, a unit of bold:"Time" is equivalent to a nanosecond, or 10^-9 seconds. + A bold:"MegaTime (MT)" is therefore equivalent to a millisecond such that a millisecond is 10^-3 seconds. - A unit of Time is intended to represent some unit of Time such that a single 64-bit integer may hold all units of Time for a single calendar year. - This unit of Time does not and must not include Years (unlike Unixtime). - To convert from Time to Unixtime, one must have a year (which could be assumed to be the current year) and then calculate all of those calendar oddities. + A unit of bold:"Time" is intended to represent some unit of bold:"Time" such that a single 64-bit integer may hold all units of bold:"Time" for a single calendar year. + This unit of bold:"Time" does not and must not include bold:"Years" (unlike bold:"Unix time"). + To convert from bold:"Time" to bold:"Unix time", one must have a year (which could be assumed to be the current year) and then calculate all of those calendar oddities. - A unit of Time by default is assumed to be in UTC. - 1 (Earth) year ~= 31536000000000000 Time or 31536000 GT (GigaTime). - 1 (Earth) day = 86400000000000 Time or 86400 GT (GigaTime). - 1 (Earth) hour = 3600000000000 Time or 3600 GT (GigaTime). - 1 (Earth) minute = 60000000000 Time or 60 GT (GigaTime). - 1 (Earth) second = 1000000000 Time or 1 GT (GigaTime). + A unit of bold:"Time" by default is assumed to be in UTC:"Coordinated Universal Time". + - code:"1 (Earth) year ~= 31536000000000000 Time or 31536000 GT (GigaTime)". + - code:"1 (Earth) day = 86400000000000 Time or 86400 GT (GigaTime)". + - code:"1 (Earth) hour = 3600000000000 Time or 3600 GT (GigaTime)". + - code:"1 (Earth) minute = 60000000000 Time or 60 GT (GigaTime)". + - code:"1 (Earth) second = 1000000000 Time or 1 GT (GigaTime)". - Consequentially, 1 day is easily represented in units of Time as 86.4 TT (TeraTime). + Consequentially, 1 day is easily represented in units of bold:"Time" as code:"86.4 TT (TeraTime)". The Time may be stored in its "year string format". In this format, a Year may be prepended to the Time followed by a single colon ':' to associate a year with the Time. @@ -27,17 +33,19 @@ Time Documentation: For example, "2020:86400000000000" would represent: January 02, 2020 0:00 UTC. For example, "2020:86.4 TT" would represent: January 02, 2020 0:00 UTC. - A second unit of Time, called EpochTime, works the same way as Time except it represents seconds. - This unit is designated "E". - The format is similar to Time, except there are two colons: "1970::1620874738" would represent: May 13, 2021 2:58:58 UTC. - When the year is not specified, then this is identical to UNIX Epoch. + A second unit of bold:"Time", called bold:"EpochTime", works the same way as bold:"Time" except it represents seconds. + This unit is designated code:"ET". + The format is similar to bold:"Time", except there are two colons: code:"1970::1620874738" would represent: code:"May 13, 2021 2:58:58 UTC". + When the year is not specified, then this is identical to bold:"UNIX Epoch". + + A unit of bold:"EpochTime" by default is assumed to be in UTC:"Coordinated Universal Time". + - code:"1 (Earth) year ~= 31536000 EpochTime or 31.536 GE (GigaEpochTime)". + - code:"1 (Earth) day = 86400 EpochTime". + - code:"1 (Earth) hour = 3600 EpochTime". + - code:"1 (Earth) minute = 60 EpochTime". + - code:"1 (Earth) second = 1 EpochTime". + - code:"1 GT (GigaTime) = 1 EpochTime". - A unit of EpochTime by default is assumed to be in UTC. - 1 (Earth) year ~= 31536000 EpochTime or 31.536 GE (GigaEpochTime). - 1 (Earth) day = 86400 EpochTime - 1 (Earth) hour = 3600 EpochTime - 1 (Earth) minute = 60 EpochTime - 1 (Earth) second = 1 EpochTime - 1 GT (GigaTime) = 1 EpochTime + Consequentially, 1 day is easily represented in units of bold:"EpochTime" as code:"86.4 KE (KiloEpochTime)". - Consequentially, 1 day is easily represented in units of EpochTime as 86.4 KE (KiloEpochTime). + See the specification file:"time.txt" for more precise technical details. diff --git a/level_3/controller/documents/time.txt b/level_3/controller/documents/time.txt index b158c8d..05a3a28 100644 --- a/level_3/controller/documents/time.txt +++ b/level_3/controller/documents/time.txt @@ -2,24 +2,30 @@ # # license: open-standard-license-1.0 # +# This file (assumed to be named time.txt) can be more easily read using the following iki_read commands: +# iki_read time.txt +Q -r UTC UTC -w -WW character "'" "'" code '"' '"' +# +# To read the "IKI Specification: 0000 - Unrestricted" section of this file, use this command sequence: +# fss_basic_list_read time.txt +Q -cn "Time Specification" | iki_read +Q -r UTC UTC -w -WW character "'" "'" code '"' '"' +# Time Documentation: - The Controller program utilizes the unit of measurement called a "Time", represented with uppercase "T". - For comparison, a unit of Time is equivalent to a nanosecond, or 10^-9 seconds. - A MegaTime (MT) is therefore equivalent to a millisecond such that a millisecond is 10^-3 seconds. + This documents a unit of measurement called a bold:"Time", represented with uppercase bold:"T". + For comparison, a unit of bold:"Time" is equivalent to a nanosecond, or 10^-9 seconds. + A bold:"MegaTime (MT)" is therefore equivalent to a millisecond such that a millisecond is 10^-3 seconds. - A unit of Time is intended to represent some unit of Time such that a single 64-bit integer may hold all units of Time for a single calendar year. - This unit of Time does not and must not include Years (unlike Unixtime). - To convert from Time to Unixtime, one must have a year (which could be assumed to be the current year) and then calculate all of those calendar oddities. + A unit of bold:"Time" is intended to represent some unit of bold:"Time" such that a single 64-bit integer may hold all units of bold:"Time" for a single calendar year. + This unit of bold:"Time" does not and must not include bold:"Years" (unlike bold:"Unix time"). + To convert from bold:"Time" to bold:"Unix time", one must have a year (which could be assumed to be the current year) and then calculate all of those calendar oddities. - A unit of Time by default is assumed to be in UTC. - 1 (Earth) year ~= 31536000000000000 Time or 31536000 GT (GigaTime). - 1 (Earth) day = 86400000000000 Time or 86400 GT (GigaTime). - 1 (Earth) hour = 3600000000000 Time or 3600 GT (GigaTime). - 1 (Earth) minute = 60000000000 Time or 60 GT (GigaTime). - 1 (Earth) second = 1000000000 Time or 1 GT (GigaTime). + A unit of bold:"Time" by default is assumed to be in UTC:"Coordinated Universal Time". + - code:"1 (Earth) year ~= 31536000000000000 Time or 31536000 GT (GigaTime)". + - code:"1 (Earth) day = 86400000000000 Time or 86400 GT (GigaTime)". + - code:"1 (Earth) hour = 3600000000000 Time or 3600 GT (GigaTime)". + - code:"1 (Earth) minute = 60000000000 Time or 60 GT (GigaTime)". + - code:"1 (Earth) second = 1000000000 Time or 1 GT (GigaTime)". - Consequentially, 1 day is easily represented in units of Time as 86.4 TT (TeraTime). + Consequentially, 1 day is easily represented in units of bold:"Time" as code:"86.4 TT (TeraTime)". The Time may be stored in its "year string format". In this format, a Year may be prepended to the Time followed by a single colon ':' to associate a year with the Time. @@ -27,17 +33,19 @@ Time Documentation: For example, "2020:86400000000000" would represent: January 02, 2020 0:00 UTC. For example, "2020:86.4 TT" would represent: January 02, 2020 0:00 UTC. - A second unit of Time, called EpochTime, works the same way as Time except it represents seconds. - This unit is designated "E". - The format is similar to Time, except there are two colons: "1970::1620874738" would represent: May 13, 2021 2:58:58 UTC. - When the year is not specified, then this is identical to UNIX Epoch. + A second unit of bold:"Time", called bold:"EpochTime", works the same way as bold:"Time" except it represents seconds. + This unit is designated code:"ET". + The format is similar to bold:"Time", except there are two colons: code:"1970::1620874738" would represent: code:"May 13, 2021 2:58:58 UTC". + When the year is not specified, then this is identical to bold:"UNIX Epoch". + + A unit of bold:"EpochTime" by default is assumed to be in UTC:"Coordinated Universal Time". + - code:"1 (Earth) year ~= 31536000 EpochTime or 31.536 GE (GigaEpochTime)". + - code:"1 (Earth) day = 86400 EpochTime". + - code:"1 (Earth) hour = 3600 EpochTime". + - code:"1 (Earth) minute = 60 EpochTime". + - code:"1 (Earth) second = 1 EpochTime". + - code:"1 GT (GigaTime) = 1 EpochTime". - A unit of EpochTime by default is assumed to be in UTC. - 1 (Earth) year ~= 31536000 EpochTime or 31.536 GE (GigaEpochTime). - 1 (Earth) day = 86400 EpochTime - 1 (Earth) hour = 3600 EpochTime - 1 (Earth) minute = 60 EpochTime - 1 (Earth) second = 1 EpochTime - 1 GT (GigaTime) = 1 EpochTime + Consequentially, 1 day is easily represented in units of bold:"EpochTime" as code:"86.4 KE (KiloEpochTime)". - Consequentially, 1 day is easily represented in units of EpochTime as 86.4 KE (KiloEpochTime). + See the specification file:"time.txt" for more precise technical details. diff --git a/level_3/controller/specifications/time.txt b/level_3/controller/specifications/time.txt new file mode 100644 index 0000000..71c7f58 --- /dev/null +++ b/level_3/controller/specifications/time.txt @@ -0,0 +1,155 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named time.txt) can be more easily read using the following iki_read commands: +# iki_read time.txt +Q -r UTC UTC -w -WW character "'" "'" code '"' '"' +# +# To read the "IKI Specification: 0000 - Unrestricted" section of this file, use this command sequence: +# fss_basic_list_read time.txt +Q -cn "Time Specification" | iki_read +Q -r UTC UTC -w -WW character "'" "'" code '"' '"' +# + +Time Specification: + There are two units of bold:"Time", the first is simply called bold:"Time" and the second is called bold:"EpochTime". + + Both bold:"Time" and bold:"EpochTime" are measured without the year but may contain a year to designate the point in the counting begins. + These are both represented by a single 64-bit (unsigned) integer. + The default timezone is always UTC:"Coordinated Universal Time". + + The common form is intended as the non-technical form that is form common use. + This may have a negative value or be more than 64-bit digits long. + This is simply not expected to be interpreted as a unit of time on a computer (but nothing stops it from being interpreted). + + The technical forms are limit to 64-bit unsigned for technical use but should technology advance to a point where larger bits are needed then this allows for that. + The systems should expect 64-bit and larger bits would have to become common before something larger than 64-bit is the expected or assumed default. + Negative signs can be allowed but they must not prevent the full use of the 64-bit. + The implementation of how this is done is left to the implementer except that the signs are immediately to the left of the digit. + For example code:"2022:-5" would be 5 units after the start of the year 2022. + Because the negative is allowed, so must the positive character (such as code:"2022:+5"). + A positive value is the default interpretation when no sign is valid. + + The unit of time called bold:"Time" is counted increments of a nanosecond, or 10^-9 seconds. + A unit of bold:"Time" is, therefore, equivalent to a nanosecond. + The default year for bold:"Time" is the current year. + + The unit of time called bold:"EpochTime" is counted increments of a second, or 10^-9 seconds. + A unit of bold:"EpochTime" is, therefore, equivalent to a second. + The default year for bold:"EpochTime" is the bold:"UNIX Epoch", sometimes called bold:"Unix time". + + The unit bold:"Time" has two technical forms and one common form, with the year and without the year. + + Key\: + code:"\s" = White space. + code:"\d" = The digits used to represent time (a digit). + code:"*" = Zero or more occurrences. + code:"+" = One or more occurrences. + code:":" = A single colon character:":" (unicode:"U+003A"). + code:'"' = A single double-quote character:'"' (unicode:"U+003A"). + + The common form of bold:"Time"\: + + Before Structure\: + code:"". + + Structure\: + code:"\s*\d+\s*\U*\s*". + + After Structure\: + code:"". + + Example\: + code:"86400". + code:"86400 T". + code:"86400 Time". + + The first technical form of bold:"Time"\: + + Before Structure\: + code:"". + + Structure\: + code:"\s*\d+:\d+\s*\U*\s*". + + After Structure\: + code:"". + + Example\: + code:"2022:86400". + code:"2022:86400 T". + code:"2022:86400 Time". + code:"2022:86400 MT". + code:"2022:86400 MegaTime". + + The second technical form of bold:"Time"\: + + Before Structure\: + code:"". + + Structure\: + code:"\s*:\d+\s*\U*\s*". + + After Structure\: + code:"". + + Example\: + code:":86400". + code:":86400 T". + code:":86400 Time". + code:":86400 MT". + code:":86400 MegaTime". + + The unit bold:"EpochTime" has two technical forms and one common form, with the year and without the year. + + The common form of bold:"Time"\: + + Before Structure\: + code:"". + + Structure\: + code:"\s*\d+\s*\U*\s*". + + After Structure\: + code:"". + + Example\: + code:"86400". + code:"86400 ET". + code:"86400 EpochTime". + code:"86400 MET". + code:"86400 MegaEpochTime". + + The first technical form of bold:"EpochTime"\: + + Before Structure\: + code:"". + + Structure\: + code:"\s*\d+::\d+\s*\U*\s*". + + After Structure\: + code:"". + + Example\: + code:"2022::86400". + code:"2022::86400 ET". + code:"2022::86400 EpochTime". + code:"2022::86400 MET". + code:"2022::86400 MegaEpochTime". + + The second technical form of bold:"Time"\: + + Before Structure\: + code:"". + + Structure\: + code:"\s*:\d+\s*\U*\s*". + + After Structure\: + code:"". + + Example\: + code:"::86400". + code:"::86400 ET". + code:"::86400 EpochTime". + code:"::86400 MET". + code:"::86400 MegaEpochTime". diff --git a/specifications/time.txt b/specifications/time.txt new file mode 100644 index 0000000..71c7f58 --- /dev/null +++ b/specifications/time.txt @@ -0,0 +1,155 @@ +# fss-0002 iki-0000 +# +# license: open-standard-license-1.0 +# +# This file (assumed to be named time.txt) can be more easily read using the following iki_read commands: +# iki_read time.txt +Q -r UTC UTC -w -WW character "'" "'" code '"' '"' +# +# To read the "IKI Specification: 0000 - Unrestricted" section of this file, use this command sequence: +# fss_basic_list_read time.txt +Q -cn "Time Specification" | iki_read +Q -r UTC UTC -w -WW character "'" "'" code '"' '"' +# + +Time Specification: + There are two units of bold:"Time", the first is simply called bold:"Time" and the second is called bold:"EpochTime". + + Both bold:"Time" and bold:"EpochTime" are measured without the year but may contain a year to designate the point in the counting begins. + These are both represented by a single 64-bit (unsigned) integer. + The default timezone is always UTC:"Coordinated Universal Time". + + The common form is intended as the non-technical form that is form common use. + This may have a negative value or be more than 64-bit digits long. + This is simply not expected to be interpreted as a unit of time on a computer (but nothing stops it from being interpreted). + + The technical forms are limit to 64-bit unsigned for technical use but should technology advance to a point where larger bits are needed then this allows for that. + The systems should expect 64-bit and larger bits would have to become common before something larger than 64-bit is the expected or assumed default. + Negative signs can be allowed but they must not prevent the full use of the 64-bit. + The implementation of how this is done is left to the implementer except that the signs are immediately to the left of the digit. + For example code:"2022:-5" would be 5 units after the start of the year 2022. + Because the negative is allowed, so must the positive character (such as code:"2022:+5"). + A positive value is the default interpretation when no sign is valid. + + The unit of time called bold:"Time" is counted increments of a nanosecond, or 10^-9 seconds. + A unit of bold:"Time" is, therefore, equivalent to a nanosecond. + The default year for bold:"Time" is the current year. + + The unit of time called bold:"EpochTime" is counted increments of a second, or 10^-9 seconds. + A unit of bold:"EpochTime" is, therefore, equivalent to a second. + The default year for bold:"EpochTime" is the bold:"UNIX Epoch", sometimes called bold:"Unix time". + + The unit bold:"Time" has two technical forms and one common form, with the year and without the year. + + Key\: + code:"\s" = White space. + code:"\d" = The digits used to represent time (a digit). + code:"*" = Zero or more occurrences. + code:"+" = One or more occurrences. + code:":" = A single colon character:":" (unicode:"U+003A"). + code:'"' = A single double-quote character:'"' (unicode:"U+003A"). + + The common form of bold:"Time"\: + + Before Structure\: + code:"". + + Structure\: + code:"\s*\d+\s*\U*\s*". + + After Structure\: + code:"". + + Example\: + code:"86400". + code:"86400 T". + code:"86400 Time". + + The first technical form of bold:"Time"\: + + Before Structure\: + code:"". + + Structure\: + code:"\s*\d+:\d+\s*\U*\s*". + + After Structure\: + code:"". + + Example\: + code:"2022:86400". + code:"2022:86400 T". + code:"2022:86400 Time". + code:"2022:86400 MT". + code:"2022:86400 MegaTime". + + The second technical form of bold:"Time"\: + + Before Structure\: + code:"". + + Structure\: + code:"\s*:\d+\s*\U*\s*". + + After Structure\: + code:"". + + Example\: + code:":86400". + code:":86400 T". + code:":86400 Time". + code:":86400 MT". + code:":86400 MegaTime". + + The unit bold:"EpochTime" has two technical forms and one common form, with the year and without the year. + + The common form of bold:"Time"\: + + Before Structure\: + code:"". + + Structure\: + code:"\s*\d+\s*\U*\s*". + + After Structure\: + code:"". + + Example\: + code:"86400". + code:"86400 ET". + code:"86400 EpochTime". + code:"86400 MET". + code:"86400 MegaEpochTime". + + The first technical form of bold:"EpochTime"\: + + Before Structure\: + code:"". + + Structure\: + code:"\s*\d+::\d+\s*\U*\s*". + + After Structure\: + code:"". + + Example\: + code:"2022::86400". + code:"2022::86400 ET". + code:"2022::86400 EpochTime". + code:"2022::86400 MET". + code:"2022::86400 MegaEpochTime". + + The second technical form of bold:"Time"\: + + Before Structure\: + code:"". + + Structure\: + code:"\s*:\d+\s*\U*\s*". + + After Structure\: + code:"". + + Example\: + code:"::86400". + code:"::86400 ET". + code:"::86400 EpochTime". + code:"::86400 MET". + code:"::86400 MegaEpochTime". -- 1.8.3.1