@graphty/graph-io 0.3.24 → 0.3.26

package/src/common/format.ts

@@ -6,10 +6,13 @@
  * spelling the target syntax accepts.
  */
 
+import type { NodeId } from "@graphty/graph-format";
+
 /**
  * The shortest decimal text that reads back to the same f32 value through Math.fround.
  * @param value - an f32 value (a JS number holding one)
  * @returns the text; "Infinity" / "-Infinity" / "NaN" for the non-finite values, "-0" for negative zero
+ * @category Plugin helpers
  */
 export function formatF32(value: number): string {
     if (!Number.isFinite(value)) {
@@ -27,20 +30,42 @@ export function formatF32(value: number): string {
     return String(value);
 }
 
+/**
+ * Whether a number read from a file keeps its decimal value in an f32 column: the shortest decimal
+ * of its f32 rounding reads back as the same number (0.2 does; 123456789.123 and 0.123456789 do not).
+ * @param value - a finite number
+ * @returns true when nothing a reader would see is lost
+ * @category Plugin helpers
+ */
+export function survivesF32(value: number): boolean {
+    return Number(formatF32(Math.fround(value))) === value;
+}
+
 /**
  * The shortest text of an f64 value: `String(x)`, which is already the shortest round-tripping
  * decimal in JS, except for negative zero, which `String()` writes as "0".
  * @param value - the value
  * @returns the text; "Infinity" / "-Infinity" / "NaN" for the non-finite values, "-0" for negative zero
+ * @category Plugin helpers
  */
 export function formatF64(value: number): string {
     return Object.is(value, -0) ? "-0" : String(value);
 }
 
+/**
+ * The text of a node id for the text formats that write ids bare (DOT, Pajek, XGMML): the string
+ * itself, or the shortest decimal of a number (formatF64).
+ * @param id - the id
+ * @returns the text
+ */
+export function idText(id: NodeId): string {
+    return typeof id === "number" ? formatF64(id) : id;
+}
+
 /**
  * A decimal text with a decimal point or an exponent guaranteed for a finite value (`2.0`,
  * `1e+21`, `1.5e-7`), so an
- * untyped re-import keeps the column f64 rather than i32 (design section 8.5); negative zero is
+ * untyped re-import keeps the column f64 rather than i32; negative zero is
  * written `-0.0` so it reads back as -0; non-finite values are the JS spellings (`Infinity`,
  * `-Infinity`, `NaN`), which the CSV / DOT / Pajek importers read back as text. The one
  * implementation of the "decimal point guaranteed" rule for every text format; GML has its own
@@ -48,6 +73,7 @@ export function formatF64(value: number): string {
  * @param value - the value
  * @param dtype - the column dtype the value comes from; f32 values use the shortest fround-round-trip text
  * @returns the text
+ * @category Plugin helpers
  */
 export function formatDecimal(value: number, dtype: "f32" | "f64" | "i32" | "u32" | "u8" = "f64"): string {
     if (!Number.isFinite(value)) {
@@ -69,6 +95,7 @@ export function formatDecimal(value: number, dtype: "f32" | "f64" | "i32" | "u32
  * @param value - the value
  * @param dtype - the column dtype the value comes from; f32 values use the shortest fround-round-trip text
  * @returns the text
+ * @category Plugin helpers
  */
 export function formatGmlReal(value: number, dtype: "f32" | "f64" | "i32" | "u32" | "u8" = "f64"): string {
     if (Number.isNaN(value)) {
@@ -91,6 +118,7 @@ export function formatGmlReal(value: number, dtype: "f32" | "f64" | "i32" | "u32
  * integer), avoiding the exponent form `String()` uses above 1e21.
  * @param value - an integral value
  * @returns the digits
+ * @category Plugin helpers
  */
 export function formatInteger(value: number): string {
     if (Number.isSafeInteger(value) || !Number.isFinite(value)) {
@@ -105,6 +133,7 @@ export function formatInteger(value: number): string {
  * @param value - the value
  * @param dtype - the column dtype the value came from
  * @returns the text
+ * @category Plugin helpers
  */
 export function formatNumber(value: number, dtype: "f32" | "f64" | "i32" | "u32" | "u8"): string {
     return dtype === "f32" ? formatF32(value) : formatF64(value);

package/src/common/ids.ts

@@ -27,6 +27,7 @@ export { ID_MERGED_CODE };
  * The "canonical" rule on one text cell.
  * @param text - the cell text, exactly as read
  * @returns the number for canonical safe-integer text (never for "-0"), the text itself otherwise
+ * @category Plugin helpers
  */
 export function canonicalId(text: string): NodeId {
     if (text !== "-0" && CANONICAL_INTEGER.test(text)) {
@@ -42,6 +43,7 @@ export function canonicalId(text: string): NodeId {
  * Whether a text cell is canonical integer text under the "canonical" rule (a number after import).
  * @param text - the cell text
  * @returns true when canonicalId(text) returns a number
+ * @category Plugin helpers
  */
 export function isCanonicalIntegerText(text: string): boolean {
     return typeof canonicalId(text) === "number";
@@ -52,6 +54,7 @@ export function isCanonicalIntegerText(text: string): boolean {
  * @param text - the cell text, exactly as read
  * @param mode - the coercion rule
  * @returns the id; E_INVALID_ID when the rule rejects the text
+ * @category Plugin helpers
  */
 export function coerceIdText(text: string, mode: IdCoercion): NodeId {
     switch (mode) {
@@ -82,6 +85,7 @@ export function coerceIdText(text: string, mode: IdCoercion): NodeId {
  * @param value - the value
  * @param mode - the coercion rule
  * @returns the id; E_INVALID_ID when the rule rejects the value
+ * @category Plugin helpers
  */
 export function coerceId(value: unknown, mode: IdCoercion): NodeId {
     if (typeof value === "string") {
@@ -115,8 +119,8 @@ function invalidId(value: unknown, reason: string): GraphFormatError {
 
 /**
  * A stateful coercer for one import call: applies the rule and, under "number", detects merges
- * (two distinct texts mapping to one number) so the importer can report them as coercion issues
- * (design section 4.1).
+ * (two distinct texts mapping to one number) so the importer can report them as coercion issues.
+ * @category Writing a format
  */
 export class IdCoercer {
     /** The rule. */
@@ -129,7 +133,14 @@ export class IdCoercer {
     private readonly firstText: Map<number, string> | null;
 
     /** The merge detected by the most recent text() call, or null. */
-    lastMerge: { readonly id: number; readonly text: string; readonly previousText: string } | null = null;
+    lastMerge: {
+        /** The number both texts became. */
+        readonly id: number;
+        /** The text just read. */
+        readonly text: string;
+        /** The first text that became the same number. */
+        readonly previousText: string;
+    } | null = null;
 
     /**
      * Create a coercer.