a-calc - npm Package Compare versions

Comparing version 2.0.0-dev.20240511 to 2.0.0-dev.20240513

a-calc.versions.js

@@ -41,3 +41,3 @@ try{
   '1.5.0-dev.2024042402',  '1.5.0-dev.2024042404',  '1.5.0-dev.2024042405',
-  '1.5.0-dev.2024042406', '2.0.0-dev.20240511' 
+  '1.5.0-dev.2024042406',  '2.0.0-dev.20240511', '2.0.0-dev.20240513' 
 ]; a_calc_versions;
@@ -44,0 +44,0 @@ }

calc.d.ts

@@ -76,3 +76,4 @@ import { U, StrRemoveSome, If_StrIncludes, Or } from "typescript-treasure";
         _fmt: Fmt,
-        _mode: "space" | "space-all", // space 只会影响表达式部分 space_all 也会影响 fmt 部分
+        _mode: "space" | "space-all" | "normal", // space 只会影响表达式部分 space_all 也会影响 fmt 部分
+        _memo: boolean,
         [Prop: string]: any;
@@ -111,7 +112,18 @@ }>;
 
-export declare const add: (a: number|string, b: number|string) => number;
-export declare const sub: (a: number|string, b: number|string) => number;
-export declare const mul: (a: number|string, b: number|string) => number;
-export declare const div: (a: number|string, b: number|string) => number;
-export declare const pow: (a: number|string, b: number|string) => number;
-export declare const mod: (a: number|string, b: number|string) => number;
+export declare const plus: <T extends "number" | "string" = "number">(a: number|string, b: number|string, type: T) => T extends "number" ? number : string;
+export declare const sub: <T extends "number" | "string" = "number">(a: number|string, b: number|string, type: T) => T extends "number" ? number : string;
+export declare const mul: <T extends "number" | "string" = "number">(a: number|string, b: number|string, type: T) => T extends "number" ? number : string;
+export declare const div: <T extends "number" | "string" = "number">(a: number|string, b: number|string, type: T) => T extends "number" ? number : string;
+export declare const pow: <T extends "number" | "string" = "number">(a: number|string, b: number|string, type: T) => T extends "number" ? number : string;
+export declare const mod: <T extends "number" | "string" = "number">(a: number|string, b: number|string, type: T) => T extends "number" ? number : string;
+
+
+export declare const plus_memo: <T extends "number" | "string" = "number">(a: number|string, b: number|string, type: T) => T extends "number" ? number : string;
+export declare const sub_memo: <T extends "number" | "string" = "number">(a: number|string, b: number|string, type: T) => T extends "number" ? number : string;
+export declare const mul_memo: <T extends "number" | "string" = "number">(a: number|string, b: number|string, type: T) => T extends "number" ? number : string;
+export declare const div_memo: <T extends "number" | "string" = "number">(a: number|string, b: number|string, type: T) => T extends "number" ? number : string;
+export declare const pow_memo: <T extends "number" | "string" = "number">(a: number|string, b: number|string, type: T) => T extends "number" ? number : string;
+export declare const mod_memo: <T extends "number" | "string" = "number">(a: number|string, b: number|string, type: T) => T extends "number" ? number : string;
+
+export declare const clear_memo: (config?: {use_count?: number, maximum?: number}) => void;
+export declare const get_memo_size: () => number;

