Merge pull request #335 from sshanks-kx/refactor

refactor
KxSystems · Nov 8, 2024 · a630bc9 · a630bc9
2 parents 92aa071 + b8fe6ea
commit a630bc9
Show file tree

Hide file tree

Showing 14 changed files with 222 additions and 127 deletions.
diff --git a/docs/basics/cmdline.md b/docs/basics/cmdline.md
@@ -307,7 +307,7 @@ and with `-q`
 Replicate from `:host:port`.
 
 :fontawesome-solid-book-open:
-[`\r` system command](syscmds.md#r-replication-master)
+[`\r` system command](syscmds.md#r-replication-primary)
 
 
 ## `-s` (secondary threads)

diff --git a/docs/basics/comparison.md b/docs/basics/comparison.md
@@ -73,39 +73,102 @@ q)(1 + 1e-13) = 1
 
 ## Temporal values 
 
+Below is a matrix of the [type](datatypes.md) used when the temporal types differ in a comparison (note: you may need to scroll to the right to view the full table):
+
+| comparison types | **timestamp** | **month**       | **date**        | **datetime** | **timespan**    | **minute** | **second** | **time** |
+| ---              | ---           | ---             | ---             | ---          | ---             | ---        | ---        | ---      |
+| **timestamp**    | _timestamp_   | _timestamp_     | _timestamp_     | _timestamp_  | _timespan_      | _minute_   | _second_   | _time_   |
+| **month**        | _timestamp_   | _month_         | _date_          | _not supported_ | _not supported_ | _not supported_ |_not supported_   | _not supported_ |
+| **date**         | _timestamp_   | _date_          | _date_          | _datetime_   | _not supported_ | _not supported_ |_not supported_   | _not supported_ |
+| **datetime**     | _timestamp_   | _not supported_ | _datetime_      | _datetime_   | _timespan_      | _minute_   | _second_   | _time_   |
+| **timespan**     | _timespan_    | _not supported_ | _not supported_ | _timespan_   | _timespan_      | _timespan_ | _timespan_ | _timespan_ |
+| **minute**       | _minute_      | _not supported_ | _not supported_ | _minute_     | _timespan_      | _minute_   | _second_   | _time_   |
+| **second**       | _second_      | _not supported_ | _not supported_ | _second_     | _timespan_      | _second_   | _second_   | _time_   |
+| **time**         | _time_        | _not supported_ | _not supported_ | _time_       | _timespan_      | _time_     | _time_     | _time_   |
+
+For example
+```q
+q)20:00:00.000603286 within 13:30 20:00t            / comparison of timespan and time, time converted to timespan values 0D13:30:00.000000000 0D20:00:00.000000000
+0b
+q)2024.10.07D20:00:00.000603286 within 13:30 20:00t / comparison of timestamp and time, timestamp converted to time value 20:00:00.000
+1b
+```
+
 Particularly notice the comparison of ordinal with cardinal datatypes, such as timestamps with minutes.
 
 ```q
 q)times: 09:15:37 09:29:01 09:29:15 09:29:15 09:30:01 09:35:27
-q)spans:`timespan$times  / timespans:  cardinal
-q)stamps:.z.D+times      / timestamps: ordinal 
-q)t:09:29                / minute:     cardinal
+q)tab:([] timeSpan:`timespan$times; timeStamp:.z.D+times)
+q)meta tab
+c        | t f a
+---------| -----
+timeSpan | n
+timeStamp| p
 ```
 
-When comparing ordinals with cardinals, ordinal is converted to the cardinal type first: `stamps=t` is equivalent to ``(`minute$stamps)=t`` and thus 
+When comparing `timestamp` with `minute`, the timestamps are converted to minutes such that `` `minute$2024.11.01D09:29:15.000000000 `` becomes `09:29` and therefore doesn't appear in the output:
 
 ```q
-q)(stamps<t;stamps=t;stamps>t)
-100000b
+q)select from tab where timeStamp>09:29     / comparing timestamp with minute
+timeSpan             timeStamp
+--------------------------------------------------
+0D09:30:01.000000000 2016.09.06D09:30:01.000000000
+0D09:35:27.000000000 2016.09.06D09:35:27.000000000
+```
+
+When comparing `timespan` with `minute`, the minute is converted to timespan such that `09:29` becomes `0D09:29:00.000000000` for the following comparison:
+
+```q
+q)select from tab where timeSpan>09:29     / comparing timespan with minute
+timeSpan             timeStamp
+--------------------------------------------------
+0D09:29:01.000000000 2016.09.06D09:29:01.000000000
+0D09:29:15.000000000 2016.09.06D09:29:15.000000000
+0D09:29:15.000000000 2016.09.06D09:29:15.000000000
+0D09:30:01.000000000 2016.09.06D09:30:01.000000000
+0D09:35:27.000000000 2016.09.06D09:35:27.000000000
+```
+
+Therefore, when comparing ordinals with cardinals (i.e. timestamp with minute), ordinal is converted to the cardinal type first. 
+
+For example:
+```q
+q)select from tab where timeStamp=09:29
+timeSpan             timeStamp
+--------------------------------------------------
+0D09:29:01.000000000 2016.09.06D09:29:01.000000000
+0D09:29:15.000000000 2016.09.06D09:29:15.000000000
+0D09:29:15.000000000 2016.09.06D09:29:15.000000000
+
+q)tab.timeStamp=09:29
 011100b
-000011b
-q)(spans<t;spans=t;spans>t)
+```
+
+is equivalent to
+
+```q
+q)(`minute$tab.timeStamp)=09:29
+011100b
+```
+and thus
+```q
+q)tab.timeStamp<09:29
 100000b
