@loradb/lora-node 0.36.0 → 0.36.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/README.md +5 -0
  2. package/docs/README.md +86 -0
  3. package/docs/concepts/graph-model.md +270 -0
  4. package/docs/concepts/nodes.md +285 -0
  5. package/docs/concepts/properties.md +348 -0
  6. package/docs/concepts/relationships.md +325 -0
  7. package/docs/concepts/result-formats.md +183 -0
  8. package/docs/concepts/schema-free.md +183 -0
  9. package/docs/cookbook.md +1081 -0
  10. package/docs/data-types/lists-and-maps.md +406 -0
  11. package/docs/data-types/overview.md +210 -0
  12. package/docs/data-types/scalars.md +376 -0
  13. package/docs/data-types/spatial.md +291 -0
  14. package/docs/data-types/temporal.md +355 -0
  15. package/docs/data-types/vectors.md +563 -0
  16. package/docs/errors.md +183 -0
  17. package/docs/functions/aggregation.md +372 -0
  18. package/docs/functions/list.md +522 -0
  19. package/docs/functions/map.md +207 -0
  20. package/docs/functions/math.md +421 -0
  21. package/docs/functions/number.md +197 -0
  22. package/docs/functions/overview.md +545 -0
  23. package/docs/functions/spatial.md +384 -0
  24. package/docs/functions/string.md +502 -0
  25. package/docs/functions/temporal.md +590 -0
  26. package/docs/functions/utility.md +137 -0
  27. package/docs/functions/vectors.md +772 -0
  28. package/docs/getting-started/installation.md +204 -0
  29. package/docs/getting-started/node.md +582 -0
  30. package/docs/getting-started/tutorial.md +334 -0
  31. package/docs/index.md +203 -0
  32. package/docs/limitations.md +291 -0
  33. package/docs/performance.md +219 -0
  34. package/docs/queries/aggregation.md +520 -0
  35. package/docs/queries/cheat-sheet.md +302 -0
  36. package/docs/queries/constraints.md +239 -0
  37. package/docs/queries/create.md +331 -0
  38. package/docs/queries/examples.md +453 -0
  39. package/docs/queries/index.md +169 -0
  40. package/docs/queries/indexes.md +546 -0
  41. package/docs/queries/match.md +429 -0
  42. package/docs/queries/ordering.md +359 -0
  43. package/docs/queries/parameters.md +328 -0
  44. package/docs/queries/paths.md +462 -0
  45. package/docs/queries/return-with.md +500 -0
  46. package/docs/queries/set-delete.md +369 -0
  47. package/docs/queries/unwind-merge.md +358 -0
  48. package/docs/queries/where.md +416 -0
  49. package/docs/snapshot.md +545 -0
  50. package/docs/troubleshooting.md +1158 -0
  51. package/docs/wal.md +570 -0
  52. package/docs/why.md +273 -0
  53. package/package.json +13 -14
