edf2csv 0.7.120 → 0.7.122

package/dist/convert/channels.js

@@ -168,7 +168,15 @@ export function selectChannels(signals, terms) {
             const index = Number(position);
             const signal = candidates.find((s) => s.index === index);
             if (!signal) {
-                throw new ChannelSelectionError(`No channel at position ${term}. ${positions}`);
+                /*
+                  The list of positions is advice, and advice goes on the continuation line.
+        
+                  It sat on the first line here and on the second in the refusal six lines up, which
+                  is the same sentence about the same thing. The first line is the one a log gets
+                  grepped for and the one `printableLines` leaves whole at any width, so on a
+                  40-channel recording this refusal ran to 111 columns where its neighbour ran to 74.
+                */
+                throw new ChannelSelectionError(`No channel at position ${term}.\n${positions}`);
             }
             chosen.set(signal.index, signal);
             continue;

package/dist/convert/channels.js.map

@@ -1 +1 @@
-{"version":3,"file":"channels.js","sourceRoot":"","sources":["../../src/convert/channels.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Channel naming and selection.\n *\n * Two real-world facts drive this module. EDF labels are free text that routinely\n * contain spaces and punctuation (\"EEG Fpz-Cz\"), and they are not guaranteed to be\n * unique — CHB-MIT recordings ship two channels both labelled \"T8-P8\", and some\n * carry a channel labelled \"-\". Labels are therefore preserved verbatim in output,\n * and only disambiguated when the file itself is ambiguous.\n */\n\nimport type { EdfSignal } from '../edf/header.js';\nimport { listed } from '../format/list.js';\n\n/**\n * The name of the column the writer puts in front of the channels, which no channel may take.\n *\n * Exported and used by the writer rather than repeated there, because the whole point of\n * reserving it here is that the two cannot drift apart.\n */\nexport const TIME_COLUMN = 'time_s';\n\nexport class ChannelSelectionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'ChannelSelectionError';\n  }\n}\n\n/**\n * Column name for a signal.\n *\n * Names are derived from the whole file, not from the current selection, so a given\n * channel always produces the same column regardless of which channels were asked\n * for. Duplicated labels get a `_ch<index>` suffix pointing at their position in\n * the file, which is the only thing that reliably tells them apart.\n */\nexport function buildColumnNames(signals: readonly EdfSignal[]): Map<number, string> {\n  const counts = new Map<string, number>();\n  for (const signal of signals) {\n    if (signal.isAnnotations) continue;\n    const base = baseName(signal);\n    counts.set(base, (counts.get(base) ?? 0) + 1);\n  }\n\n  const names = new Map<number, string>();\n  for (const signal of signals) {\n    if (signal.isAnnotations) continue;\n    const base = baseName(signal);\n    const duplicated = (counts.get(base) ?? 0) > 1;\n    names.set(signal.index, duplicated ? `${base}_ch${signal.index}` : base);\n  }\n\n  /*\n    The suffix has to be checked against the file, not only against the label it disambiguates.\n\n    Counting collisions on the raw label alone made the suffix a guess: `_ch<index>` is unique\n    among the channels sharing that label, and nothing stopped it from landing on a label some\n    other channel already had. A file labelled T8, T8, T8_ch0 — all three legal, since EDF\n    labels are free text and nothing enforces uniqueness — produced\n\n        time_s,T8_ch0,T8_ch1,T8_ch0\n\n    two columns with one name, while the warning beside it said the suffix kept them\n    \"distinguishable\". channels.csv listed the same name against two signal indices, so the\n    join it exists for could not resolve it either, and `df[\"T8_ch0\"]` in pandas or R returns\n    one of the two with nothing to say which.\n\n    Anything still shared after the first pass takes its own position as well. That is unique\n    by construction, so the loop settles immediately in practice; the bound is there because\n    a second round could in principle land on yet another literal label.\n\n    The time column counts as taken, for the same reason. It is a name this file does not\n    supply and the writer does, and a channel labelled `time_s` collided with it in silence:\n    the header came out `time_s,time_s,ECG`, channels.csv named the channel's column `time_s`,\n    and every read-back the documentation gives — `index_col=\"time_s\"`, `pop(\"time_s\")`,\n    `pivot(index=\"time_s\")` — resolves that to one of the two columns without saying which.\n    pandas and Python's own `csv.DictReader` resolve it opposite ways round.\n  */\n  for (let round = 0; round < 8; round++) {\n    const taken = new Map<string, number>([[TIME_COLUMN, 1]]);\n    for (const name of names.values()) taken.set(name, (taken.get(name) ?? 0) + 1);\n\n    const clashing = [...names].filter(([, name]) => (taken.get(name) ?? 0) > 1);\n    if (clashing.length === 0) break;\n    for (const [index, name] of clashing) names.set(index, `${name}_ch${index}`);\n  }\n  return names;\n}\n\nfunction baseName(signal: EdfSignal): string {\n  return signal.label === '' ? `signal_${signal.index}` : signal.label;\n}\n\n/**\n * Channels whose column name was pushed off their own label to keep the header unique.\n *\n * A channel genuinely labelled `T8_ch0` loses that name when another label's disambiguating\n * suffix wants it, and the resulting column is the one thing in the output that no longer\n * matches the file. Silence there is what made the collision hard to see in the first place:\n * the only warning raised was about the *other* label.\n */\nexport function renamedByCollision(\n  signals: readonly EdfSignal[],\n  columnNames: ReadonlyMap<number, string>,\n): EdfSignal[] {\n  const counts = new Map<string, number>();\n  for (const signal of signals) {\n    if (signal.isAnnotations) continue;\n    const base = baseName(signal);\n    counts.set(base, (counts.get(base) ?? 0) + 1);\n  }\n  return signals.filter(\n    (signal) =>\n      !signal.isAnnotations &&\n      (counts.get(baseName(signal)) ?? 0) === 1 &&\n      columnNames.get(signal.index) !== baseName(signal),\n  );\n}\n\nexport interface ChannelSelection {\n  signals: EdfSignal[];\n  /** Labels that matched more than one channel, so the user knows why they got extras. */\n  ambiguous: { term: string; matched: EdfSignal[] }[];\n}\n\n/**\n * Resolve a `--channels` specification against the file's signals.\n *\n * Matching is case-insensitive on the exact label, with `#<index>` available to\n * address a specific channel when labels collide. A term that matches nothing is an\n * error rather than a silent omission: quietly dropping a requested channel would\n * hand the user a CSV that is missing data they explicitly asked for.\n */\nexport function selectChannels(signals: readonly EdfSignal[], terms: readonly string[]): ChannelSelection {\n  const candidates = signals.filter((s) => !s.isAnnotations);\n  const byLabel = new Map<string, EdfSignal[]>();\n  for (const signal of candidates) {\n    const key = signal.label.toLowerCase();\n    const bucket = byLabel.get(key);\n    if (bucket) bucket.push(signal);\n    else byLabel.set(key, [signal]);\n  }\n\n  const chosen = new Map<number, EdfSignal>();\n  const ambiguous: { term: string; matched: EdfSignal[] }[] = [];\n  /*\n    A file may have no signal channels at all, and both position errors below assumed it had\n    some. `listed([])` is the empty string, so `--channels \"#0\"` on an annotations-only\n    recording — one of this tool's own fixtures — was refused with\n\n        No channel at position #0. This file has signal channels at .\n\n    a sentence that states there are channels and then names none, ending mid-clause. The\n    conversion already raises NO_SIGNAL_CHANNELS for this file and says what it is, so the\n    fact was known one layer up; the message that a `--channels` user actually reaches was\n    the one that did not have it.\n  */\n  const positions =\n    candidates.length === 0\n      ? 'This file has no signal channels; it contains only annotations.'\n      : `This file has signal channels at ${listed(candidates.map((s) => `#${s.index}`))}.`;\n\n  for (const rawTerm of terms) {\n    const term = rawTerm.trim();\n    if (term === '') continue;\n\n    // '#N' addresses a channel by position, but a label may literally be \"#5\".\n    // A real label always wins, so no channel becomes unreachable.\n    const literal = byLabel.get(term.toLowerCase());\n    if (term.startsWith('#') && (!literal || literal.length === 0)) {\n      /*\n        A position must be written in plain digits.\n\n        `Number()` was doing the parsing, and it accepts a great deal more than a position:\n        `#0x2` reached channel 2 through hex, `#0b1` channel 1 through binary, `#1e0` and\n        `#2.0` and `# 2` all landed somewhere, and `#` on its own became `Number('')`, which\n        is 0. Every one of them selected a channel and exited 0, so a slip did not fail —\n        it quietly converted a different channel than the one asked for, which for this tool\n        is the worst way to be wrong.\n      */\n      const position = term.slice(1);\n      if (!/^\\d+$/u.test(position)) {\n        throw new ChannelSelectionError(\n          `\"${term}\" is not a channel position: a position is #0, #1, #2 and so on.\\n` +\n            positions,\n        );\n      }\n      const index = Number(position);\n      const signal = candidates.find((s) => s.index === index);\n      if (!signal) {\n        throw new ChannelSelectionError(\n          `No channel at position ${term}. ${positions}`,\n        );\n      }\n      chosen.set(signal.index, signal);\n      continue;\n    }\n\n    const matched = byLabel.get(term.toLowerCase());\n    if (!matched || matched.length === 0) {\n      /*\n        The one term that is certainly not a typo: a column name.\n\n        Matching is on the label, and where a label collides the column gains a `_ch<index>`\n        suffix — so `T8-P8_ch1` is a name this tool invented, prints in the COLUMN column of\n        --info, writes into channels.csv and puts at the head of signals.csv, and then\n        rejects with \"No channel named \"T8-P8_ch1\". Run with --info to list the channels in\n        this file\", which is where the user copied it from. The reference documents the trap;\n        the message a user actually hits did not.\n\n        Answered where it is asked instead, and with the thing that works: `#<index>` selects\n        one channel of a colliding pair, which is exactly what someone reaching for the\n        suffixed column name wants and the only way to get it.\n      */\n      const columns = buildColumnNames(candidates);\n      const owner = candidates.find(\n        (signal) => (columns.get(signal.index) ?? '').toLowerCase() === term.toLowerCase(),\n      );\n      if (owner) {\n        // A channel with no label at all gets the column `signal_<index>`, and offering its\n        // label back would be offering `\"\"` — there is nothing to type. Position is the only\n        // way to reach it, and saying so is more use than quoting an empty string twice.\n        throw new ChannelSelectionError(\n          owner.label === ''\n            ? `\"${term}\" is a column name, not a channel name: --channels matches the label, ` +\n              `and this channel has none.\\n` +\n              `Use \"#${owner.index}\" — a channel with no label can only be addressed by position.`\n            : `\"${term}\" is a column name, not a channel name: --channels matches the label, ` +\n              `which for this channel is \"${owner.label}\".\\n` +\n              (typeable(owner.label) === null\n                ? `Use \"#${owner.index}\" — ${untypeableBecause(owner.label)}, so position is ` +\n                  `the only way to reach it.`\n                : `Use \"#${owner.index}\" to select just this one, or ${typeable(owner.label)} ` +\n                  `for every channel sharing that label.`),\n        );\n      }\n      /*\n        The annotation channel is a channel, and this said the file had none by that name.\n\n        `EDF Annotations` is a label the file really carries — the spec reserves it, --info\n        counts it on the \"Channels\" line, and it is the name anyone reading about EDF+ meets\n        first. Asking for it got \"No channel named \"EDF Annotations\". Run with --info to list\n        the channels in this file\", which is false about the file and points at a table that\n        does not list it either, so following the advice returns the reader to the same\n        message. What they were after is already being written: every conversion of a file\n        with this channel writes annotations.csv from it.\n      */\n      const asAnnotations = signals.find(\n        (signal) => signal.isAnnotations && signal.label.toLowerCase() === term.toLowerCase(),\n      );\n      if (asAnnotations) {\n        throw new ChannelSelectionError(\n          `\"${term}\" is this recording's annotation channel, not a signal: it holds event ` +\n            `text rather than samples, so it has no column to select.\\n` +\n            `Its events are already written to annotations.csv by any conversion of this ` +\n            `file — pass --annotations-only for those and no signal data.`,\n        );\n      }\n      throw new ChannelSelectionError(\n        `No channel named \"${term}\".${suggest(term, candidates)}\\n` +\n          `Run with --info to list the channels in this file.`,\n      );\n    }\n    if (matched.length > 1) ambiguous.push({ term, matched: [...matched] });\n    for (const signal of matched) chosen.set(signal.index, signal);\n  }\n\n  const selected = [...chosen.values()].sort((a, b) => a.index - b.index);\n  if (selected.length === 0) {\n    throw new ChannelSelectionError('No channels were selected.');\n  }\n  return { signals: selected, ambiguous };\n}\n\nfunction suggest(term: string, candidates: readonly EdfSignal[]): string {\n  // Duplicated labels would otherwise be suggested twice, which reads like two\n  // different options while naming the same thing.\n  const unique = [...new Set(candidates.map((s) => s.label))];\n  const scored = unique\n    .map((label) => ({ label, distance: editDistance(term.toLowerCase(), label.toLowerCase()) }))\n    .filter((c) => c.label !== '' && c.distance <= Math.max(2, Math.floor(term.length / 3)))\n    .sort((a, b) => a.distance - b.distance);\n  if (scored.length === 0) return '';\n  /*\n    A suggestion is something to retype, so it has to be retypeable.\n\n    `Did you mean \"EEG \"A1\"\"?` collapses in a shell to `EEG A1`, which this then rejects with\n    the same sentence and the same suggestion — a loop the reader cannot get out of by doing\n    what it says. Same failure the header parser's `--channels` advice was fixed for in\n    0.7.18, and the branch above it here; a label carrying `$` or a backtick is the same thing\n    again, since a shell expands both inside double quotes.\n\n    Where nothing can be typed — a label with a comma, which --channels splits after the shell\n    has finished with it, or one with a control byte in it — the position is offered instead.\n    It is not the name they asked about, but it is the answer to what they wanted.\n  */\n  /*\n    Cut to three, and the rest counted rather than dropped.\n\n    `.slice(0, 3)` said nothing about what it left. On a recording with channels ECG1 to ECG5,\n    `--channels ECG` is one edit from all five and the answer was `Did you mean \"ECG1\", \"ECG2\",\n    \"ECG3\"?` — three of five equally good answers, with nothing to say the list was cut. A\n    reader has no way to tell ECG4 from a channel that does not exist, and this sentence is the\n    only place the tool offers to tell them what does.\n\n    Through `listed`, which every other list in a sentence goes through: it counts what it\n    leaves, and shows a fourth item rather than hiding it behind a phrase longer than the item.\n  */\n  const offered = scored.map((c) => typeable(c.label) ?? `\"#${positionOf(c.label, candidates)}\"`);\n  return ` Did you mean ${listed(offered, 3)}?`;\n}\n\n/** The first channel carrying this label, for a suggestion that cannot be made by name. */\nfunction positionOf(label: string, candidates: readonly EdfSignal[]): number {\n  return candidates.find((signal) => signal.label === label)?.index ?? 0;\n}\n\n/**\n * The label written so that typing it back selects this channel, or null when nothing does.\n *\n * Double quotes wherever they survive, since they also show where the label begins and ends\n * and every documented example is written that way. They do not survive a label containing a\n * quote of their own, and — less obviously — a shell still expands `$`, a backtick and a\n * backslash inside them, so `EEG $ref` would arrive as `EEG ` with nothing said. Those go in\n * single quotes, the one POSIX form with no escapes inside it, where a single quote in the\n * label closes, escapes and reopens.\n *\n * Two labels have no form at all. `--channels` splits its list on commas after the shell has\n * finished quoting, so no quoting reaches a label with one in it; and a control character\n * cannot be typed. Both take a position instead, which is what NONPRINTABLE_LABEL already\n * says for the same two reasons.\n */\nexport function typeable(label: string): string | null {\n  if (label === '' || label.includes(',')) return null;\n  if (/[\\u0000-\\u001f\\u007f-\\u009f]/u.test(label)) return null;\n  if (!/[\"$`\\\\]/u.test(label)) return `\"${label}\"`;\n  return `'${label.replaceAll(\"'\", \"'\\\\''\")}'`;\n}\n\n/** Why a label has no typeable form, for the sentence that offers a position instead. */\nfunction untypeableBecause(label: string): string {\n  if (label.includes(',')) return 'a comma in the label would read as two names';\n  return 'the label cannot be typed';\n}\n\n/** Levenshtein distance, two-row variant. */\nfunction editDistance(a: string, b: string): number {\n  if (a === b) return 0;\n  if (a.length === 0) return b.length;\n  if (b.length === 0) return a.length;\n\n  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);\n  let current = new Array<number>(b.length + 1).fill(0);\n\n  for (let i = 1; i <= a.length; i++) {\n    current[0] = i;\n    for (let j = 1; j <= b.length; j++) {\n      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;\n      current[j] = Math.min(\n        (current[j - 1] ?? 0) + 1,\n        (previous[j] ?? 0) + 1,\n        (previous[j - 1] ?? 0) + cost,\n      );\n    }\n    const swap = previous;\n    previous = current;\n    current = swap;\n  }\n  return previous[b.length] ?? 0;\n}\n"]}
+{"version":3,"file":"channels.js","sourceRoot":"","sources":["../../src/convert/channels.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Channel naming and selection.\n *\n * Two real-world facts drive this module. EDF labels are free text that routinely\n * contain spaces and punctuation (\"EEG Fpz-Cz\"), and they are not guaranteed to be\n * unique — CHB-MIT recordings ship two channels both labelled \"T8-P8\", and some\n * carry a channel labelled \"-\". Labels are therefore preserved verbatim in output,\n * and only disambiguated when the file itself is ambiguous.\n */\n\nimport type { EdfSignal } from '../edf/header.js';\nimport { listed } from '../format/list.js';\n\n/**\n * The name of the column the writer puts in front of the channels, which no channel may take.\n *\n * Exported and used by the writer rather than repeated there, because the whole point of\n * reserving it here is that the two cannot drift apart.\n */\nexport const TIME_COLUMN = 'time_s';\n\nexport class ChannelSelectionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'ChannelSelectionError';\n  }\n}\n\n/**\n * Column name for a signal.\n *\n * Names are derived from the whole file, not from the current selection, so a given\n * channel always produces the same column regardless of which channels were asked\n * for. Duplicated labels get a `_ch<index>` suffix pointing at their position in\n * the file, which is the only thing that reliably tells them apart.\n */\nexport function buildColumnNames(signals: readonly EdfSignal[]): Map<number, string> {\n  const counts = new Map<string, number>();\n  for (const signal of signals) {\n    if (signal.isAnnotations) continue;\n    const base = baseName(signal);\n    counts.set(base, (counts.get(base) ?? 0) + 1);\n  }\n\n  const names = new Map<number, string>();\n  for (const signal of signals) {\n    if (signal.isAnnotations) continue;\n    const base = baseName(signal);\n    const duplicated = (counts.get(base) ?? 0) > 1;\n    names.set(signal.index, duplicated ? `${base}_ch${signal.index}` : base);\n  }\n\n  /*\n    The suffix has to be checked against the file, not only against the label it disambiguates.\n\n    Counting collisions on the raw label alone made the suffix a guess: `_ch<index>` is unique\n    among the channels sharing that label, and nothing stopped it from landing on a label some\n    other channel already had. A file labelled T8, T8, T8_ch0 — all three legal, since EDF\n    labels are free text and nothing enforces uniqueness — produced\n\n        time_s,T8_ch0,T8_ch1,T8_ch0\n\n    two columns with one name, while the warning beside it said the suffix kept them\n    \"distinguishable\". channels.csv listed the same name against two signal indices, so the\n    join it exists for could not resolve it either, and `df[\"T8_ch0\"]` in pandas or R returns\n    one of the two with nothing to say which.\n\n    Anything still shared after the first pass takes its own position as well. That is unique\n    by construction, so the loop settles immediately in practice; the bound is there because\n    a second round could in principle land on yet another literal label.\n\n    The time column counts as taken, for the same reason. It is a name this file does not\n    supply and the writer does, and a channel labelled `time_s` collided with it in silence:\n    the header came out `time_s,time_s,ECG`, channels.csv named the channel's column `time_s`,\n    and every read-back the documentation gives — `index_col=\"time_s\"`, `pop(\"time_s\")`,\n    `pivot(index=\"time_s\")` — resolves that to one of the two columns without saying which.\n    pandas and Python's own `csv.DictReader` resolve it opposite ways round.\n  */\n  for (let round = 0; round < 8; round++) {\n    const taken = new Map<string, number>([[TIME_COLUMN, 1]]);\n    for (const name of names.values()) taken.set(name, (taken.get(name) ?? 0) + 1);\n\n    const clashing = [...names].filter(([, name]) => (taken.get(name) ?? 0) > 1);\n    if (clashing.length === 0) break;\n    for (const [index, name] of clashing) names.set(index, `${name}_ch${index}`);\n  }\n  return names;\n}\n\nfunction baseName(signal: EdfSignal): string {\n  return signal.label === '' ? `signal_${signal.index}` : signal.label;\n}\n\n/**\n * Channels whose column name was pushed off their own label to keep the header unique.\n *\n * A channel genuinely labelled `T8_ch0` loses that name when another label's disambiguating\n * suffix wants it, and the resulting column is the one thing in the output that no longer\n * matches the file. Silence there is what made the collision hard to see in the first place:\n * the only warning raised was about the *other* label.\n */\nexport function renamedByCollision(\n  signals: readonly EdfSignal[],\n  columnNames: ReadonlyMap<number, string>,\n): EdfSignal[] {\n  const counts = new Map<string, number>();\n  for (const signal of signals) {\n    if (signal.isAnnotations) continue;\n    const base = baseName(signal);\n    counts.set(base, (counts.get(base) ?? 0) + 1);\n  }\n  return signals.filter(\n    (signal) =>\n      !signal.isAnnotations &&\n      (counts.get(baseName(signal)) ?? 0) === 1 &&\n      columnNames.get(signal.index) !== baseName(signal),\n  );\n}\n\nexport interface ChannelSelection {\n  signals: EdfSignal[];\n  /** Labels that matched more than one channel, so the user knows why they got extras. */\n  ambiguous: { term: string; matched: EdfSignal[] }[];\n}\n\n/**\n * Resolve a `--channels` specification against the file's signals.\n *\n * Matching is case-insensitive on the exact label, with `#<index>` available to\n * address a specific channel when labels collide. A term that matches nothing is an\n * error rather than a silent omission: quietly dropping a requested channel would\n * hand the user a CSV that is missing data they explicitly asked for.\n */\nexport function selectChannels(signals: readonly EdfSignal[], terms: readonly string[]): ChannelSelection {\n  const candidates = signals.filter((s) => !s.isAnnotations);\n  const byLabel = new Map<string, EdfSignal[]>();\n  for (const signal of candidates) {\n    const key = signal.label.toLowerCase();\n    const bucket = byLabel.get(key);\n    if (bucket) bucket.push(signal);\n    else byLabel.set(key, [signal]);\n  }\n\n  const chosen = new Map<number, EdfSignal>();\n  const ambiguous: { term: string; matched: EdfSignal[] }[] = [];\n  /*\n    A file may have no signal channels at all, and both position errors below assumed it had\n    some. `listed([])` is the empty string, so `--channels \"#0\"` on an annotations-only\n    recording — one of this tool's own fixtures — was refused with\n\n        No channel at position #0. This file has signal channels at .\n\n    a sentence that states there are channels and then names none, ending mid-clause. The\n    conversion already raises NO_SIGNAL_CHANNELS for this file and says what it is, so the\n    fact was known one layer up; the message that a `--channels` user actually reaches was\n    the one that did not have it.\n  */\n  const positions =\n    candidates.length === 0\n      ? 'This file has no signal channels; it contains only annotations.'\n      : `This file has signal channels at ${listed(candidates.map((s) => `#${s.index}`))}.`;\n\n  for (const rawTerm of terms) {\n    const term = rawTerm.trim();\n    if (term === '') continue;\n\n    // '#N' addresses a channel by position, but a label may literally be \"#5\".\n    // A real label always wins, so no channel becomes unreachable.\n    const literal = byLabel.get(term.toLowerCase());\n    if (term.startsWith('#') && (!literal || literal.length === 0)) {\n      /*\n        A position must be written in plain digits.\n\n        `Number()` was doing the parsing, and it accepts a great deal more than a position:\n        `#0x2` reached channel 2 through hex, `#0b1` channel 1 through binary, `#1e0` and\n        `#2.0` and `# 2` all landed somewhere, and `#` on its own became `Number('')`, which\n        is 0. Every one of them selected a channel and exited 0, so a slip did not fail —\n        it quietly converted a different channel than the one asked for, which for this tool\n        is the worst way to be wrong.\n      */\n      const position = term.slice(1);\n      if (!/^\\d+$/u.test(position)) {\n        throw new ChannelSelectionError(\n          `\"${term}\" is not a channel position: a position is #0, #1, #2 and so on.\\n` +\n            positions,\n        );\n      }\n      const index = Number(position);\n      const signal = candidates.find((s) => s.index === index);\n      if (!signal) {\n        /*\n          The list of positions is advice, and advice goes on the continuation line.\n\n          It sat on the first line here and on the second in the refusal six lines up, which\n          is the same sentence about the same thing. The first line is the one a log gets\n          grepped for and the one `printableLines` leaves whole at any width, so on a\n          40-channel recording this refusal ran to 111 columns where its neighbour ran to 74.\n        */\n        throw new ChannelSelectionError(\n          `No channel at position ${term}.\\n${positions}`,\n        );\n      }\n      chosen.set(signal.index, signal);\n      continue;\n    }\n\n    const matched = byLabel.get(term.toLowerCase());\n    if (!matched || matched.length === 0) {\n      /*\n        The one term that is certainly not a typo: a column name.\n\n        Matching is on the label, and where a label collides the column gains a `_ch<index>`\n        suffix — so `T8-P8_ch1` is a name this tool invented, prints in the COLUMN column of\n        --info, writes into channels.csv and puts at the head of signals.csv, and then\n        rejects with \"No channel named \"T8-P8_ch1\". Run with --info to list the channels in\n        this file\", which is where the user copied it from. The reference documents the trap;\n        the message a user actually hits did not.\n\n        Answered where it is asked instead, and with the thing that works: `#<index>` selects\n        one channel of a colliding pair, which is exactly what someone reaching for the\n        suffixed column name wants and the only way to get it.\n      */\n      const columns = buildColumnNames(candidates);\n      const owner = candidates.find(\n        (signal) => (columns.get(signal.index) ?? '').toLowerCase() === term.toLowerCase(),\n      );\n      if (owner) {\n        // A channel with no label at all gets the column `signal_<index>`, and offering its\n        // label back would be offering `\"\"` — there is nothing to type. Position is the only\n        // way to reach it, and saying so is more use than quoting an empty string twice.\n        throw new ChannelSelectionError(\n          owner.label === ''\n            ? `\"${term}\" is a column name, not a channel name: --channels matches the label, ` +\n              `and this channel has none.\\n` +\n              `Use \"#${owner.index}\" — a channel with no label can only be addressed by position.`\n            : `\"${term}\" is a column name, not a channel name: --channels matches the label, ` +\n              `which for this channel is \"${owner.label}\".\\n` +\n              (typeable(owner.label) === null\n                ? `Use \"#${owner.index}\" — ${untypeableBecause(owner.label)}, so position is ` +\n                  `the only way to reach it.`\n                : `Use \"#${owner.index}\" to select just this one, or ${typeable(owner.label)} ` +\n                  `for every channel sharing that label.`),\n        );\n      }\n      /*\n        The annotation channel is a channel, and this said the file had none by that name.\n\n        `EDF Annotations` is a label the file really carries — the spec reserves it, --info\n        counts it on the \"Channels\" line, and it is the name anyone reading about EDF+ meets\n        first. Asking for it got \"No channel named \"EDF Annotations\". Run with --info to list\n        the channels in this file\", which is false about the file and points at a table that\n        does not list it either, so following the advice returns the reader to the same\n        message. What they were after is already being written: every conversion of a file\n        with this channel writes annotations.csv from it.\n      */\n      const asAnnotations = signals.find(\n        (signal) => signal.isAnnotations && signal.label.toLowerCase() === term.toLowerCase(),\n      );\n      if (asAnnotations) {\n        throw new ChannelSelectionError(\n          `\"${term}\" is this recording's annotation channel, not a signal: it holds event ` +\n            `text rather than samples, so it has no column to select.\\n` +\n            `Its events are already written to annotations.csv by any conversion of this ` +\n            `file — pass --annotations-only for those and no signal data.`,\n        );\n      }\n      throw new ChannelSelectionError(\n        `No channel named \"${term}\".${suggest(term, candidates)}\\n` +\n          `Run with --info to list the channels in this file.`,\n      );\n    }\n    if (matched.length > 1) ambiguous.push({ term, matched: [...matched] });\n    for (const signal of matched) chosen.set(signal.index, signal);\n  }\n\n  const selected = [...chosen.values()].sort((a, b) => a.index - b.index);\n  if (selected.length === 0) {\n    throw new ChannelSelectionError('No channels were selected.');\n  }\n  return { signals: selected, ambiguous };\n}\n\nfunction suggest(term: string, candidates: readonly EdfSignal[]): string {\n  // Duplicated labels would otherwise be suggested twice, which reads like two\n  // different options while naming the same thing.\n  const unique = [...new Set(candidates.map((s) => s.label))];\n  const scored = unique\n    .map((label) => ({ label, distance: editDistance(term.toLowerCase(), label.toLowerCase()) }))\n    .filter((c) => c.label !== '' && c.distance <= Math.max(2, Math.floor(term.length / 3)))\n    .sort((a, b) => a.distance - b.distance);\n  if (scored.length === 0) return '';\n  /*\n    A suggestion is something to retype, so it has to be retypeable.\n\n    `Did you mean \"EEG \"A1\"\"?` collapses in a shell to `EEG A1`, which this then rejects with\n    the same sentence and the same suggestion — a loop the reader cannot get out of by doing\n    what it says. Same failure the header parser's `--channels` advice was fixed for in\n    0.7.18, and the branch above it here; a label carrying `$` or a backtick is the same thing\n    again, since a shell expands both inside double quotes.\n\n    Where nothing can be typed — a label with a comma, which --channels splits after the shell\n    has finished with it, or one with a control byte in it — the position is offered instead.\n    It is not the name they asked about, but it is the answer to what they wanted.\n  */\n  /*\n    Cut to three, and the rest counted rather than dropped.\n\n    `.slice(0, 3)` said nothing about what it left. On a recording with channels ECG1 to ECG5,\n    `--channels ECG` is one edit from all five and the answer was `Did you mean \"ECG1\", \"ECG2\",\n    \"ECG3\"?` — three of five equally good answers, with nothing to say the list was cut. A\n    reader has no way to tell ECG4 from a channel that does not exist, and this sentence is the\n    only place the tool offers to tell them what does.\n\n    Through `listed`, which every other list in a sentence goes through: it counts what it\n    leaves, and shows a fourth item rather than hiding it behind a phrase longer than the item.\n  */\n  const offered = scored.map((c) => typeable(c.label) ?? `\"#${positionOf(c.label, candidates)}\"`);\n  return ` Did you mean ${listed(offered, 3)}?`;\n}\n\n/** The first channel carrying this label, for a suggestion that cannot be made by name. */\nfunction positionOf(label: string, candidates: readonly EdfSignal[]): number {\n  return candidates.find((signal) => signal.label === label)?.index ?? 0;\n}\n\n/**\n * The label written so that typing it back selects this channel, or null when nothing does.\n *\n * Double quotes wherever they survive, since they also show where the label begins and ends\n * and every documented example is written that way. They do not survive a label containing a\n * quote of their own, and — less obviously — a shell still expands `$`, a backtick and a\n * backslash inside them, so `EEG $ref` would arrive as `EEG ` with nothing said. Those go in\n * single quotes, the one POSIX form with no escapes inside it, where a single quote in the\n * label closes, escapes and reopens.\n *\n * Two labels have no form at all. `--channels` splits its list on commas after the shell has\n * finished quoting, so no quoting reaches a label with one in it; and a control character\n * cannot be typed. Both take a position instead, which is what NONPRINTABLE_LABEL already\n * says for the same two reasons.\n */\nexport function typeable(label: string): string | null {\n  if (label === '' || label.includes(',')) return null;\n  if (/[\\u0000-\\u001f\\u007f-\\u009f]/u.test(label)) return null;\n  if (!/[\"$`\\\\]/u.test(label)) return `\"${label}\"`;\n  return `'${label.replaceAll(\"'\", \"'\\\\''\")}'`;\n}\n\n/** Why a label has no typeable form, for the sentence that offers a position instead. */\nfunction untypeableBecause(label: string): string {\n  if (label.includes(',')) return 'a comma in the label would read as two names';\n  return 'the label cannot be typed';\n}\n\n/** Levenshtein distance, two-row variant. */\nfunction editDistance(a: string, b: string): number {\n  if (a === b) return 0;\n  if (a.length === 0) return b.length;\n  if (b.length === 0) return a.length;\n\n  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);\n  let current = new Array<number>(b.length + 1).fill(0);\n\n  for (let i = 1; i <= a.length; i++) {\n    current[0] = i;\n    for (let j = 1; j <= b.length; j++) {\n      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;\n      current[j] = Math.min(\n        (current[j - 1] ?? 0) + 1,\n        (previous[j] ?? 0) + 1,\n        (previous[j - 1] ?? 0) + cost,\n      );\n    }\n    const swap = previous;\n    previous = current;\n    current = swap;\n  }\n  return previous[b.length] ?? 0;\n}\n"]}

package/dist/convert/time-range.js

@@ -76,6 +76,23 @@ export function parseTimeSpec(input, optionName, allowNegative = false) {
     */
     const negative = trimmed.startsWith('-');
     const text = negative ? trimmed.slice(1) : trimmed;
+    /*
+      A leading plus, named as such.
+  
+      Refusing it is deliberate — see the paragraph above — but it came back as "is not a time I
+      understand. Try 30s, 5m, 1h30m, 00:30:00, or a plain number of seconds", which is the
+      message for input that could not be read at all. Every part of `+5s` was read: the number
+      parsed, the unit was looked up and found. The one thing wrong with it is a character the
+      reader put there on purpose, and they were sent to re-check their unit spellings with `5m`
+      sitting in the list of suggestions, differing from what they typed by the sign they cannot
+      see is the problem. 0.7.102 made this argument about a space; this is the same sentence
+      about the other character that reaches it. `--decimals` and `--jobs` both quote the value
+      back and say what is wrong with it.
+    */
+    if (text.startsWith('+')) {
+        throw new TimeRangeError(`${optionName} "${input}" begins with a plus. Write the number on its own: ` +
+            `${input.trim().replace('+', '')}`);
+    }
     const signed = (seconds) => assertFinite(negative ? -seconds : seconds, optionName, input, allowNegative);
     // Bare number means seconds.
     if (/^\d+(?:\.\d+)?$/u.test(text))

package/dist/convert/time-range.js.map

@@ -1 +1 @@
-{"version":3,"file":"time-range.js","sourceRoot":"","sources":["../../src/convert/time-range.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Parsing for the time-range options.\n *\n * Researchers write offsets in whatever form is natural for the recording in front\n * of them: seconds for a short ECG strip, `30m` into a sleep study, `01:23:45` when\n * reading off a clock. All three are accepted; anything ambiguous is rejected with\n * a message that shows the forms that work.\n */\n\nimport { fixed, formatDuration } from '../format/number.js';\n\nexport class TimeRangeError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'TimeRangeError';\n  }\n}\n\n/**\n * Every spelling of a unit this accepts, and what one of it is worth in seconds.\n *\n * Exported so the spellings can be enumerated by a test rather than listed a second time:\n * twelve of these sixteen are named nowhere in the tool or its documentation, and none of\n * their values was checked by anything. `hrs: 360` would have converted `--start 2hrs` from\n * twelve minutes in and said nothing, which is the one kind of mistake a window may not make.\n */\nexport const UNIT_SECONDS: Record<string, number> = {\n  h: 3600,\n  hr: 3600,\n  hrs: 3600,\n  hour: 3600,\n  hours: 3600,\n  m: 60,\n  min: 60,\n  mins: 60,\n  minute: 60,\n  minutes: 60,\n  s: 1,\n  sec: 1,\n  secs: 1,\n  second: 1,\n  seconds: 1,\n  ms: 0.001,\n};\n\nconst CLOCK = /^(?:(\\d+):)?(\\d{1,2}):(\\d{1,2}(?:\\.\\d+)?)$/u;\nconst UNIT_TOKEN = /(\\d+(?:\\.\\d+)?)\\s*([a-z]+)/giu;\n\n/**\n * Parse a duration or offset into seconds.\n *\n * Accepted: `90`, `90s`, `5m`, `1h30m`, `1h 30m 15s`, `00:30:00`, `30:00`, `250ms`.\n *\n * `allowNegative` is for the two options that name a position rather than a length.\n *\n * A recording is timed from its first record's timekeeping annotation, and nothing obliges that\n * to sit at or after zero: a file whose records run from -100 s to -97 s is one this tool reads,\n * times from -100, and describes with\n *\n *     Timed from -100.000s  (first sample; --start and --end use this clock)\n *\n * That line says the number can be typed straight back in, and it could not be. Every offset\n * such a recording has came back as \"not a time I understand\", so its whole clock was\n * unreachable and no window of it could be converted at all — the one file shape where a\n * window is refused for naming a moment the recording actually contains.\n *\n * A length below zero is still a different thing, and `--duration` still refuses one.\n */\nexport function parseTimeSpec(input: string, optionName: string, allowNegative = false): number {\n  const trimmed = input.trim().toLowerCase();\n  if (trimmed === '') {\n    throw new TimeRangeError(`${optionName} is empty. Try a value like 30s, 5m, or 00:30:00.`);\n  }\n\n  /*\n    The sign is read off the front and applied to the whole value, so `-1h30m` is an hour and a\n    half before the origin rather than an hour before it and half an hour after.\n\n    Nothing may sit between the sign and the number, and a leading `+` is still refused: every\n    other number this tool takes is refused when written in a form nobody types, and `+5` is\n    exactly what `--decimals` and `--jobs` reject one flag over.\n  */\n  const negative = trimmed.startsWith('-');\n  const text = negative ? trimmed.slice(1) : trimmed;\n  const signed = (seconds: number): number =>\n    assertFinite(negative ? -seconds : seconds, optionName, input, allowNegative);\n\n  // Bare number means seconds.\n  if (/^\\d+(?:\\.\\d+)?$/u.test(text)) return signed(Number(text));\n\n  // Clock form: hh:mm:ss or mm:ss.\n  const clock = CLOCK.exec(text);\n  if (clock) {\n    const hours = clock[1] === undefined ? 0 : Number(clock[1]);\n    const minutes = Number(clock[2]);\n    const seconds = Number(clock[3]);\n    if (minutes >= 60 || seconds >= 60) {\n      throw new TimeRangeError(\n        `${optionName} \"${input}\" has a minutes or seconds field of 60 or more.`,\n      );\n    }\n    return signed(hours * 3600 + minutes * 60 + seconds);\n  }\n\n  // Unit form: 1h30m, 1h30m 15s, 250ms. A number sits directly against its unit; see below.\n  UNIT_TOKEN.lastIndex = 0;\n  let total = 0;\n  let matched = 0;\n  let consumed = 0;\n  /** Whether any token had a space between its number and its unit. See the refusal below. */\n  let spaced = false;\n  let match: RegExpExecArray | null;\n  // Which units have already been seen, so a repeat can be rejected rather than added.\n  const seen = new Set<number>();\n  while ((match = UNIT_TOKEN.exec(text)) !== null) {\n    const amount = Number(match[1]);\n    const unit = match[2] ?? '';\n    const scale = UNIT_SECONDS[unit];\n    if (scale === undefined) {\n      throw new TimeRangeError(\n        `${optionName} \"${input}\" uses an unknown unit \"${unit}\". Use h, m, s or ms, ` +\n          `or their long forms: hours, minutes, seconds.`,\n      );\n    }\n\n    // \"1h1h\" is a typo, not a request for two hours. Summing repeated units silently\n    // turned a slip into a plausible window that was quietly the wrong length. Units are\n    // keyed by their scale so the aliases collapse together: \"1h30min20m\" is caught too.\n    if (seen.has(scale)) {\n      throw new TimeRangeError(\n        `${optionName} \"${input}\" gives the same unit twice. ` +\n          `Combine each unit once, as in 1h30m.`,\n      );\n    }\n    seen.add(scale);\n\n    total += amount * scale;\n    matched++;\n    // Counted with the whitespace taken out, so the comparison below is against the same\n    // string on both sides and a space inside a token reaches the refusal written for it\n    // rather than the one about input that could not be read at all.\n    consumed += match[0].replace(/\\s+/gu, '').length;\n    if (/\\s/u.test(match[0])) spaced = true;\n  }\n\n  // Reject partially-understood input like \"5x\" or \"1h banana\".\n  if (matched === 0 || consumed !== text.replace(/\\s+/gu, '').length) {\n    throw new TimeRangeError(\n      `${optionName} \"${input}\" is not a time I understand. ` +\n        `Try 30s, 5m, 1h30m, 00:30:00, or a plain number of seconds.`,\n    );\n  }\n\n  /*\n    A space between a number and its unit, named as such.\n\n    `5 min` is refused on purpose — cli-reference sets the rule out, and it is what keeps\n    `1 2h` from being read as anything — but it came back as \"is not a time I understand. Try\n    30s, 5m, 1h30m, 00:30:00, or a plain number of seconds\", which is the message for input\n    that could not be read at all. Every part of `5 min` was read: the number parsed, the unit\n    was looked up in the table and found. The one thing wrong with it is a space, and the\n    reader was sent to re-check their unit spellings instead — with `5m` sitting in the list of\n    suggestions, differing from what they typed by a character they cannot see is the problem.\n\n    Only reachable now that the count above ignores whitespace; before, the length check caught\n    these first and there was nothing left to tell them apart by.\n  */\n  if (spaced) {\n    throw new TimeRangeError(\n      `${optionName} \"${input}\" puts a space between a number and its unit. ` +\n        `Write them together: ${input.trim().replace(/(\\d)\\s+([a-z])/giu, '$1$2')}`,\n    );\n  }\n\n  return signed(total);\n}\n\nfunction assertFinite(\n  value: number,\n  optionName: string,\n  input: string,\n  allowNegative: boolean,\n): number {\n  if (!Number.isFinite(value) || (!allowNegative && value < 0)) {\n    throw new TimeRangeError(`${optionName} \"${input}\" is not a valid non-negative time.`);\n  }\n  return value;\n}\n\nexport interface ResolvedRange {\n  /** Inclusive start, in seconds from the beginning of the recording. */\n  startSeconds: number;\n  /** Exclusive end, in seconds. */\n  endSeconds: number;\n  /** First data record touching the window. */\n  startRecord: number;\n  /** One past the last data record touching the window. */\n  endRecord: number;\n  /** True when the window covers the whole recording. */\n  isWholeRecording: boolean;\n  /** Earliest record start, including EDF+D timing gaps. */\n  recordingStartSeconds: number;\n  /** End of the latest record, including EDF+D timing gaps. */\n  recordingEndSeconds: number;\n}\n\n/**\n * Slack for comparisons at sample/window boundaries.\n *\n * A nanosecond is far below any real sampling interval — 20 kHz is 50 microseconds — so it\n * absorbs the arithmetic error in `recordStart + sample / rate` without reaching a\n * neighbouring sample.\n */\nexport const BOUNDARY_TOLERANCE = 1e-9;\n\n/**\n * The slack to use for a channel sampled this often.\n *\n * Never as much as half a sample interval, because slack that reaches the next sample stops\n * being slack. A fixed nanosecond was applied whatever the rate, and the format does not\n * oblige the interval to be larger than it: EDF's record duration is an 8-character field\n * that accepts `1e-9`. A recording of two 1 ns records holding ten samples each wrote ten of\n * its twenty rows — the window ends at 2e-9, the comparison asked for `time < 2e-9 - 1e-9`,\n * and the entire second record failed it. Exit 0, no warning, half the samples gone.\n */\nexport function toleranceFor(rate: number): number {\n  if (!(rate > 0) || !Number.isFinite(rate)) return BOUNDARY_TOLERANCE;\n  return Math.min(BOUNDARY_TOLERANCE, 1 / rate / 2);\n}\n\n/** Match the exact half-open boundary rules used while writing signal rows. */\nexport function sampleTimeIsInRange(\n  time: number,\n  startSeconds: number,\n  endSeconds: number,\n  tolerance: number = BOUNDARY_TOLERANCE,\n): boolean {\n  return time >= startSeconds - tolerance && time < endSeconds - tolerance;\n}\n\n/** Count samples from one record that fall inside a half-open requested window. */\nexport function countSamplesInRange(options: {\n  recordStart: number;\n  rate: number;\n  samplesPerRecord: number;\n  startSeconds: number;\n  endSeconds: number;\n}): number {\n  const slack = toleranceFor(options.rate);\n  const lower = Math.ceil(\n    (options.startSeconds - slack - options.recordStart) * options.rate,\n  );\n  const upper = Math.ceil(\n    (options.endSeconds - slack - options.recordStart) * options.rate,\n  );\n  const first = Math.max(0, Math.min(options.samplesPerRecord, lower));\n  const last = Math.max(0, Math.min(options.samplesPerRecord, upper));\n  return Math.max(0, last - first);\n}\n\n/**\n * Whether two instants differ only by the arithmetic that produced them.\n *\n * A relative epsilon, because the gap between doubles grows with magnitude — the same shape\n * the long layout uses to decide two sample times are one instant. Well below any real sample\n * interval, and well above the rounding that two routes to one quantity produce: a recording's\n * length is `recordCount * recordDuration`, which for 6003 records of 0.1s is not the 600.3 it\n * prints as.\n */\nfunction sameInstant(a: number, b: number): boolean {\n  return Math.abs(a - b) <= Math.max(Math.abs(a), Math.abs(b)) * 1e-12;\n}\n\n/**\n * Turn a requested window into both an exact time span and the record range that\n * contains it. Records are the unit the file can be read in; the exact span is what\n * decides which samples inside those records are actually written.\n */\nexport function resolveRange(options: {\n  start?: number | undefined;\n  /** The `--start` value exactly as typed, quoted back in the past-the-end error. */\n  startText?: string | undefined;\n  duration?: number | undefined;\n  end?: number | undefined;\n  /** The `--end` value exactly as typed, quoted back in the window error. */\n  endText?: string | undefined;\n  recordDuration: number;\n  recordCount: number;\n  /**\n   * True start time of each data record, for discontinuous files. When absent,\n   * records are assumed to sit end to end.\n   */\n  recordStarts?: Float64Array | null | undefined;\n}): ResolvedRange {\n  // For a continuous file the recording spans recordCount * recordDuration. A\n  // discontinuous one does not: a 10-second recording with a 95-second gap in the\n  // middle still ends at 105 seconds. Deriving the span from the records' real\n  // positions is what stops a requested window from being clipped back to the\n  // amount of *data* in the file and silently discarding everything past it.\n  const { earliest, latest } = span(options.recordStarts, options.recordCount, options.recordDuration);\n\n  if (options.duration !== undefined && options.end !== undefined) {\n    throw new TimeRangeError('Use either --duration or --end, not both.');\n  }\n\n  const startSeconds = options.start ?? earliest;\n\n  let endSeconds: number;\n  if (options.duration !== undefined) endSeconds = startSeconds + options.duration;\n  else if (options.end !== undefined) endSeconds = options.end;\n  else endSeconds = latest;\n\n  /*\n    At the end, allowing for the arithmetic that produced the end.\n\n    `latest` is `recordCount * recordDuration`, and with a fractional duration that is not the\n    number it prints as: 6003 records of 0.1s is 600.3000000000001, not 600.3. So `--start\n    600.3` on a recording `--info` calls \"10m 0.3s\" was accepted by a hair, converted nothing,\n    and exited 0 with a signals.csv holding its header — which is the empty conversion this\n    error exists to prevent, and which the same command on a whole-second recording is refused\n    for.\n\n    A relative epsilon, the same shape the long layout uses to decide two sample times are one\n    instant: well below any real interval, and well above the rounding that two different\n    routes to the same quantity produce.\n  */\n  if (startSeconds >= latest || sameInstant(startSeconds, latest)) {\n    /*\n      Quote what was typed. Reporting the parsed seconds meant `--start 4h` came back as\n      \"--start 14400s is at or past the end\", which reads as a value the user never gave.\n\n      In quotation marks, which the parse errors above have always used and this did not.\n      Without them the value ran into the sentence: `--start \"  5s  \"` printed as\n      `--start   5s   is at or past the end`, where the value appears to be `5s   is` and\n      the surrounding spaces — the actual reason a shell-built argument went wrong — are\n      invisible.\n    */\n    throw new TimeRangeError(\n      /*\n        The recording's length in the same words --info uses for it.\n\n        `formatSeconds` renders a bare number of seconds, so this message and the Duration\n        line disagreed about one file in one session: --info said \"6m 40s\" and the error said\n        \"400s\". On an overnight recording it read \"7950s recording\", leaving the reader to\n        divide by 3600 to find out whether their --start was reasonable — which is the one\n        question this message exists to answer. cli-reference.md has always documented it\n        humanised (\"2h 12m 30s\"), a form no input could produce.\n\n        The typed value keeps `quoted`, since that is the user's own text and should come\n        back exactly as they wrote it.\n      */\n      /*\n        `latest` is where the recording ends on its own clock, which is its length only when\n        it starts at zero. A file timed from its first record's timekeeping TAL need not: one\n        whose records run 1000s to 1003s is three seconds long, and this called it \"this\n        16m 43s recording\" — while --info two lines away said \"Duration 3s\". Where the\n        recording sits is the useful thing to say in that case, and it is the number --start\n        has to be given.\n      */\n      earliest === 0\n        ? `--start ${quoted(options.startText, startSeconds)} is at or past the end of this ` +\n          `${formatDuration(latest)} recording.`\n        : `--start ${quoted(options.startText, startSeconds)} is at or past the end of this ` +\n          `${formatDuration(latest - earliest)} recording, which runs from ` +\n          `${formatSeconds(earliest)} to ${formatSeconds(latest)}.`,\n    );\n  }\n  if (endSeconds <= startSeconds) {\n    // Quote whatever the caller actually gave, for the same reason as the error above. The\n    // end is only echoed when --end was passed: with --duration the end is computed here,\n    // so there is no typed value to quote and the arithmetic result is the honest thing.\n    const endShown =\n      options.end !== undefined && options.endText !== undefined\n        ? quoted(options.endText, endSeconds)\n        : formatSeconds(endSeconds);\n    const startShown = quoted(options.startText, startSeconds);\n    throw new TimeRangeError(\n      `The requested window ends at ${endShown}, which is not after its start at ${startShown}.`,\n    );\n  }\n\n  const clampedEnd = Math.min(endSeconds, latest);\n  /*\n    Both ends of the window, clamped the same way.\n\n    The end has been clamped to the recording since these fields existed — `--end 999h` on a\n    two-hour file is documented as converting to the end, silently — and the start was left as\n    typed. So a window asked for before the recording begins was recorded as one:\n\n        edf2csv two-second.edf --out csv --start=-500\n        metadata.json  \"start_seconds\": -500, \"end_seconds\": 2\n\n    over a signals.csv whose first row is 0.000, with `records_converted` correctly `[0, 2]`.\n    output-files calls the pair \"the resolved time window\", which the end is and the start was\n    not, and a script taking `end_seconds - start_seconds` for the span converted got 502 for\n    two seconds of data.\n\n    `earliest` and not zero, because a recording is timed from its first record and need not\n    begin there: negative-origin.edf runs from -100s, and -100 is where a start before the\n    recording belongs. Nothing downstream moves — every sample sits at or after `earliest`, so\n    the row filter and the record selection answer the same for either value, and the byte\n    estimate takes a width from the smaller magnitude, which is the one the column actually\n    holds.\n\n    Not when the whole window sits before the recording, where there is no overlap to clamp\n    to and raising the start past the end would describe the request backwards: `--start 0\n    --duration 0.001` on a file beginning at 30s is an empty window, and EMPTY_WINDOW quotes\n    the bounds — \"(30.000s to 0.001s)\" says nothing a reader can act on, where the bounds as\n    asked for are what its hint is already explaining.\n  */\n  const clampedStart = clampedEnd <= earliest ? startSeconds : Math.max(startSeconds, earliest);\n  const { startRecord, endRecord } = selectRecords(options, clampedStart, clampedEnd);\n\n  return {\n    startSeconds: clampedStart,\n    endSeconds: clampedEnd,\n    startRecord,\n    endRecord,\n    /*\n      The same rounding, one field over.\n\n      `latest` is `recordCount * recordDuration`, and 6003 records of 0.1s is\n      600.3000000000001. So `--end 600.3` on a recording of exactly that length wrote every\n      sample it has — byte-identical to a bare conversion — and metadata.json recorded\n      `whole_recording: false` for it, while the bare run recorded true. One conversion, two\n      answers, on the field a pipeline reads to decide whether it has the lot.\n    */\n    isWholeRecording:\n      (startSeconds <= earliest || sameInstant(startSeconds, earliest)) &&\n      (clampedEnd >= latest || sameInstant(clampedEnd, latest)),\n    recordingStartSeconds: earliest,\n    recordingEndSeconds: latest,\n  };\n}\n\nfunction span(\n  recordStarts: Float64Array | null | undefined,\n  recordCount: number,\n  recordDuration: number,\n): { earliest: number; latest: number } {\n  if (!recordStarts || recordStarts.length === 0) {\n    return { earliest: 0, latest: recordCount * recordDuration };\n  }\n  let earliest = Infinity;\n  let latest = -Infinity;\n  for (const start of recordStarts) {\n    if (start < earliest) earliest = start;\n    if (start + recordDuration > latest) latest = start + recordDuration;\n  }\n  if (!Number.isFinite(earliest) || !Number.isFinite(latest)) {\n    return { earliest: 0, latest: recordCount * recordDuration };\n  }\n  return { earliest, latest };\n}\n\n/** Every record whose own time span overlaps the requested window. */\nfunction selectRecords(\n  options: { recordDuration: number; recordCount: number; recordStarts?: Float64Array | null | undefined },\n  startSeconds: number,\n  endSeconds: number,\n): { startRecord: number; endRecord: number } {\n  const starts = options.recordStarts;\n  if (!starts || starts.length === 0) {\n    return {\n      startRecord: Math.max(0, Math.floor(startSeconds / options.recordDuration)),\n      endRecord: Math.min(options.recordCount, Math.ceil(endSeconds / options.recordDuration)),\n    };\n  }\n\n  let first = options.recordCount;\n  let last = 0;\n  for (let i = 0; i < starts.length; i++) {\n    const begin = starts[i] ?? 0;\n    if (begin + options.recordDuration > startSeconds && begin < endSeconds) {\n      if (i < first) first = i;\n      if (i + 1 > last) last = i + 1;\n    }\n  }\n  return first < last ? { startRecord: first, endRecord: last } : { startRecord: 0, endRecord: 0 };\n}\n\n/**\n * The value as the caller typed it, in quotation marks, or the parsed seconds if they gave\n * none. The marks show where the value begins and ends, which matters most for the values\n * that went wrong because of what surrounds them.\n */\nfunction quoted(text: string | undefined, seconds: number): string {\n  return text === undefined ? formatSeconds(seconds) : `\"${text}\"`;\n}\n\nfunction formatSeconds(seconds: number): string {\n  /*\n    The same 1e21 cliff, in the bounds this message hands back.\n\n    `--start \"9e21\"` was answered with \"is at or past the end of this 3e+21s recording, which\n    runs from 1e+21s to 4e+21s\" — a sentence whose whole purpose is to say what window there\n    is to ask for, ending in two tokens the parser refuses: `--start 1e+21s` is \"uses an\n    unknown unit \\\"e\\\"\". `Number(...)` was here to drop the trailing zeros, and it also\n    re-introduced the exponent form that `toFixed` had produced.\n  */\n  const text = fixed(seconds, 3);\n  return `${text.includes('.') ? text.replace(/\\.?0+$/u, '') : text}s`;\n}\n"]}
+{"version":3,"file":"time-range.js","sourceRoot":"","sources":["../../src/convert/time-range.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Parsing for the time-range options.\n *\n * Researchers write offsets in whatever form is natural for the recording in front\n * of them: seconds for a short ECG strip, `30m` into a sleep study, `01:23:45` when\n * reading off a clock. All three are accepted; anything ambiguous is rejected with\n * a message that shows the forms that work.\n */\n\nimport { fixed, formatDuration } from '../format/number.js';\n\nexport class TimeRangeError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'TimeRangeError';\n  }\n}\n\n/**\n * Every spelling of a unit this accepts, and what one of it is worth in seconds.\n *\n * Exported so the spellings can be enumerated by a test rather than listed a second time:\n * twelve of these sixteen are named nowhere in the tool or its documentation, and none of\n * their values was checked by anything. `hrs: 360` would have converted `--start 2hrs` from\n * twelve minutes in and said nothing, which is the one kind of mistake a window may not make.\n */\nexport const UNIT_SECONDS: Record<string, number> = {\n  h: 3600,\n  hr: 3600,\n  hrs: 3600,\n  hour: 3600,\n  hours: 3600,\n  m: 60,\n  min: 60,\n  mins: 60,\n  minute: 60,\n  minutes: 60,\n  s: 1,\n  sec: 1,\n  secs: 1,\n  second: 1,\n  seconds: 1,\n  ms: 0.001,\n};\n\nconst CLOCK = /^(?:(\\d+):)?(\\d{1,2}):(\\d{1,2}(?:\\.\\d+)?)$/u;\nconst UNIT_TOKEN = /(\\d+(?:\\.\\d+)?)\\s*([a-z]+)/giu;\n\n/**\n * Parse a duration or offset into seconds.\n *\n * Accepted: `90`, `90s`, `5m`, `1h30m`, `1h 30m 15s`, `00:30:00`, `30:00`, `250ms`.\n *\n * `allowNegative` is for the two options that name a position rather than a length.\n *\n * A recording is timed from its first record's timekeeping annotation, and nothing obliges that\n * to sit at or after zero: a file whose records run from -100 s to -97 s is one this tool reads,\n * times from -100, and describes with\n *\n *     Timed from -100.000s  (first sample; --start and --end use this clock)\n *\n * That line says the number can be typed straight back in, and it could not be. Every offset\n * such a recording has came back as \"not a time I understand\", so its whole clock was\n * unreachable and no window of it could be converted at all — the one file shape where a\n * window is refused for naming a moment the recording actually contains.\n *\n * A length below zero is still a different thing, and `--duration` still refuses one.\n */\nexport function parseTimeSpec(input: string, optionName: string, allowNegative = false): number {\n  const trimmed = input.trim().toLowerCase();\n  if (trimmed === '') {\n    throw new TimeRangeError(`${optionName} is empty. Try a value like 30s, 5m, or 00:30:00.`);\n  }\n\n  /*\n    The sign is read off the front and applied to the whole value, so `-1h30m` is an hour and a\n    half before the origin rather than an hour before it and half an hour after.\n\n    Nothing may sit between the sign and the number, and a leading `+` is still refused: every\n    other number this tool takes is refused when written in a form nobody types, and `+5` is\n    exactly what `--decimals` and `--jobs` reject one flag over.\n  */\n  const negative = trimmed.startsWith('-');\n  const text = negative ? trimmed.slice(1) : trimmed;\n\n  /*\n    A leading plus, named as such.\n\n    Refusing it is deliberate — see the paragraph above — but it came back as \"is not a time I\n    understand. Try 30s, 5m, 1h30m, 00:30:00, or a plain number of seconds\", which is the\n    message for input that could not be read at all. Every part of `+5s` was read: the number\n    parsed, the unit was looked up and found. The one thing wrong with it is a character the\n    reader put there on purpose, and they were sent to re-check their unit spellings with `5m`\n    sitting in the list of suggestions, differing from what they typed by the sign they cannot\n    see is the problem. 0.7.102 made this argument about a space; this is the same sentence\n    about the other character that reaches it. `--decimals` and `--jobs` both quote the value\n    back and say what is wrong with it.\n  */\n  if (text.startsWith('+')) {\n    throw new TimeRangeError(\n      `${optionName} \"${input}\" begins with a plus. Write the number on its own: ` +\n        `${input.trim().replace('+', '')}`,\n    );\n  }\n  const signed = (seconds: number): number =>\n    assertFinite(negative ? -seconds : seconds, optionName, input, allowNegative);\n\n  // Bare number means seconds.\n  if (/^\\d+(?:\\.\\d+)?$/u.test(text)) return signed(Number(text));\n\n  // Clock form: hh:mm:ss or mm:ss.\n  const clock = CLOCK.exec(text);\n  if (clock) {\n    const hours = clock[1] === undefined ? 0 : Number(clock[1]);\n    const minutes = Number(clock[2]);\n    const seconds = Number(clock[3]);\n    if (minutes >= 60 || seconds >= 60) {\n      throw new TimeRangeError(\n        `${optionName} \"${input}\" has a minutes or seconds field of 60 or more.`,\n      );\n    }\n    return signed(hours * 3600 + minutes * 60 + seconds);\n  }\n\n  // Unit form: 1h30m, 1h30m 15s, 250ms. A number sits directly against its unit; see below.\n  UNIT_TOKEN.lastIndex = 0;\n  let total = 0;\n  let matched = 0;\n  let consumed = 0;\n  /** Whether any token had a space between its number and its unit. See the refusal below. */\n  let spaced = false;\n  let match: RegExpExecArray | null;\n  // Which units have already been seen, so a repeat can be rejected rather than added.\n  const seen = new Set<number>();\n  while ((match = UNIT_TOKEN.exec(text)) !== null) {\n    const amount = Number(match[1]);\n    const unit = match[2] ?? '';\n    const scale = UNIT_SECONDS[unit];\n    if (scale === undefined) {\n      throw new TimeRangeError(\n        `${optionName} \"${input}\" uses an unknown unit \"${unit}\". Use h, m, s or ms, ` +\n          `or their long forms: hours, minutes, seconds.`,\n      );\n    }\n\n    // \"1h1h\" is a typo, not a request for two hours. Summing repeated units silently\n    // turned a slip into a plausible window that was quietly the wrong length. Units are\n    // keyed by their scale so the aliases collapse together: \"1h30min20m\" is caught too.\n    if (seen.has(scale)) {\n      throw new TimeRangeError(\n        `${optionName} \"${input}\" gives the same unit twice. ` +\n          `Combine each unit once, as in 1h30m.`,\n      );\n    }\n    seen.add(scale);\n\n    total += amount * scale;\n    matched++;\n    // Counted with the whitespace taken out, so the comparison below is against the same\n    // string on both sides and a space inside a token reaches the refusal written for it\n    // rather than the one about input that could not be read at all.\n    consumed += match[0].replace(/\\s+/gu, '').length;\n    if (/\\s/u.test(match[0])) spaced = true;\n  }\n\n  // Reject partially-understood input like \"5x\" or \"1h banana\".\n  if (matched === 0 || consumed !== text.replace(/\\s+/gu, '').length) {\n    throw new TimeRangeError(\n      `${optionName} \"${input}\" is not a time I understand. ` +\n        `Try 30s, 5m, 1h30m, 00:30:00, or a plain number of seconds.`,\n    );\n  }\n\n  /*\n    A space between a number and its unit, named as such.\n\n    `5 min` is refused on purpose — cli-reference sets the rule out, and it is what keeps\n    `1 2h` from being read as anything — but it came back as \"is not a time I understand. Try\n    30s, 5m, 1h30m, 00:30:00, or a plain number of seconds\", which is the message for input\n    that could not be read at all. Every part of `5 min` was read: the number parsed, the unit\n    was looked up in the table and found. The one thing wrong with it is a space, and the\n    reader was sent to re-check their unit spellings instead — with `5m` sitting in the list of\n    suggestions, differing from what they typed by a character they cannot see is the problem.\n\n    Only reachable now that the count above ignores whitespace; before, the length check caught\n    these first and there was nothing left to tell them apart by.\n  */\n  if (spaced) {\n    throw new TimeRangeError(\n      `${optionName} \"${input}\" puts a space between a number and its unit. ` +\n        `Write them together: ${input.trim().replace(/(\\d)\\s+([a-z])/giu, '$1$2')}`,\n    );\n  }\n\n  return signed(total);\n}\n\nfunction assertFinite(\n  value: number,\n  optionName: string,\n  input: string,\n  allowNegative: boolean,\n): number {\n  if (!Number.isFinite(value) || (!allowNegative && value < 0)) {\n    throw new TimeRangeError(`${optionName} \"${input}\" is not a valid non-negative time.`);\n  }\n  return value;\n}\n\nexport interface ResolvedRange {\n  /** Inclusive start, in seconds from the beginning of the recording. */\n  startSeconds: number;\n  /** Exclusive end, in seconds. */\n  endSeconds: number;\n  /** First data record touching the window. */\n  startRecord: number;\n  /** One past the last data record touching the window. */\n  endRecord: number;\n  /** True when the window covers the whole recording. */\n  isWholeRecording: boolean;\n  /** Earliest record start, including EDF+D timing gaps. */\n  recordingStartSeconds: number;\n  /** End of the latest record, including EDF+D timing gaps. */\n  recordingEndSeconds: number;\n}\n\n/**\n * Slack for comparisons at sample/window boundaries.\n *\n * A nanosecond is far below any real sampling interval — 20 kHz is 50 microseconds — so it\n * absorbs the arithmetic error in `recordStart + sample / rate` without reaching a\n * neighbouring sample.\n */\nexport const BOUNDARY_TOLERANCE = 1e-9;\n\n/**\n * The slack to use for a channel sampled this often.\n *\n * Never as much as half a sample interval, because slack that reaches the next sample stops\n * being slack. A fixed nanosecond was applied whatever the rate, and the format does not\n * oblige the interval to be larger than it: EDF's record duration is an 8-character field\n * that accepts `1e-9`. A recording of two 1 ns records holding ten samples each wrote ten of\n * its twenty rows — the window ends at 2e-9, the comparison asked for `time < 2e-9 - 1e-9`,\n * and the entire second record failed it. Exit 0, no warning, half the samples gone.\n */\nexport function toleranceFor(rate: number): number {\n  if (!(rate > 0) || !Number.isFinite(rate)) return BOUNDARY_TOLERANCE;\n  return Math.min(BOUNDARY_TOLERANCE, 1 / rate / 2);\n}\n\n/** Match the exact half-open boundary rules used while writing signal rows. */\nexport function sampleTimeIsInRange(\n  time: number,\n  startSeconds: number,\n  endSeconds: number,\n  tolerance: number = BOUNDARY_TOLERANCE,\n): boolean {\n  return time >= startSeconds - tolerance && time < endSeconds - tolerance;\n}\n\n/** Count samples from one record that fall inside a half-open requested window. */\nexport function countSamplesInRange(options: {\n  recordStart: number;\n  rate: number;\n  samplesPerRecord: number;\n  startSeconds: number;\n  endSeconds: number;\n}): number {\n  const slack = toleranceFor(options.rate);\n  const lower = Math.ceil(\n    (options.startSeconds - slack - options.recordStart) * options.rate,\n  );\n  const upper = Math.ceil(\n    (options.endSeconds - slack - options.recordStart) * options.rate,\n  );\n  const first = Math.max(0, Math.min(options.samplesPerRecord, lower));\n  const last = Math.max(0, Math.min(options.samplesPerRecord, upper));\n  return Math.max(0, last - first);\n}\n\n/**\n * Whether two instants differ only by the arithmetic that produced them.\n *\n * A relative epsilon, because the gap between doubles grows with magnitude — the same shape\n * the long layout uses to decide two sample times are one instant. Well below any real sample\n * interval, and well above the rounding that two routes to one quantity produce: a recording's\n * length is `recordCount * recordDuration`, which for 6003 records of 0.1s is not the 600.3 it\n * prints as.\n */\nfunction sameInstant(a: number, b: number): boolean {\n  return Math.abs(a - b) <= Math.max(Math.abs(a), Math.abs(b)) * 1e-12;\n}\n\n/**\n * Turn a requested window into both an exact time span and the record range that\n * contains it. Records are the unit the file can be read in; the exact span is what\n * decides which samples inside those records are actually written.\n */\nexport function resolveRange(options: {\n  start?: number | undefined;\n  /** The `--start` value exactly as typed, quoted back in the past-the-end error. */\n  startText?: string | undefined;\n  duration?: number | undefined;\n  end?: number | undefined;\n  /** The `--end` value exactly as typed, quoted back in the window error. */\n  endText?: string | undefined;\n  recordDuration: number;\n  recordCount: number;\n  /**\n   * True start time of each data record, for discontinuous files. When absent,\n   * records are assumed to sit end to end.\n   */\n  recordStarts?: Float64Array | null | undefined;\n}): ResolvedRange {\n  // For a continuous file the recording spans recordCount * recordDuration. A\n  // discontinuous one does not: a 10-second recording with a 95-second gap in the\n  // middle still ends at 105 seconds. Deriving the span from the records' real\n  // positions is what stops a requested window from being clipped back to the\n  // amount of *data* in the file and silently discarding everything past it.\n  const { earliest, latest } = span(options.recordStarts, options.recordCount, options.recordDuration);\n\n  if (options.duration !== undefined && options.end !== undefined) {\n    throw new TimeRangeError('Use either --duration or --end, not both.');\n  }\n\n  const startSeconds = options.start ?? earliest;\n\n  let endSeconds: number;\n  if (options.duration !== undefined) endSeconds = startSeconds + options.duration;\n  else if (options.end !== undefined) endSeconds = options.end;\n  else endSeconds = latest;\n\n  /*\n    At the end, allowing for the arithmetic that produced the end.\n\n    `latest` is `recordCount * recordDuration`, and with a fractional duration that is not the\n    number it prints as: 6003 records of 0.1s is 600.3000000000001, not 600.3. So `--start\n    600.3` on a recording `--info` calls \"10m 0.3s\" was accepted by a hair, converted nothing,\n    and exited 0 with a signals.csv holding its header — which is the empty conversion this\n    error exists to prevent, and which the same command on a whole-second recording is refused\n    for.\n\n    A relative epsilon, the same shape the long layout uses to decide two sample times are one\n    instant: well below any real interval, and well above the rounding that two different\n    routes to the same quantity produce.\n  */\n  if (startSeconds >= latest || sameInstant(startSeconds, latest)) {\n    /*\n      Quote what was typed. Reporting the parsed seconds meant `--start 4h` came back as\n      \"--start 14400s is at or past the end\", which reads as a value the user never gave.\n\n      In quotation marks, which the parse errors above have always used and this did not.\n      Without them the value ran into the sentence: `--start \"  5s  \"` printed as\n      `--start   5s   is at or past the end`, where the value appears to be `5s   is` and\n      the surrounding spaces — the actual reason a shell-built argument went wrong — are\n      invisible.\n    */\n    throw new TimeRangeError(\n      /*\n        The recording's length in the same words --info uses for it.\n\n        `formatSeconds` renders a bare number of seconds, so this message and the Duration\n        line disagreed about one file in one session: --info said \"6m 40s\" and the error said\n        \"400s\". On an overnight recording it read \"7950s recording\", leaving the reader to\n        divide by 3600 to find out whether their --start was reasonable — which is the one\n        question this message exists to answer. cli-reference.md has always documented it\n        humanised (\"2h 12m 30s\"), a form no input could produce.\n\n        The typed value keeps `quoted`, since that is the user's own text and should come\n        back exactly as they wrote it.\n      */\n      /*\n        `latest` is where the recording ends on its own clock, which is its length only when\n        it starts at zero. A file timed from its first record's timekeeping TAL need not: one\n        whose records run 1000s to 1003s is three seconds long, and this called it \"this\n        16m 43s recording\" — while --info two lines away said \"Duration 3s\". Where the\n        recording sits is the useful thing to say in that case, and it is the number --start\n        has to be given.\n      */\n      earliest === 0\n        ? `--start ${quoted(options.startText, startSeconds)} is at or past the end of this ` +\n          `${formatDuration(latest)} recording.`\n        : `--start ${quoted(options.startText, startSeconds)} is at or past the end of this ` +\n          `${formatDuration(latest - earliest)} recording, which runs from ` +\n          `${formatSeconds(earliest)} to ${formatSeconds(latest)}.`,\n    );\n  }\n  if (endSeconds <= startSeconds) {\n    // Quote whatever the caller actually gave, for the same reason as the error above. The\n    // end is only echoed when --end was passed: with --duration the end is computed here,\n    // so there is no typed value to quote and the arithmetic result is the honest thing.\n    const endShown =\n      options.end !== undefined && options.endText !== undefined\n        ? quoted(options.endText, endSeconds)\n        : formatSeconds(endSeconds);\n    const startShown = quoted(options.startText, startSeconds);\n    throw new TimeRangeError(\n      `The requested window ends at ${endShown}, which is not after its start at ${startShown}.`,\n    );\n  }\n\n  const clampedEnd = Math.min(endSeconds, latest);\n  /*\n    Both ends of the window, clamped the same way.\n\n    The end has been clamped to the recording since these fields existed — `--end 999h` on a\n    two-hour file is documented as converting to the end, silently — and the start was left as\n    typed. So a window asked for before the recording begins was recorded as one:\n\n        edf2csv two-second.edf --out csv --start=-500\n        metadata.json  \"start_seconds\": -500, \"end_seconds\": 2\n\n    over a signals.csv whose first row is 0.000, with `records_converted` correctly `[0, 2]`.\n    output-files calls the pair \"the resolved time window\", which the end is and the start was\n    not, and a script taking `end_seconds - start_seconds` for the span converted got 502 for\n    two seconds of data.\n\n    `earliest` and not zero, because a recording is timed from its first record and need not\n    begin there: negative-origin.edf runs from -100s, and -100 is where a start before the\n    recording belongs. Nothing downstream moves — every sample sits at or after `earliest`, so\n    the row filter and the record selection answer the same for either value, and the byte\n    estimate takes a width from the smaller magnitude, which is the one the column actually\n    holds.\n\n    Not when the whole window sits before the recording, where there is no overlap to clamp\n    to and raising the start past the end would describe the request backwards: `--start 0\n    --duration 0.001` on a file beginning at 30s is an empty window, and EMPTY_WINDOW quotes\n    the bounds — \"(30.000s to 0.001s)\" says nothing a reader can act on, where the bounds as\n    asked for are what its hint is already explaining.\n  */\n  const clampedStart = clampedEnd <= earliest ? startSeconds : Math.max(startSeconds, earliest);\n  const { startRecord, endRecord } = selectRecords(options, clampedStart, clampedEnd);\n\n  return {\n    startSeconds: clampedStart,\n    endSeconds: clampedEnd,\n    startRecord,\n    endRecord,\n    /*\n      The same rounding, one field over.\n\n      `latest` is `recordCount * recordDuration`, and 6003 records of 0.1s is\n      600.3000000000001. So `--end 600.3` on a recording of exactly that length wrote every\n      sample it has — byte-identical to a bare conversion — and metadata.json recorded\n      `whole_recording: false` for it, while the bare run recorded true. One conversion, two\n      answers, on the field a pipeline reads to decide whether it has the lot.\n    */\n    isWholeRecording:\n      (startSeconds <= earliest || sameInstant(startSeconds, earliest)) &&\n      (clampedEnd >= latest || sameInstant(clampedEnd, latest)),\n    recordingStartSeconds: earliest,\n    recordingEndSeconds: latest,\n  };\n}\n\nfunction span(\n  recordStarts: Float64Array | null | undefined,\n  recordCount: number,\n  recordDuration: number,\n): { earliest: number; latest: number } {\n  if (!recordStarts || recordStarts.length === 0) {\n    return { earliest: 0, latest: recordCount * recordDuration };\n  }\n  let earliest = Infinity;\n  let latest = -Infinity;\n  for (const start of recordStarts) {\n    if (start < earliest) earliest = start;\n    if (start + recordDuration > latest) latest = start + recordDuration;\n  }\n  if (!Number.isFinite(earliest) || !Number.isFinite(latest)) {\n    return { earliest: 0, latest: recordCount * recordDuration };\n  }\n  return { earliest, latest };\n}\n\n/** Every record whose own time span overlaps the requested window. */\nfunction selectRecords(\n  options: { recordDuration: number; recordCount: number; recordStarts?: Float64Array | null | undefined },\n  startSeconds: number,\n  endSeconds: number,\n): { startRecord: number; endRecord: number } {\n  const starts = options.recordStarts;\n  if (!starts || starts.length === 0) {\n    return {\n      startRecord: Math.max(0, Math.floor(startSeconds / options.recordDuration)),\n      endRecord: Math.min(options.recordCount, Math.ceil(endSeconds / options.recordDuration)),\n    };\n  }\n\n  let first = options.recordCount;\n  let last = 0;\n  for (let i = 0; i < starts.length; i++) {\n    const begin = starts[i] ?? 0;\n    if (begin + options.recordDuration > startSeconds && begin < endSeconds) {\n      if (i < first) first = i;\n      if (i + 1 > last) last = i + 1;\n    }\n  }\n  return first < last ? { startRecord: first, endRecord: last } : { startRecord: 0, endRecord: 0 };\n}\n\n/**\n * The value as the caller typed it, in quotation marks, or the parsed seconds if they gave\n * none. The marks show where the value begins and ends, which matters most for the values\n * that went wrong because of what surrounds them.\n */\nfunction quoted(text: string | undefined, seconds: number): string {\n  return text === undefined ? formatSeconds(seconds) : `\"${text}\"`;\n}\n\nfunction formatSeconds(seconds: number): string {\n  /*\n    The same 1e21 cliff, in the bounds this message hands back.\n\n    `--start \"9e21\"` was answered with \"is at or past the end of this 3e+21s recording, which\n    runs from 1e+21s to 4e+21s\" — a sentence whose whole purpose is to say what window there\n    is to ask for, ending in two tokens the parser refuses: `--start 1e+21s` is \"uses an\n    unknown unit \\\"e\\\"\". `Number(...)` was here to drop the trailing zeros, and it also\n    re-introduced the exponent form that `toFixed` had produced.\n  */\n  const text = fixed(seconds, 3);\n  return `${text.includes('.') ? text.replace(/\\.?0+$/u, '') : text}s`;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edf2csv",
-  "version": "0.7.120",
+  "version": "0.7.122",
   "description": "Convert EDF, EDF+ and BDF biosignal recordings (European Data Format) to CSV from the command line. Local, streaming, and never resamples or alters units.",
   "keywords": [
     "edf",