-000000b
-011111b
+q)tab.timeStamp>09:29
+000011b
 ```
 
-:fontawesome-solid-graduation-cap: 
-[Comparing temporals](../kb/temporal-data.md#comparing-temporals)
-<br>
 :fontawesome-solid-street-view: 
 _Q for Mortals_
 [§4.9.1 Temporal Comparison](/q4m3/4_Operators/#491-temporal-comparison)
 
+## Floating point
+
+The comparison of floating-point types are discussed in [`comparison tolerance`](precision.md#comparison-tolerance).
 
 ## Different types
 
-The comparison operators also work on text values (characters, symbols) – not always intuitively.
+The comparison operators also work on text values (characters, symbols).
 
 ```q
 q)"0" < ("4"; "f"; "F"; 4)  / characters are treated as their numeric value
@@ -141,7 +204,6 @@ q)n < neg inf
 11111b
 ```
 
-
 ## Infinities
 
 Infinities of different type are ordered by their width. 
@@ -178,9 +240,6 @@ Keyword [`differ`](../ref/differ.md) is a uniform unary function that returns a
 [Match](../ref/match.md) (`~`) compares its arguments and returns a boolean atom to say whether they are the same.
 
 
-:fontawesome-solid-book: 
-[Comparison tolerance](precision.md#comparison-tolerance)
-<br>
 :fontawesome-solid-street-view:
 _Q for Mortals_
 [§4.3.3 Order](/q4m3/4_Operators/#433-order)

diff --git a/docs/basics/precision.md b/docs/basics/precision.md
@@ -10,7 +10,7 @@ keywords: comparison, float, precision, tolerance
 
 ## Float precision
 
-Precision of floats is a tricky issue since floats (_doubles_ in other languages) are actually binary rational approximations to real numbers. Whenever you are concerned with precision, set `\P 0` before doing anything else, so that you can see what’s really going on.
+Precision of floats is a complex issue because floats (known as _doubles_ in other programming languages) are actually binary rational approximations of real numbers. If you are concerned with precision, make sure to set [`\P 0`](syscmds.md#p-precision) before proceeding with anything else. This helps you understand what's really happening with your data.
 
 Due to the finite accuracy of the binary representation of floating-point numbers, the last decimal digit of a float is not reliable. This is not peculiar to kdb+.
 
@@ -22,7 +22,7 @@ q)1%3
 
 Efficient algorithms for complex calculations such as log and sine introduce imprecision. Moreover, even basic calculations raise issues of rounding. The IEEE floating-point spec addresses many such issues, but the topic is complex.
 
-Q takes this into account in its implementation of the equality operator `=`, which should actually be read as “tolerantly equal.” Roughly speaking, this means that the difference is relatively small compared to some acceptable representation error. This makes the following hold:
+Q takes this into account in its implementation of the equality operator [`=`](comparison.md), which should actually be read as “tolerantly equal.” Roughly speaking, this means that the difference is relatively small compared to some acceptable representation error. This makes the following hold:
 
 ```q
 q)r7:1%7
@@ -102,7 +102,7 @@ The l64 builds of kdb+ now have a faster SIMD [`sum`](../ref/sum.md) implementat
 
 Consider the task of calculating the sum of `1e-10*til 10000000`.
 