@@ -0,0 +1,197 @@
1
+ ---
2
+ title: "Number Functions"
3
+ description: "Number functions in LoraDB - formatting, radix conversion, Roman numerals, integer and sign predicates, finite-value predicates, and bit helpers."
4
+ online: "https://loradb.com/docs/functions/number"
5
+ package: "@loradb/lora-node@0.36.2"
6
+ ---
7
+
8
+ # Number Functions
9
+
10
+ Number functions cover value-level numeric utilities that are not really
11
+ math formulas: display formatting, base conversion, Roman numeral
12
+ interop, and predicates for validating imported data. For numeric
13
+ formulas, trigonometry, rounding, constants, and random values, use
14
+ [Math Functions](./math.md).
15
+
16
+ Most functions return `null` when an argument is `null`, has the wrong
17
+ type, overflows, or uses an unsupported option. That keeps ingestion
18
+ queries simple: invalid values can be filtered with `IS NOT NULL` or
19
+ replaced with `coalesce`.
20
+
21
+ ## Overview
22
+
23
+ | Goal | Function |
24
+ |---|---|
25
+ | Format for display | `number.format(n[, precision[, thousands]])` |
26
+ | Convert integer to base 2..36 | `number.to_base(n, radix)` |
27
+ | Parse base 2..36 text | `number.from_base(text, radix)` |
28
+ | Roman numeral interop | `number.to_roman(n)`, `number.from_roman(text)` |
29
+ | Integer predicates | `number.is_integer(n)`, `number.is_even(n)`, `number.is_odd(n)` |
30
+ | Sign predicates | `number.is_positive(n)`, `number.is_negative(n)`, `number.is_zero(n)` |
31
+ | Float predicates | `number.is_nan(n)`, `number.is_finite(n)`, `number.is_infinite(n)` |
32
+ | Bit operations | `bits.and`, `bits.or`, `bits.xor`, `bits.not`, `bits.shift_left`, `bits.shift_right` |
33
+
34
+ ## Formatting
35
+
36
+ `number.format(n[, precision[, thousands]])` returns a string. When
37
+ `precision` is provided, the number is rounded to that many decimal
38
+ places. When `thousands` is provided, it is inserted between groups of
39
+ three digits in the integer part.
40
+
41
+ ```cypher
42
+ RETURN number.format(1234); // '1234'
43
+ RETURN number.format(1234.567, 2); // '1234.57'
44
+ RETURN number.format(1234567, 0, ','); // '1,234,567'
45
+ RETURN number.format(-12345.6, 1, '_') // '-12_345.6'
46
+ ```
47
+
48
+ Use `math.round` when the result should remain numeric:
49
+
50
+ ```cypher
51
+ RETURN math.round(1234.567, 2); // 1234.57
52
+ RETURN number.format(1234.567, 2) // '1234.57'
53
+ ```
54
+
55
+ ## Radix Conversion
56
+
57
+ Use `number.to_base(n, radix)` and `number.from_base(text, radix)` for
58
+ integer identifiers, compact codes, imported binary or hexadecimal
59
+ fields, and similar data-shaping jobs. `radix` must be between `2` and
60
+ `36`. Output uses lowercase digits `0-9` and `a-z`.
61
+
62
+ ```cypher
63
+ RETURN number.to_base(255, 16); // 'ff'
64
+ RETURN number.to_base(42, 2); // '101010'
65
+ RETURN number.to_base(-10, 2); // '-1010'
66
+
67
+ RETURN number.from_base('ff', 16); // 255
68
+ RETURN number.from_base('101010', 2); // 42
69
+ RETURN number.from_base('-1010', 2) // -10
70
+ ```
71
+
72
+ Invalid digits, unsupported radix values, and integer overflow return
73
+ `null`:
74
+
75
+ ```cypher
76
+ RETURN number.from_base('ff', 10); // null
77
+ RETURN number.to_base(10, 1) // null
78
+ ```
79
+
80
+ ### Import Hex IDs
81
+
82
+ ```cypher
83
+ UNWIND $rows AS row
84
+ WITH row, number.from_base(row.hex_id, 16) AS id
85
+ WHERE id IS NOT NULL
86
+ MERGE (:ExternalThing {id: id})
87
+ ```
88
+
89
+ ## Roman Numerals
90
+
91
+ `number.to_roman(n)` supports integers from `1` through `3999`.
92
+ `number.from_roman(text)` accepts uppercase or lowercase Roman numerals
93
+ and returns an integer.
94
+
95
+ ```cypher
96
+ RETURN number.to_roman(1994); // 'MCMXCIV'
97
+ RETURN number.from_roman('MCMXCIV'); // 1994
98
+ RETURN number.to_roman(0) // null
99
+ ```
100
+
101
+ Roman parsing is intended for interop and display cleanup, not strict
102
+ historical validation. Prefer storing ordinary integers as properties.
103
+
104
+ ## Predicates
105
+
106
+ `number.is_integer(n)` accepts both `INTEGER` values and finite `FLOAT`
107
+ values with no fractional part. `number.is_even` and `number.is_odd`
108
+ require an `INTEGER`; they return `null` for floats, even when the float
109
+ looks integral. The sign predicates accept both integers and floats.
110
+
111
+ ```cypher
112
+ RETURN number.is_integer(42); // true
113
+ RETURN number.is_integer(42.0); // true
114
+ RETURN number.is_integer(42.5); // false
115
+
116
+ RETURN number.is_even(42); // true
117
+ RETURN number.is_odd(41); // true
118
+ RETURN number.is_even(42.0); // null
119
+
120
+ RETURN number.is_positive(0.1); // true
121
+ RETURN number.is_negative(-1); // true
122
+ RETURN number.is_zero(0.0) // true
123
+ ```
124
+
125
+ The finite-value predicates are mostly useful when a host binding or
126
+ JSON import can produce special floating-point values:
127
+
128
+ ```cypher
129
+ RETURN number.is_finite(1.5); // true
130
+ RETURN number.is_nan($maybe_nan) // true, when a host binding supplies NaN
131
+ ```
132
+
133
+ ## Bit Operations
134
+
135
+ Bit operations live in the `bits.*` namespace because they are integer
136
+ operations over the two's-complement representation, not ordinary
137
+ numeric formulas.
138
+
139
+ ```cypher
140
+ RETURN bits.and(12, 10); // 8
141
+ RETURN bits.or(12, 10); // 14
142
+ RETURN bits.xor(12, 10); // 6
143
+ RETURN bits.not(0); // -1
144
+ RETURN bits.shift_left(3, 2); // 12
145
+ RETURN bits.shift_right(12, 2) // 3
146
+ ```
147
+
148
+ A shift moves 0 to 63 bits; any other amount is an error.
149
+ `bits.shift_left(a, b)` is `a * 2^b`, so like the arithmetic operators
150
+ it raises an error when the result doesn't fit a 64-bit integer, rather
151
+ than wrapping. `bits.shift_right` keeps the sign (`bits.shift_right(-8, 1)`
152
+ is `-4`) and never overflows.
153
+
154
+ ```cypher
155
+ RETURN bits.shift_left(1, 62); // 4611686018427387904
156
+ RETURN bits.shift_left(-1, 63); // -9223372036854775808
157
+ RETURN bits.shift_left(1, 63); // error: overflowed
158
+ RETURN bits.shift_right(1, 64) // error: shift must be between 0 and 63
159
+ ```
160
+
161
+ For new queries, prefer the named `bits.*` helpers over
162
+ `number.bitop(a, op, b)`. The older `number.bitop` form remains
163
+ available for generated queries that need to pass the operation name as
164
+ a string.
165
+
166
+ ```cypher
167
+ RETURN number.bitop(12, 'and', 10) // 8
168
+ ```
169
+
170
+ ## Common Patterns
171
+
172
+ ### Validate Imported Integers
173
+
174
+ ```cypher
175
+ UNWIND $rows AS row
176
+ WITH row, cast.try(row.rank, INTEGER) AS rank
177
+ WHERE number.is_integer(rank) AND number.is_even(rank)
178
+ CREATE (:ImportedRank {rank: rank, source: row.source})
179
+ ```
180
+
181
+ ### Build Stable Short Codes
182
+
183
+ ```cypher
184
+ MATCH (n:Thing)
185
+ RETURN n.id, string.upper(number.to_base(n.id, 36)) AS code
186
+ ORDER BY n.id
187
+ ```
188
+
189
+ ### Keep Numeric And Display Values Separate
190
+
191
+ ```cypher
192
+ MATCH (invoice:Invoice)
193
+ WITH invoice, invoice.total_cents / 100.0 AS total
194
+ RETURN invoice.id,
195
+ total,
196
+ number.format(total, 2, ',') AS display_total
197
+ ```