package.json

 {
     "name": "a-calc",
-    "version": "2.0.0-dev.20240511",
+    "version": "2.0.0-dev.20240513",
     "description": "A very powerful and easy-to-use number precision calculation and formatting library.",
@@ -5,0 +5,0 @@ "main": "./es/index.js",

README.md

@@ -86,12 +86,6 @@ # a-calc
 
-Spaces are not necessary in cases where there is no ambiguity, and it can even correctly parse the hard-to-read-by-human formula `calc("-2e+2+3e+2")`. However, this makes the clarity too low. Please try your best to write clearer code instead of shit! <span style="color: red;">Always include spaces in your calculation, which makes it more beautiful and clear, just like the examples I wrote!!!</span>
+By default, spaces in expressions are not required unless you are using the space or space-all mode. Introductions to these two modes are specifically mentioned in the high performance section. However, I recommend that you always include space in expressions, which looks clearer and more beautiful.
 
-By the way, here's an ambiguous formula `calc("50%%2", {_unit: true})`. This ambiguity obviously occurs in calculations with units. Since the parser doesn't know if your unit is `%` or `%%`, you should use a space to give a clear meaning. The correct way to write is `calc("50% % 2", {_unit: true})`.
-
-In short, always add spaces!
-
 ## Fill in variables and calculate (important)
 
-**The calculated value is precise and scientific notation will not appear.**
-
 ```js
@@ -128,6 +122,7 @@ let a = 0.000001
 calc("1.123$$$ + 2.88% | + =6", {_unit: true}) // "+4.003000$$$"
+
+// Starting from a-calc@2.0.0, the array form of filling data can also be configured. You can use the configuration object as the first or the last parameter of the array. These are the only two positions that are supported.
+calc("a + b", [{a: "1%", b: "2%"}, {_unit: true}]) // "3%"
 ```
 
-After version 1.0.6, calculations with units can have more parameters. The value of `_unit` can be `boolean | "on" | "off" | "auto" | "space"`. The parameters seem to be a lot but actually are similar to the previous usage. The effects of `true "on" "auto"` are the same, which means to automatically recognize the unit after the number. `false "off"` means to turn off the unit calculation. The biggest difference is the "space" value, which only treats the space as a unit separator. For example, if your unit happens to be +-, it will be recognized as an operator in normal mode, so you can use the "space" mode. But in this case, the space is necessary. You should write like this: `calc("2+- * 3")`. The final result is: `6+-`.
-
 In actual development, you may hope that the final result does not automatically carry units. In versions after 1.3.6, you can remove units from the result through the formatting parameter `!u`, or you can directly output the number with `!n`.
@@ -286,11 +281,67 @@
 
+## High performance
 
+This section will teach you how to squeeze every last bit of performance out of a-calc. a-calc 2.x is several times faster than 1.x at its peak performance.
 
+### Memory cache
+
+You can use the _memo parameter to enable calculation caching. In most cases, we will use variables to participate in calculations. If the formulas composed of variables are the same, then the cache will also be used.
+
+```typescript
+calc("a + b", {a：1， b: 2, _memo: true})
+calc("c + d", {c: 8, d: 9, _memo: true})
+// The two calculations above have not optimized a performance point, that is, the formulas are not universal. The same two numbers are added but different formulas are used, a + b and c + d are different formulas. Although this is the same pattern, a-calc will only remember the same formula.
+calc("a * (b - c)", {a: 1, b: 2, c: 3, _memo: true})
+calc("a * (b - c)", {a: 8, b: 2.88, c: 3.8, _memo: true})
+// The above two can fully utilize the ability of formula memory.
+```
+
+**Cache cleanup**
+
+By default, the cache function is turned off. This is because the cache requires you to decide when to clean it up, otherwise it may cause excessive memory usage. a-calc provides you with a cleanup function, you just need to call it at the right time.
+
+```typescript
+import {clear_memo, get_memo_size} from "a-calc"
+
+clear_memo() // By default, a maximum of 5000 cache results are retained. However, if the cache item is used less than 100 times, it will be cleared. Of course, you can also set this yourself.
+clear_memo({maximum: 10000, use_count: 200}) // "maximum" indicates the maximum number of caches retained after cleanup, and "use_count" represents the cleanup of caches with less than this reuse count.
+get_memo_size() // return type: number You can use this method to return the current number of caches, and you can decide whether or not to clear the cache based on this information.
+```
+
+### The space and space-all modes
+
+Both the space and space-all modes can improve a certain level of performance, but these two modes have higher requirements for code writing. The space mode requires strict insertion of spaces between each unit in the calculation part, while the space-all not only requires spaces to be strictly inserted in the calculation part, but also requires spaces to be inserted in the fmt formatting part.
+
+```typescript
+calc("1+1", {_mode: "space"}) // This writing cannot be computed because it lacks spaces.
+calc("1 + 1", {_mode: "space"}) // This is correct
+calc("1 + (2 * 3)", {_mode: "space"}) // This approach is also correct, as special handling has been applied to parentheses. The parentheses can be placed next to the internal numbers or variable names, or they can be separated by spaces.
+
+calc("1 + ( 2 * 3 ) | =2 ,", {_mode: "space-all"}) // After using the space-all mode, spaces are now required between = 2 and ,. There should be at least one space between each formatted unit, and the number of spaces can vary but not be omitted.
+```
+
+### Primitive method
+
+You can also use methods like plus, sub, mul, div to perform calculations. Although a-calc is primarily designed to address the issue of non-intuitive method writing, if you only have two operands and no need for any formatting, using these methods can provide a certain performance improvement.
+
+```typescript
+import {plus, sub, mul, div, mod, pow, idiv, plus_memo, ...} from "a-calc"
+// All of the above methods will have a memo version, which will not be elaborated on.
+plus(1, 1) // 2
+plus(1, 1, "string") // "2"
+```
+
+## 版本变更
+
 ## Version changes
 
-* 1.5.0 
+* 2.0.0 
 
-    - Performance improvement
-    - Expose high performance function methods, for simple arithmetic expressions you can choose to use simple functions to call，for example：`plus("1", "1")`
-    - More robust update detection methods
+    - Destructive change: The \_unit parameter now only supports boolean type, the previous space value has been moved to the \_mode parameter.
+    - Destructive change: Previously, the letter case of some formatted sections could be mixed, but now it must be all lowercase. For example, "!u" cannot be written as "!U".
+    - Significant performance improvement, it is now the fastest among similar libraries.
+    - Expose high-performance function methods, for simple arithmetic expressions you can opt to use straightforward functions for invocation, such as: `plus(1, 1)`
+    - Added the configuration for the \_mode mode.
+    - Now it is also possible to configure when the second parameter is an array.
+    - Exposed primitive methods such as plus, subtract, multiply, divide, modulo, power, integer division and their corresponding memo versions.
 * 1.3.9 Solved the problem of failed rounding due to the part of the injection variable in formatting being 0 (Problem reporter: MangMax)
@@ -297,0 +348,0 @@ * 1.3.8 Solved the packaging failure problem caused by the upgrade of vite5.x (Problem reporter: 武建鹏）

No alert changes

Improved metrics

Total package byte prevSize

240834

increased by6.38%

Lines of code

945

increased by5.12%

Number of lines in readme file

428

increased by13.53%

No dependency changes