-The SIMD code is equivalent to the following (`\P 0`):
+The SIMD code is equivalent to the following ([`\P 0`](syscmds.md#p-precision)):
 
 ```q
 q){x+y}over{x+y}over 0N 8#1e-10*til 10000000
@@ -280,4 +280,4 @@ These do not use comparison tolerance, and are therefore appropriate for databas
 
 :fontawesome-regular-hand-point-right: 
 [Comparison](comparison.md), 
-[Match](../ref/match.md), [`differ`](../ref/differ.md)
+[Match](../ref/match.md), [`differ`](../ref/differ.md)
diff --git a/docs/basics/syscmds.md b/docs/basics/syscmds.md
@@ -25,7 +25,7 @@ keywords: command, kdb+, q, system
 [\o  offset from UTC](#o-offset-from-utc)                  [\\_       hide q code](#_-hide-q-code)
 [\p  listening port](#p-listening-port)                   [\\        terminate](#terminate)
 [\P  precision](#p-precision)                        [\\        toggle q/k](#toggle-qk)
-[\r  replication master](#r-replication-primary)               [\\\\       quit](#quit)
+[\r  replication primary](#r-replication-primary)              [\\\\       quit](#quit)
 [\r  rename](#r-rename)                                              
 </div>
 

diff --git a/docs/database/mdb-odbc.md b/docs/database/mdb-odbc.md
@@ -6,30 +6,29 @@ date: November 2020
 # :fontawesome-brands-windows: Access a table from an MDB file via ODBC
 
 
+Install the [ODBC client driver for kdb+](../interfaces/q-client-for-odbc.md).
+Install Microsoft ODBC driver for Microsoft Access. 
 
-From Windows, load `odbc.k` into your q session, and then load the MDB file.
+Using the driver installed, a MDB file can be opened using the following example command:
 
-```powershell
-C:>q w32\odbc.k
-```
 
 ```q
-q)h: .odbc.load `mydb.mdb
+q)h:.odbc.open "driver=Microsoft Access Driver (*.mdb, *.accdb);dbq=C:\\mydb.mdb"
 ```
 
-This loads the entire database, which may consist of several tables. Use `.odbc.tables` to list the tables.
+!!! note "The name of the driver may differ between versions. The command above should be altered to reflect the driver name installed."
+
+Use [`.odbc.tables`](../interfaces/q-client-for-odbc.md#tables) to list the tables.
 
 ```q
 q).odbc.tables  h
 `aa`bb`cc`dd`ii`nn
 ```
 
-Use `.odbc.eval` to evaluate SQL commands via ODBC.
+Use [`.odbc.eval`](../interfaces/q-client-for-odbc.md#eval) to evaluate SQL commands via ODBC.
 
 ```q
 q).odbc.eval[h;"select * from aa"]
 ```
 
----
-:fontawesome-solid-handshake:
-[Q driver for ODBC3](../interfaces/q-server-for-odbc3.md)
+An alternative to querying through SQL is to load the entire database into kdb+ via the [.odbc.load](../interfaces/q-client-for-odbc.md#load) command, where the data can then be queried using kdb+ directly.
diff --git a/docs/interfaces/capiref.md b/docs/interfaces/capiref.md
@@ -885,7 +885,7 @@ Increment an object‘s reference count.
 V sd0(I d)
 ```
 
-Remove the callback on `d` and call `kclose`.
+Remove the callback on `d`  and call `kclose`. Should only be called from main thread.
 
 Shared library only.
 
@@ -896,9 +896,9 @@ Shared library only.
 V sd0x(I d, I f)
 ```
 
-Remove the callback on `d` and call `kclose` on `d` if `f` is 1.
+Remove the callback on `d` and call `kclose` on `d` if `f` is 1. Should only be called from main thread.
 
-Shared library only. Since V3.0 2013.04.04.
+Shared library only. Ssince V3.0 2013.04.04.
 
 
 ### `sd1` (set function on loop)
@@ -907,19 +907,21 @@ Shared library only. Since V3.0 2013.04.04.
 K sd1(I d, f)
 ```
 
-Put the function `K f(I d){…}` on the q main event loop given a socket `d`.
+Put the function `K f(I d){…}` on the q main event loop given a socket `d`. Should only be called from main thread.
 
 If `d` is negative, the socket is switched to non-blocking.
 
-The function `f` should return `NULL` or a pointer to a K object, and its reference count will be decremented.
-(It is the return value of `f` that will be `r0`’d – and only if not null.)
+The function `f` should return `NULL` or a pointer to a K object.
+If the return value of `f` is  a pointer to a K object, its reference count is decremented i.e. passed to [`r0`](#r0-decrement-refcount).
 
-Shared library only.
 
-On success, returns int K object containing `d`. On error, `NULL` is returned, `d` is closed.
+On success, `sd1` returns a K object of type integer, containing `d`. On error, `NULL` is returned and `d` is closed.
+
 
 Since 4.1t 2023.09.15, sd1 no longer imposes a limit of 1023 on the value of the descriptor submitted.
 
+Shared library only.
+
 :fontawesome-regular-hand-point-right:
 [Callbacks](c-client-for-q.md#callbacks)