Files
likang 7e01147566
CI / typecheck + test + build (push) Has been cancelled
Initial commit: import VibeMake PCB Studio
2026-11-03 11:20:08 +08:00

1340 lines
44 KiB
TypeScript

// SPDX-License-Identifier: GPL-3.0-or-later
// Copyright (C) 2026 ZiroEDA and contributors.
// Portions derived from KiCad, copyright The KiCad Developers. See NOTICE.md.
/**
* String helpers shared across the editors. Counterpart:
* `common/string_utils.cpp`, the natural-order comparison every reference
* designator list is sorted with, and the stacked-pin notation, which lets one
* schematic pin stand for several footprint pads: `[1,2]`, `[A1-A4]`,
* `[1,3-5,7]`. A backslash escapes a structural character (`[ ] , -`) so it can
* appear inside a pin number.
*/
import type { OutStr } from './font/font.js';
import { ResolveUriByEnvVars } from './eda_doc.js';
import { wxDirExists, wxFileExists, wxNormalizePath } from '@ziroeda/wx/filefn.js';
/**
* EscapeString( …, CTX_NETNAME ), make a string safe to use as (part of) a net
* name. `/` is the hierarchy separator in a net name, so it becomes `{slash}`;
* newlines are dropped. This is what turns a label "SDA/A4" into the net name
* "SDA{slash}A4", and it is applied to each sheet name of a net's path too.
*/
export function escapeNetName(source: string): string {
let out = '';
for (const c of source) {
if (c === '/') out += '{slash}';
else if (c === '\n' || c === '\r') continue;
else out += c;
}
return out;
}
/**
* StrNumCmp, natural order: digit runs compare by value, so R2 sorts before
* R10. `aIgnoreCase` defaults to false, as upstream.
*/
export function strNumCmp(a: string, b: string, ignoreCase = false): number {
const fold = (s: string): string => (ignoreCase ? s.toUpperCase() : s);
let i = 0;
let j = 0;
while (i < a.length && j < b.length) {
const ca = a[i]!;
const cb = b[j]!;
if (ca >= '0' && ca <= '9' && cb >= '0' && cb <= '9') {
let ei = i;
while (ei < a.length && a[ei]! >= '0' && a[ei]! <= '9') ei++;
let ej = j;
while (ej < b.length && b[ej]! >= '0' && b[ej]! <= '9') ej++;
const na = Number(a.slice(i, ei));
const nb = Number(b.slice(j, ej));
if (na !== nb) return na < nb ? -1 : 1;
i = ei;
j = ej;
continue;
}
const fa = fold(ca);
const fb = fold(cb);
if (fa !== fb) return fa < fb ? -1 : 1;
i++;
j++;
}
return a.length - i - (b.length - j);
}
/**
* EscapeString( …, CTX_IPC ), make a string safe to put in a cross-probe packet.
* The packet joins its parts with commas and splits a path on slashes, and a
* quote would end a quoted field early — so those three, and only those three,
* are escaped. `{` is left alone here, unlike the file contexts.
*/
export function escapeIpc(source: string): string {
let out = '';
for (const c of source) {
if (c === '/') out += '{slash}';
else if (c === ',') out += '{comma}';
else if (c === '"') out += '{dblquote}';
else out += c;
}
return out;
}
/**
* `EscapeString( …, CTX_LIBID )`, make a string safe to use as a LIB_ID part.
*
* The set is exactly the characters `LIB_ID::isLegalChar` rejects, minus the
* two it drops rather than escapes:
*
* else if( c == '\\' ) converted += wxT( "{backslash}" );
* else if( c == '<' ) converted += wxT( "{lt}" );
* else if( c == '>' ) converted += wxT( "{gt}" );
* else if( c == ':' ) converted += wxT( "{colon}" );
* else if( c == '\"' ) converted += wxT( "{dblquote}" );
* else if( c == '\n' || c == '\r' ) converted += wxEmptyString; // drop
*
* `/` is NOT escaped: it was, under `CTX_LEGACY_LIBID`, and the comment
* upstream ("We no longer escape '/' in LIB_IDs, but we used to") is the whole
* reason the two contexts still exist separately. A tab survives too — it is
* illegal in a LIB_ID but has no escape, which is upstream's, not ours.
*/
export function escapeLibId(source: string): string {
let out = '';
for (const c of source) {
if (c === '\\') out += '{backslash}';
else if (c === '<') out += '{lt}';
else if (c === '>') out += '{gt}';
else if (c === ':') out += '{colon}';
else if (c === '"') out += '{dblquote}';
else if (c === '\n' || c === '\r') continue;
else out += c;
}
return out;
}
/** UnescapeString's `{token}` -> character table. */
const UNESCAPE_TOKENS: Record<string, string> = {
dblquote: '"',
quote: "'",
lt: '<',
gt: '>',
backslash: '\\',
slash: '/',
bar: '|',
comma: ',',
colon: ':',
space: ' ',
dollar: '$',
tab: '\t',
return: '\n',
brace: '{',
};
/**
* UnescapeString, turn the `{slash}`-style escapes KiCad writes into a file back
* into the characters they stand for. A `{…}` group preceded by `$`, `~`, `^` or `_`
* is markup (a variable reference, an overbar, a superscript, a subscript) and is
* kept, with its contents unescaped; so is an unknown or unterminated token.
*/
export function unescapeString(source: string): string {
// The smallest escape string is three characters; shortcut everything else.
if (source.length <= 2) return source;
let out = '';
let prev = '';
let ch = '';
for (let i = 0; i < source.length; ++i) {
prev = ch;
ch = source[i]!;
if (ch !== '{') {
out += ch;
continue;
}
let token = '';
let depth = 1;
let terminated = false;
for (i = i + 1; i < source.length; ++i) {
ch = source[i]!;
if (ch === '{') depth++;
else if (ch === '}') depth--;
if (depth <= 0) {
terminated = true;
break;
}
token += ch;
}
if (!terminated) out += `{${unescapeString(token)}`;
else if (prev === '$' || prev === '~' || prev === '^' || prev === '_')
out += `{${unescapeString(token)}}`;
else if (token in UNESCAPE_TOKENS) out += UNESCAPE_TOKENS[token];
else out += `{${unescapeString(token)}}`;
}
return out;
}
/** The characters stacked-pin notation gives meaning to. */
const SPECIAL = new Set(['[', ']', ',', '-', '\\']);
const isEscapeAt = (text: string, i: number): boolean =>
text[i] === '\\' && i + 1 < text.length && SPECIAL.has(text[i + 1]!);
/** EscapeStackedPinItem: make a pin number safe to place inside `[…]`. */
export function escapeStackedPinItem(pinNumber: string): string {
let out = '';
for (const ch of pinNumber) {
if (SPECIAL.has(ch)) out += '\\';
out += ch;
}
return out;
}
/** SplitStackedPinItems: split on unescaped commas. */
function splitStackedPinItems(inner: string): string[] {
const parts: string[] = [];
let current = '';
for (let i = 0; i < inner.length; i++) {
if (isEscapeAt(inner, i)) {
current += inner[i]! + inner[i + 1]!;
i++;
} else if (inner[i] === ',') {
parts.push(current);
current = '';
} else {
current += inner[i];
}
}
parts.push(current);
return parts;
}
/** FindUnescaped: the first unescaped occurrence of a character, or -1. */
function findUnescaped(text: string, ch: string): number {
for (let i = 0; i < text.length; i++) {
if (isEscapeAt(text, i)) i++;
else if (text[i] === ch) return i;
}
return -1;
}
/** UnescapeStackedPinItem: drop the backslashes a structural character needed. */
function unescapeStackedPinItem(item: string): string {
let out = '';
for (let i = 0; i < item.length; i++) {
if (isEscapeAt(item, i)) out += item[++i];
else out += item[i];
}
return out;
}
/** ParseAlphaNumericPin: split "A12" into ["A", 12]; -1 when there is no number. */
function parseAlphaNumericPin(pinNum: string): [string, number] {
let numStart = pinNum.length;
for (let i = pinNum.length - 1; i >= 0; i--) {
if (!/[0-9]/.test(pinNum[i]!)) {
numStart = i + 1;
break;
}
if (i === 0) numStart = 0; // all digits
}
if (numStart < pinNum.length) {
const prefix = pinNum.slice(0, numStart);
const value = Number.parseInt(pinNum.slice(numStart), 10);
return [prefix, Number.isNaN(value) ? -1 : value];
}
return ['', -1];
}
/**
* ExpandStackedPinNotation: the pad numbers a pin stands for. `valid` reports
* whether the notation parsed, mismatched brackets, a reversed or
* non-numeric range, or an empty list make it false, and the pin name comes
* back unexpanded.
*/
export function expandStackedPinNotation(pinName: string): {
numbers: string[];
valid: boolean;
} {
const hasOpen = pinName.includes('[');
const hasClose = pinName.includes(']');
if (hasOpen || hasClose) {
if (!pinName.startsWith('[') || !pinName.endsWith(']')) {
return { numbers: [pinName], valid: false };
}
}
if (!pinName.startsWith('[') || !pinName.endsWith(']')) {
return { numbers: [pinName], valid: true };
}
const inner = pinName.slice(1, -1);
const expanded: string[] = [];
for (const raw of splitStackedPinItems(inner)) {
const part = raw.trim();
if (part === '') continue;
// A range (A1-A4) is only a range on an *unescaped* dash.
const dash = findUnescaped(part, '-');
if (dash !== -1) {
const startTxt = unescapeStackedPinItem(part.slice(0, dash)).trim();
const endTxt = unescapeStackedPinItem(part.slice(dash + 1)).trim();
const [startPrefix, startVal] = parseAlphaNumericPin(startTxt);
const [endPrefix, endVal] = parseAlphaNumericPin(endTxt);
if (startPrefix !== endPrefix || startVal === -1 || endVal === -1 || startVal > endVal) {
return { numbers: [pinName], valid: false };
}
for (let i = startVal; i <= endVal; i++) expanded.push(`${startPrefix}${i}`);
} else {
expanded.push(unescapeStackedPinItem(part));
}
}
if (expanded.length === 0) return { numbers: [pinName], valid: false };
return { numbers: expanded, valid: true };
}
/** CountStackedPinNotation: how many pads a pin number stands for. */
export function countStackedPinNotation(pinName: string): { count: number; valid: boolean } {
if (pinName.length === 0) return { count: 1, valid: true };
const { numbers, valid } = expandStackedPinNotation(pinName);
return { count: numbers.length, valid };
}
/**
* ConvertToNewOverbarNotation (`common/string_utils.cpp:88-156`): rewrite the
* pre-2021 overbar spelling, where a bare `~` toggled an overbar on and off
* (and a space, `}` or `)` also ended one), into the current `~{…}` form.
*
* Every reader of a file older than its format's cut-over runs its text
* through this; without it a legacy `~RESET` keeps its tilde as a literal
* character and draws with no bar at all.
*
* The details that a paraphrase loses, all from the C++:
* - the lone `~` is the legacy empty-string token and is returned untouched;
* - `~~` is an escaped tilde, but `~~{` becomes `~~{}` so that the `{` which
* follows cannot open an overbar;
* - `~{` means the string has already been converted, so the WHOLE string is
* returned unchanged rather than converted twice;
* - an overbar left open at the end of the string is closed explicitly.
*/
export function convertToNewOverbarNotation(oldStr: string): string {
// Don't get tripped up by the legacy empty-string token.
if (oldStr === '~') return oldStr;
let newStr = '';
let inOverbar = false;
for (let i = 0; i < oldStr.length; i++) {
const ch = oldStr[i]!;
if (ch === '~') {
const next = oldStr[i + 1];
if (next === '~') {
if (oldStr[i + 2] === '{') {
// This way the subsequent opening curly brace will not start an
// overbar.
newStr += '~~{}';
continue;
}
// Two subsequent tildes mean a tilde.
newStr += '~';
i++;
continue;
}
if (next === '{') {
// Could mean the user wants "{" with an overbar, but more likely this
// is a case of double notation conversion. Bail out.
return oldStr;
}
if (inOverbar) {
newStr += '}';
inOverbar = false;
} else {
newStr += '~{';
inOverbar = true;
}
continue;
}
if ((ch === ' ' || ch === '}' || ch === ')') && inOverbar) {
// Spaces were used to terminate overbar as well.
newStr += '}';
inOverbar = false;
}
newStr += ch;
}
// Explicitly end the overbar even if there was no terminating '~'.
if (inOverbar) newStr += '}';
return newStr;
}
// ---------------------------------------------------------------------------
// Wildcard matching (`common/string_utils.cpp:910`).
/**
* WildCompareString: match `stringToTst` against a `*` / `?` `pattern`, whole
* string. `*` stands for any run of characters including an empty one, `?` for
* exactly one; every other character, `.` `+` `^` `$` `(` `)` `[` `]` `|` `\`
* included, is literal.
*
* This is the pointer walk upstream uses rather than a translation to a regular
* expression, which is the point: with no regex there is no escape set to get
* wrong, so a net named `Net.Cu` can never be matched by the pattern `NetXCu`.
*
* `caseSensitive` defaults to true exactly as the header does
* (`include/string_utils.h:233`), but **every call site in KiCad passes
* `false`** — the filters in Edit Text and Graphics, Change Symbols, Exchange
* Footprints, the net navigator and the DRC expression evaluator are all
* case-insensitive to the user. Pass the argument explicitly, the way the C++
* does, rather than leaning on the default.
*/
export function wildCompareString(
pattern: string,
stringToTst: string,
caseSensitive = true,
): boolean {
const wild = caseSensitive ? pattern : pattern.toUpperCase();
const str = caseSensitive ? stringToTst : stringToTst.toUpperCase();
// Indices, where upstream has pointers: past the end reads as undefined,
// which stands in for the terminating NUL and equals no character.
let w = 0;
let s = 0;
let mp = 0;
let cp = 0;
while (s < str.length && wild[w] !== '*') {
if (wild[w] !== str[s] && wild[w] !== '?') return false;
w++;
s++;
}
while (s < str.length) {
if (wild[w] === '*') {
w++;
// A trailing `*` swallows the rest of the string.
if (w >= wild.length) return true;
// Remember where to resume if this `*` turns out to be too greedy.
mp = w;
cp = s + 1;
} else if (wild[w] === str[s] || wild[w] === '?') {
w++;
s++;
} else {
w = mp;
s = cp++;
}
}
// Trailing `*`s may still match the empty remainder.
while (wild[w] === '*') w++;
return w >= wild.length;
}
// ---------------------------------------------------------------------------
// Numeric-aware helpers (`common/string_utils.cpp`).
/**
* GetTrailingInt (`common/string_utils.cpp:1299`): the number a string ends
* with, 0 when it ends in anything else. No sign and no decimal point, so
* `"12Foo4.2"` is 2 and `"foo"` is 0.
*/
export function getTrailingInt(str: string): number {
let number = 0;
let base = 1;
for (let i = str.length - 1; i >= 0; i--) {
const ch = str[i]!;
if (ch < '0' || ch > '9') break;
number += (ch.charCodeAt(0) - 48) * base;
base *= 10;
}
return number;
}
/**
* NUMERIC_EVALUATOR::IsOldSchoolDecimalSeparator
* (`common/libeval/numeric_evaluator.cpp:196`): the characters that may be
* written *in place of* a decimal point, `4k7` for 4.7 k. Both micro signs are
* listed because they look alike and are U+00B5 and U+03BC.
*/
const OLD_SCHOOL_DECIMAL_SEPARATORS = new Set([
'p',
'n',
'µ',
'μ',
'u',
'm',
'L',
'R',
'F',
'k',
'K',
'M',
'G',
'T',
]);
/**
* convertSeparators (`common/string_utils.cpp:1090`): rewrite a number into the
* C locale, working out from the value itself which of `.` and `,` is the
* decimal point and which groups thousands.
*
* Upstream's reasoning, which is why this is not just "strip the commas":
* fetching the separator from the current locale is no silver bullet, because
* it assumes the schematic was authored on this computer. Most values say what
* they are — several instances of one character must be thousands separators,
* one of each must be thousands then decimal, a separator followed by other
* than three digits must be a decimal — and only a genuinely ambiguous value
* falls back on the locale.
*
* Returns the converted string, or `undefined` when the value contradicts
* itself (a decimal before a thousands, two decimals, a thousands group that is
* not three digits). Upstream returns false there and leaves the string
* untouched, and its one caller ignores the result, so the caller here keeps
* the original text on `undefined` in the same way.
*/
export function convertSeparators(value: string): string | undefined {
let text = value.split(' ').join('');
let ambiguousSeparator = '?';
let thousandsSeparator = '?';
let thousandsSeparatorFound = false;
let decimalSeparator = '?';
let decimalSeparatorFound = false;
let digits = 0;
for (let ii = text.length - 1; ii >= 0; --ii) {
const c = text[ii]!;
if (c >= '0' && c <= '9') {
digits += 1;
continue;
}
if (c !== '.' && c !== ',') {
digits = 0;
continue;
}
if (decimalSeparator !== '?' || thousandsSeparator !== '?') {
// We've previously found a non-ambiguous separator...
if (c === decimalSeparator) {
if (thousandsSeparatorFound) return undefined; // decimal before thousands
if (decimalSeparatorFound) return undefined; // more than one decimal
decimalSeparatorFound = true;
} else if (c === thousandsSeparator) {
if (digits !== 3) return undefined; // thousands not followed by 3 digits
thousandsSeparatorFound = true;
}
} else if (ambiguousSeparator !== '?') {
// We've previously found a separator, but we don't know which...
if (c === ambiguousSeparator) {
// They both must be thousands separators.
thousandsSeparator = ambiguousSeparator;
thousandsSeparatorFound = true;
decimalSeparator = c === '.' ? ',' : '.';
} else {
// The first must have been a decimal, and this must be a thousands.
decimalSeparator = ambiguousSeparator;
decimalSeparatorFound = true;
thousandsSeparator = c;
thousandsSeparatorFound = true;
}
} else {
// This is the first separator. Preceded by a lone `0`, or followed by
// some number of digits other than 3, and it must be a decimal point;
// otherwise we do not know yet.
if ((ii === 1 && text[0] === '0') || digits !== 3) {
decimalSeparator = c;
decimalSeparatorFound = true;
thousandsSeparator = c === '.' ? ',' : '.';
} else {
ambiguousSeparator = c;
}
}
digits = 0;
}
// If we found nothing definitive we would have to look at the current
// locale. A browser has no `localeconv()` and every file we read is written
// in the C locale, so `.` is the decimal point.
if (decimalSeparator === '?' && thousandsSeparator === '?') {
decimalSeparator = '.';
thousandsSeparator = ',';
}
// Convert to C-locale.
text = text.split(thousandsSeparator).join('');
text = text.split(decimalSeparator).join('.');
return text;
}
/**
* SplitString (`common/string_utils.cpp:1213`): break a value into its
* alphabetic preamble, its digit run and its trailing text — `C10A` is
* `C` / `10` / `A`. An "old school" decimal separator inside the digits (the
* `k` of `4k7`) is moved: the digits become `4.7` and the ending gains the `k`.
*/
export function splitString(strToSplit: string): {
beginning: string;
digits: string;
end: string;
} {
// Starting at the end of the string look for the first digit.
let ii = strToSplit.length - 1;
for (; ii >= 0; ii--) {
if (strToSplit[ii]! >= '0' && strToSplit[ii]! <= '9') break;
}
// If there were no digits then just set the single string.
if (ii < 0) return { beginning: strToSplit, digits: '', end: '' };
// Since there is at least one digit this is the trailing string.
const end = strToSplit.slice(ii + 1);
const position = ii + 1;
let infix = '';
for (; ii >= 0; ii--) {
const c = strToSplit[ii]!;
if (c >= '0' && c <= '9') continue;
// NUMERIC_EVALUATOR::IsOldSchoolDecimalSeparator: one unit letter may
// stand in for the decimal point, as in `4k7` or `1u5F`. It is a closed
// set of 14 characters, not "any letter" — `C` in `C10A` is a preamble.
if (infix === '' && OLD_SCHOOL_DECIMAL_SEPARATORS.has(c)) {
infix = c;
continue;
}
if (c === '.' || c === ',') continue;
break;
}
let digits: string;
let beginning = '';
if (ii < 0) {
// All that was left was digits.
digits = strToSplit.slice(0, position);
} else {
digits = strToSplit.slice(ii + 1, position);
beginning = strToSplit.slice(0, ii + 1);
}
if (infix !== '') return { beginning, digits: digits.split(infix).join('.'), end: infix + end };
return { beginning, digits, end };
}
/** The SI/IEC-60062 multipliers ApplyModifier recognises. Both micro signs
* (U+00B5 and U+03BC) are listed, as upstream lists both. */
const SI_MODIFIERS: Readonly<Record<string, number>> = {
a: 1e-18,
f: 1e-15,
p: 1e-12,
n: 1e-9,
u: 1e-6,
µ: 1e-6,
μ: 1e-6,
m: 1e-3,
L: 1e-3,
R: 1,
F: 1,
k: 1e3,
K: 1e3,
M: 1e6,
G: 1e9,
T: 1e12,
P: 1e15,
E: 1e18,
};
/**
* ApplyModifier (`common/string_utils.cpp:971`): scale `value` by the SI suffix
* the trailing text starts with. `isModifier` is false when that text is not a
* unit at all, which is what makes ValueStringCompare fall back to comparing
* the endings as plain text.
*/
function applyModifier(value: number, text: string): { value: number; isModifier: boolean } {
if (text.length === 0) return { value, isModifier: false };
const first = text[0]!;
const hasModifier = first in SI_MODIFIERS;
const units = (hasModifier ? text.slice(1) : text).trim();
const known = ['f', 'hz', 'w', 'v', 'a', 'h'];
if (units.length > 0 && !known.includes(units.toLowerCase())) return { value, isModifier: false };
return { value: hasModifier ? value * SI_MODIFIERS[first]! : value, isModifier: true };
}
/**
* ValueStringCompare (`common/string_utils.cpp:1158`): order two component
* values the way a person reads them — `10uF` before `100uF`, `100uF` before
* `1mF` — by splitting each into preamble / number / units and comparing the
* three in turn. The preamble and the ending compare case-insensitively.
*
* Both sides are unescaped first, as upstream does, so a value written to file
* as `1{k}5` sorts as the `1k5` the user typed.
*/
export function valueStringCompare(strFWord: string, strSWord: string): number {
// Compare unescaped text.
const fa = splitString(unescapeString(strFWord));
const fb = splitString(unescapeString(strSWord));
const beg = fa.beginning.toLowerCase().localeCompare(fb.beginning.toLowerCase());
if (beg !== 0) return beg < 0 ? -1 : 1;
// ToCDouble on a C-locale number: anything unparseable reads as 0, exactly as
// an untouched wxString does when ToCDouble fails.
const toDouble = (digits: string): number => Number(convertSeparators(digits) ?? digits) || 0;
const na = applyModifier(toDouble(fa.digits), fa.end);
const nb = applyModifier(toDouble(fb.digits), fb.end);
if (na.value > nb.value) return 1;
if (na.value < nb.value) return -1;
// If the first two sections are equal and the endings are modifiers then
// there is nothing left to compare.
if (!na.isModifier && !nb.isModifier) {
const end = fa.end.toLowerCase().localeCompare(fb.end.toLowerCase());
return end < 0 ? -1 : end > 0 ? 1 : 0;
}
return 0;
}
/**
* C's `%g` conversion, which `wxString::Format` hands straight to the C
* library — `PL_EDITOR_FRAME::UpdateStatusBar` formats its coordinates with
* `"X %.4g Y %.4g"` (`pagelayout_editor/pl_editor_frame.cpp:770-771`).
*
* `%g` is not "4 significant digits": it is 4 significant digits *and* a switch
* to exponent form once the exponent leaves the range `-4 <= e < precision`,
* with trailing zeros trimmed and the exponent padded to two digits. That is
* why a cold-open pl_editor reads `X 1.266e+04 Y 1.217e+04` and not
* `X 12660 Y 12170`, which is what `Number(n.toPrecision(4))` gives.
*
* The exponent is taken AFTER rounding to `precision` digits, as C does, so
* 9999.6 at `%.4g` is `1e+04` rather than `9999.6`.
*/
export function formatG(value: number, precision = 4): string {
if (!Number.isFinite(value)) return String(value);
// Negative zero keeps its sign, as the C library does. This is visible, not
// pedantic: `PL_EDITOR_FRAME::UpdateStatusBar` multiplies each delta by the
// origin corner's axis sign, so a pl_editor sitting on `Right Bottom page
// corner` with the cursor on its local origin computes `0 * -1` and its
// status bar reads `dx -0 dy -0`. Photographed off the running program
// (`qa/probes/pl_e2e`); ours read `dx 0 dy 0`.
if (value === 0) return Object.is(value, -0) ? '-0' : '0';
const p = precision <= 0 ? 1 : precision;
const rounded = value.toExponential(p - 1);
const exponent = Number(rounded.slice(rounded.indexOf('e') + 1));
const trim = (text: string): string =>
text.includes('.') ? text.replace(/0+$/, '').replace(/\.$/, '') : text;
if (exponent < -4 || exponent >= p) {
const mantissa = trim(rounded.slice(0, rounded.indexOf('e')));
const sign = exponent < 0 ? '-' : '+';
return `${mantissa}e${sign}${String(Math.abs(exponent)).padStart(2, '0')}`;
}
return trim(value.toFixed(Math.max(0, p - 1 - exponent)));
}
/**
* `wxStringSplit` (common/string_utils.cpp:1402-1421).
*
* Not `String.split`: wx appends the accumulated word at every separator, so
* two adjacent separators yield an empty element, but it appends the tail only
* `if( !tmp.IsEmpty() )`, so exactly ONE trailing empty is dropped. `"a "`
* therefore splits to `["a", ""]`, where `split(' ')` gives `["a", "", ""]`.
*/
export function wxStringSplit(text: string, splitter: string): string[] {
const parts = text.split(splitter);
if (parts.length > 0 && parts[parts.length - 1] === '') parts.pop();
return parts;
}
/**
* `PrintableCharCount` (common/string_utils.cpp:704): the characters a text shows, leaving out
* tabs and the `^{ }`, `_{ }` and `~{ }` markup.
*/
export function PrintableCharCount(aString: string): number {
let char_count = 0;
let overbarDepth = -1;
let superSubDepth = -1;
let braceNesting = 0;
const chars = [...aString];
for (let i = 0; i < chars.length; i++) {
const ch = chars[i];
if (ch === '\t') {
// We don't format tabs in bitmap text (where this is currently used), so just
// drop them from the count.
continue;
} else if ((ch === '^' || ch === '_') && superSubDepth === -1) {
if (chars[i + 1] === '{') {
i++;
superSubDepth = braceNesting;
braceNesting++;
continue;
}
} else if (ch === '~' && overbarDepth === -1) {
if (chars[i + 1] === '{') {
i++;
overbarDepth = braceNesting;
braceNesting++;
continue;
}
} else if (ch === '{') {
braceNesting++;
} else if (ch === '}') {
if (braceNesting > 0) braceNesting--;
if (braceNesting === superSubDepth) {
superSubDepth = -1;
continue;
}
if (braceNesting === overbarDepth) {
overbarDepth = -1;
continue;
}
}
char_count++;
}
return char_count;
}
/** `wxString::Capitalize`: first character upper, the REST lower. */
const capitalize = (word: string): string =>
word.length === 0 ? word : word[0]!.toUpperCase() + word.slice(1).toLowerCase();
/**
* `TitleCaps` (common/string_utils.cpp:397-414).
*
* Splits on spaces, capitalizes each word, and rejoins with a single space.
* Because the join is `if( !result.IsEmpty() ) result += " "`, a leading empty
* word contributes nothing — a leading space is swallowed — while an interior
* one still gets its separator, so runs of spaces inside the string survive.
*/
export function titleCaps(str: string): string {
let result = '';
for (const word of wxStringSplit(str, ' ')) {
if (result !== '') result += ' ';
result += capitalize(word);
}
return result;
}
/**
* `InitialCaps` (common/string_utils.cpp:418-436): the first word
* capitalized, every later word lower-cased, single spaces between.
*/
export function InitialCaps(aString: string): string {
let result = '';
for (const word of wxStringSplit(aString, ' ')) {
if (result === '') result += capitalize(word);
else result += ` ${word.toLowerCase()}`;
}
return result;
}
/**
* `PrintableCharCount`: how many characters a string actually *prints*.
*
* Not `length`. KiCad's bitmap text understands three markup forms — `~{…}` for
* an overbar, `^{…}` and `_{…}` for super- and subscript — and the introducer
* and the braces that delimit them draw nothing. Tabs are dropped too, because
* bitmap text does not lay them out.
*
* It matters because the pad painter divides the pad's width by this count to
* choose a font size (`pcb_painter.cpp:1538, 1564`). Counting the markup makes
* the string look longer than it is and the text comes out smaller than KiCad
* draws it — for a net named `~{RESET}` by five characters, a third of its
* width.
*
* The nesting rules are upstream's, including the ones that look odd: an
* introducer only opens a group when a `{` immediately follows, only one
* overbar and one super/subscript group can be open at a time, and a `}` closes
* one only at the exact brace depth its group opened at. Anything else counts.
*/
export function printableCharCount(text: string): number {
let count = 0;
let overbarDepth = -1;
let superSubDepth = -1;
let braceNesting = 0;
for (let i = 0; i < text.length; i++) {
const ch = text[i]!;
if (ch === '\t') continue;
if ((ch === '^' || ch === '_') && superSubDepth === -1) {
if (text[i + 1] === '{') {
i++;
superSubDepth = braceNesting;
braceNesting++;
continue;
}
} else if (ch === '~' && overbarDepth === -1) {
if (text[i + 1] === '{') {
i++;
overbarDepth = braceNesting;
braceNesting++;
continue;
}
} else if (ch === '{') {
braceNesting++;
} else if (ch === '}') {
if (braceNesting > 0) braceNesting--;
if (braceNesting === superSubDepth) {
superSubDepth = -1;
continue;
}
if (braceNesting === overbarDepth) {
overbarDepth = -1;
continue;
}
}
count++;
}
return count;
}
/**
* `wxSplit( str, sep, escape )`, with wx's own default escape of `\\`.
*
* A port rather than `String.split`, because the two disagree in three ways
* that reach real net names, and `NETINFO_LIST::RebuildDisplayNetnames` depends
* on all three. Measured against wxWidgets 3.2 rather than read off the docs
* (`qa/probes/wxsplit_probe.cpp`):
*
* - **An empty string yields no parts at all**, not one empty part. `split`
* gives `['']`.
* - **The escape character suppresses a separator** and is consumed:
* `/Sheet\\/SDA` is two parts, the second `Sheet/SDA`. A backslash is
* reachable in a net name because `EscapeString( …, CTX_NETNAME )` escapes
* only `/` and drops newlines — it leaves `\\` alone.
* - A backslash anywhere else is an ordinary character and is kept.
*/
export function wxSplit(text: string, sep: string, escapeChar = '\\'): string[] {
if (text.length === 0) return [];
const out: string[] = [];
let current = '';
let prev = '';
for (const ch of text) {
if (ch === sep) {
if (prev === escapeChar && escapeChar !== '') {
// Drop the escape that is already in `current` and keep the separator
// as an ordinary character: wx rewrites its last character in place.
current = `${current.slice(0, -1)}${sep}`;
} else {
out.push(current);
current = '';
}
} else {
current += ch;
}
prev = ch;
}
out.push(current);
return out;
}
/**
* `fmt::format("{:.<precision>f}", value)` — C's `%f`, which `toFixed` is
* except that `toFixed` gives up on exponent form at 1e21 and `%f` never does.
*/
export function formatF(value: number, precision: number): string {
if (Number.isNaN(value)) return 'nan';
if (!Number.isFinite(value)) return value > 0 ? 'inf' : '-inf';
if (Math.abs(value) >= 1e21) {
const whole = BigInt(Math.trunc(value)).toString();
return precision > 0 ? `${whole}.${'0'.repeat(precision)}` : whole;
}
return value.toFixed(precision);
}
/**
* `FormatDouble2Str` (common/string_utils.cpp:1446): a double as a file
* writer prints it — `{:.10g}`, except a non-zero value at or below 0.0001,
* which takes `{:.16f}` with its trailing zeros removed so it never comes
* out in exponent form.
*/
export function FormatDouble2Str(value: number): string {
if (value !== 0.0 && Math.abs(value) <= 0.0001) {
let buf = formatF(value, 16);
// remove trailing zeros (and the decimal marker if needed)
while (buf.length > 0 && buf.endsWith('0')) buf = buf.slice(0, -1);
// if the value was really small we may have just stripped all the zeros
// after the decimal
if (buf.endsWith('.')) buf = buf.slice(0, -1);
return buf;
}
return formatG(value, 10);
}
/**
* `UIDouble2Str` (common/string_utils.cpp:1476): a double for the UI, the
* same `%.16f`-trimmed / `%.10g` choice as `FormatDouble2Str`.
*/
export function UIDouble2Str(aValue: number): string {
if (aValue !== 0.0 && Math.abs(aValue) <= 0.0001) {
// For these small values, %f works fine,
// and %g gives an exponent
let buf = formatF(aValue, 16);
while (buf.length > 1 && buf.endsWith('0')) buf = buf.slice(0, -1);
if (buf.endsWith('.') || buf.endsWith(',')) buf = buf.slice(0, -1);
return buf;
}
// For these values, %g works fine, and sometimes %f
// gives a bad value (try aValue = 1.222222222222, with %.16f format!)
return formatG(aValue, 10);
}
/** `GetDefaultVariantName()`: the name the default (no) variant shows as. */
export function GetDefaultVariantName(): string {
return '< Default >';
}
/** `SortVariantNames`: the default variant first, then natural order. */
export function SortVariantNames(aLhs: string, aRhs: string): number {
const defaultVariantName = GetDefaultVariantName();
if (aLhs === defaultVariantName && aRhs !== defaultVariantName) return -1;
if (aLhs !== defaultVariantName && aRhs === defaultVariantName) return 1;
return strNumCmp(aLhs, aRhs);
}
/**
* `IsURL( wxString )`: whether the string holds an http(s)/ftp/file URL.
*/
export function IsURL(aStr: string): boolean {
// The C++ runs ReplaceAll first, then Matches; the replacement leaves at least one
// match in the string whenever there was one, so the answer is the same.
const regex = /(https?|ftp|file):\/\/([-\w+&@#/%?=~|!:,.;]*[^.,:;<>\s¶])/i;
return regex.test(aStr);
}
/**
* `ConvertPathToFileUri( aPath, aProject )` (string_utils.cpp:1561): a path to a file or
* folder that exists (absolute, `${VAR}`-relative or `./`, `../`) gains a `file://`
* prefix; anything else, a URL included, comes back as given. \a aProject resolves the
* variables and anchors a relative path at the project.
*/
export function ConvertPathToFileUri(
aPath: string,
aProject: { TextVarResolver(aToken: OutStr): boolean; GetProjectPath(): string } | null = null,
): string {
if (aPath === '' || aPath === '~') return aPath;
const looksLikePath =
aPath.startsWith('/') ||
aPath.startsWith('${') ||
aPath.startsWith('./') ||
aPath.startsWith('../');
// Not a path, return unchanged (a URI with a scheme included)
if (!looksLikePath) return aPath;
// Resolve env vars
let resolved = aPath;
if (aProject) resolved = ResolveUriByEnvVars(aPath, (aToken) => aProject.TextVarResolver(aToken));
if (!resolved.startsWith('/') && aProject && aProject.GetProjectPath() !== '')
resolved = wxNormalizePath(`${aProject.GetProjectPath()}/${resolved}`);
// Only convert if the file actually exists
if (!wxFileExists(resolved) && !wxDirExists(resolved)) return aPath;
return `file://${aPath}`;
}
/**
* `AccumulateDescription( wxString& aDesc, const wxString& aItem )` (`string_utils.h:379`):
* append `aItem` to `aDesc`, comma-separated. Returns the accumulated string.
*/
export function AccumulateDescription(aDesc: string, aItem: string): string {
if (aDesc !== '') aDesc += ', ';
aDesc += aItem;
return aDesc;
}
/** `EscapeHTML( aString )` (common/string_utils.cpp:573). */
export function EscapeHTML(aString: string): string {
let converted = '';
for (const c of aString) {
if (c === '"') converted += '&quot;';
else if (c === "'") converted += '&apos;';
else if (c === '&') converted += '&amp;';
else if (c === '<') converted += '&lt;';
else if (c === '>') converted += '&gt;';
else converted += c;
}
return converted;
}
/** `wxDateTime::Now().FormatISOCombined( 'T' )`: local time, "YYYY-MM-DDTHH:MM:SS". */
export function GetISO8601CurrentDateTime(): string {
const d = new Date();
const p2 = (n: number): string => String(n).padStart(2, '0');
return `${d.getFullYear()}-${p2(d.getMonth() + 1)}-${p2(d.getDate())}T${p2(d.getHours())}:${p2(d.getMinutes())}:${p2(d.getSeconds())}`;
}
/** `ESCAPE_CONTEXT` (include/string_utils.h:55-67). */
export enum ESCAPE_CONTEXT {
CTX_NETNAME,
CTX_LIBID,
CTX_LEGACY_LIBID,
CTX_IPC,
CTX_QUOTED_STR,
CTX_JS_STR,
CTX_LINE,
CTX_CSV,
CTX_FILENAME,
CTX_NO_SPACE, // to replace spaces in names that do not accept spaces
}
/**
* `EscapeString( aSource, aContext )` (common/string_utils.cpp): the
* HTML-entity-reference-style encoding for the characters each context
* cannot hold.
*/
export function EscapeString(aSource: string, aContext: ESCAPE_CONTEXT): string {
let converted = '';
for (const c of aSource) {
if (aContext === ESCAPE_CONTEXT.CTX_NETNAME) {
if (c === '/') converted += '{slash}';
else if (c === '\n' || c === '\r')
converted += ''; // drop
else converted += c;
} else if (
aContext === ESCAPE_CONTEXT.CTX_LIBID ||
aContext === ESCAPE_CONTEXT.CTX_LEGACY_LIBID
) {
// We no longer escape '/' in LIB_IDs, but we used to
if (c === '/' && aContext === ESCAPE_CONTEXT.CTX_LEGACY_LIBID) converted += '{slash}';
else if (c === '\\') converted += '{backslash}';
else if (c === '<') converted += '{lt}';
else if (c === '>') converted += '{gt}';
else if (c === ':') converted += '{colon}';
else if (c === '"') converted += '{dblquote}';
else if (c === '\n' || c === '\r')
converted += ''; // drop
else converted += c;
} else if (aContext === ESCAPE_CONTEXT.CTX_IPC) {
if (c === '/') converted += '{slash}';
else if (c === ',') converted += '{comma}';
else if (c === '"') converted += '{dblquote}';
else converted += c;
} else if (aContext === ESCAPE_CONTEXT.CTX_QUOTED_STR) {
if (c === '"') converted += '{dblquote}';
else converted += c;
} else if (aContext === ESCAPE_CONTEXT.CTX_JS_STR) {
const code = c.codePointAt(0)!;
if (code >= 0x7f || c === "'" || c === '"' || c === '\\' || c === '(' || c === ')')
converted += `\\u${code.toString(16).toUpperCase().padStart(4, '0')}`;
else converted += c;
} else if (aContext === ESCAPE_CONTEXT.CTX_LINE) {
if (c === '\n' || c === '\r') converted += '{return}';
else converted += c;
} else if (aContext === ESCAPE_CONTEXT.CTX_FILENAME) {
if (c === '/') converted += '{slash}';
else if (c === '\\') converted += '{backslash}';
else if (c === '"') converted += '{dblquote}';
else if (c === '<') converted += '{lt}';
else if (c === '>') converted += '{gt}';
else if (c === '|') converted += '{bar}';
else if (c === ':') converted += '{colon}';
else if (c === '\t') converted += '{tab}';
else if (c === '\n' || c === '\r') converted += '{return}';
else converted += c;
} else if (aContext === ESCAPE_CONTEXT.CTX_NO_SPACE) {
if (c === ' ') converted += '{space}';
else converted += c;
} else if (aContext === ESCAPE_CONTEXT.CTX_CSV) {
if (c === ',') converted += '{comma}';
else if (c === '\n' || c === '\r') converted += '{return}';
else converted += c;
} else {
converted += c;
}
}
return converted;
}
/**
* `EscapedUTF8( const wxString& aString )` (common/string_utils.cpp): the string in double
* quotes with `"` and `\` backslash-escaped, compatible with ReadDelimitedText().
*
* Upstream replaces newlines on a copy it then does not use, so a newline passes through;
* kept.
*/
export function EscapedUTF8(aString: string): string {
let ret = '"';
for (const ch of aString) {
// this escaping strategy is designed to be compatible with ReadDelimitedText():
if (ch === '"') ret += '\\"';
else if (ch === '\\') ret += '\\\\';
else ret += ch;
}
ret += '"';
return ret;
}
/**
* `LinkifyHTML( aStr )` (common/string_utils.cpp:674-682): every URL in the
* (already escaped) text made an anchor. The anchor opens a new tab, which is
* what a link in a details pane must do in a page (upstream's HTML window
* hands it to the system browser).
*/
export function LinkifyHTML(aStr: string): string {
return aStr.replace(
/\b(https?|ftp|file):\/\/([-\w+&@#/%?=~|!:,.;]*[^.,:;<>()\s\u00b6])/gi,
(m) => `<a href="${m}" target="_blank" rel="noreferrer">${m}</a>`,
);
}
/** `illegalFileNameChars` (string_utils.cpp:55). */
const illegalFileNameChars = '\\/:"<>|*?';
/**
* `ReplaceIllegalFileNameChars( std::string& aName, int aReplaceChar )`
* (string_utils.cpp:1329): each character that cannot be in a file name
* becomes `aReplaceChar`, or `%xx` when that is 0. Returns the new name.
*/
export function ReplaceIllegalFileNameChars(aName: string, aReplaceChar = ''): string {
let result = '';
for (const c of aName) {
if (illegalFileNameChars.includes(c)) {
if (aReplaceChar) result += aReplaceChar;
else result += `%${c.charCodeAt(0).toString(16).padStart(2, '0')}`;
} else {
result += c;
}
}
return result;
}
/**
* `UnescapeHTML( aString )` (string_utils.cpp:599): numeric references and
* the five named ones; `&#0;` (or an unparsable one) is dropped.
*/
export function UnescapeHTML(aString: string): string {
// Construct regex: the named keys in std::map order
const regex = /&(#(\d*)|#x([a-zA-Z0-9]{4})|amp|apos|gt|lt|quot);/;
const c_replacements: Record<string, string> = {
quot: '"',
apos: "'",
amp: '&',
lt: '<',
gt: '>',
};
let result = '';
let str = aString;
for (let m = regex.exec(str); m; m = regex.exec(str)) {
result += str.slice(0, m.index);
const code = m[1] ?? '';
const codeDec = m[2] ?? '';
const codeHex = m[3] ?? '';
if (codeDec !== '' || codeHex !== '') {
let codeVal = 0;
if (codeDec !== '') codeVal = /^\d+$/.test(codeDec) ? Number.parseInt(codeDec, 10) : 0;
else if (codeHex !== '')
codeVal = /^[0-9a-fA-F]+$/.test(codeHex) ? Number.parseInt(codeHex, 16) : 0;
if (codeVal !== 0 && codeVal <= 0x10ffff) result += String.fromCodePoint(codeVal);
} else if (c_replacements[code] !== undefined) {
result += c_replacements[code];
}
str = str.slice(m.index + m[0].length);
}
result += str;
return result;
}
/** `RemoveHTMLTags( aInput )` (string_utils.cpp:665): every `<...>` removed. */
export function RemoveHTMLTags(aInput: string): string {
return aInput.replace(/<[^>]*>/g, '');
}
/**
* `NoPrintableChars` (string_utils.cpp): true when the string is empty once
* leading and trailing whitespace is trimmed.
*/
export function NoPrintableChars(aString: string): boolean {
return aString.trim() === '';
}
/**
* `AccumulateDescriptions( aItemCollection )` (string_utils.h): a comma-separated list built
* from a collection of strings.
*/
export function AccumulateDescriptions(aItemCollection: Iterable<string>): string {
let desc = '';
for (const item of aItemCollection) desc = AccumulateDescription(desc, item);
return desc;
}
/**
* `IsFullFileNameValid( aFullFilename )` (common/string_utils.cpp:61): false when the name holds a
* character `wxFileName::GetForbiddenChars()` forbids - on Unix only the NUL; '\\' and '/' are
* separators in a full path, so allowed.
*/
export function IsFullFileNameValid(aFullFilename: string): boolean {
return !aFullFilename.includes('\0');
}