runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/cond.js

@@ -0,0 +1,157 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "cond",
+    "category": "math/linalg/solve",
+    "keywords": [
+        "cond",
+        "condition number",
+        "norm",
+        "linear algebra",
+        "gpu"
+    ],
+    "summary": "Compute the matrix condition number with MATLAB-compatible norm choices.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/cond.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "RunMat gathers GPU inputs to the host when a provider does not expose a native cond hook, then re-uploads the scalar result to preserve residency."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::linalg::solve::cond::tests",
+        "gpu": "builtins::math::linalg::solve::cond::tests::cond_gpu_round_trip_matches_cpu",
+        "wgpu": "builtins::math::linalg::solve::cond::tests::cond_wgpu_matches_cpu"
+    },
+    "description": "`k = cond(A)` returns the condition number of matrix `A`, measuring how sensitive solutions to linear systems are to small perturbations in `A` or in the right-hand side. By default, `cond` computes the 2-norm condition number using the ratio of the largest to smallest singular values.",
+    "behaviors": [
+        "`cond(A)` and `cond(A, 2)` use the singular values of `A`, so rectangular matrices are supported.",
+        "`cond(A, 1)`, `cond(A, Inf)`, and `cond(A, 'fro')` require a square, invertible matrix and use the definition `norm(A, p) * norm(inv(A), p)` with MATLAB's norm semantics.",
+        "Scalars behave like 1x1 matrices. Non-zero scalars have condition number `1`, while `cond(0) = Inf`.",
+        "Empty matrices return `0`, matching MATLAB's convention.",
+        "Singular or rank-deficient matrices return `Inf`.",
+        "Complex inputs are handled in full complex arithmetic."
+    ],
+    "examples": [
+        {
+            "description": "Condition number of the identity matrix",
+            "input": "A = eye(3);\nk = cond(A)",
+            "output": "k = 1"
+        },
+        {
+            "description": "Diagnosing an ill-conditioned diagonal matrix",
+            "input": "D = diag([1, 1e-8]);\nk = cond(D)",
+            "output": "k = 1.0e+8"
+        },
+        {
+            "description": "Condition number of a rectangular matrix (2-norm)",
+            "input": "A = [1 0; 0 1; 1 1];\nk = cond(A, 2)",
+            "output": "k = 1.7321"
+        },
+        {
+            "description": "Using a different norm specification",
+            "input": "A = [4 -1; 2 3];\nk1 = cond(A, 1)\nkInf = cond(A, Inf)",
+            "output": "k1   = 2.1429\nkInf = 2.1429"
+        },
+        {
+            "description": "Complex-valued matrices",
+            "input": "A = [1+2i 0; 3i 4-1i];\nk = cond(A)",
+            "output": "k = 3.0327"
+        },
+        {
+            "description": "Empty inputs and GPU residency",
+            "input": "G = gpuArray([]);      % Empty 0x0 matrix on the GPU\nk = cond(G);           % Returns 0 and keeps residency when possible\nresult = gather(k)",
+            "output": "result = 0"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What does a large condition number mean?",
+            "answer": "Large condition numbers (>> 1) indicate that small perturbations in the input can produce large changes in the solution of a linear system involving `A`. Values close to `1` indicate a well- conditioned matrix."
+        },
+        {
+            "question": "Why does `cond` return `Inf` for singular matrices?",
+            "answer": "Singular matrices have at least one zero singular value (or an undefined inverse), so the condition number is mathematically infinite. RunMat mirrors MATLAB and returns `Inf` in these cases."
+        },
+        {
+            "question": "Does `cond` support rectangular matrices?",
+            "answer": "Yes for the default 2-norm: `cond(A)` uses singular values and accepts any two-dimensional matrix. Norms `1`, `Inf`, and `'fro'` require a square, invertible matrix because they are defined using the matrix inverse."
+        },
+        {
+            "question": "How does `cond` handle empty matrices?",
+            "answer": "All norm choices return `0` for empty matrices (`0x0`), matching MATLAB's behaviour."
+        },
+        {
+            "question": "Will calling `cond` move my data off the GPU?",
+            "answer": "Only when the active provider lacks a dedicated implementation. In that case RunMat gathers the data, computes the scalar on the host, and uploads it back so subsequent GPU operations still see a device-resident value."
+        }
+    ],
+    "links": [
+        {
+            "label": "rcond",
+            "url": "./rcond"
+        },
+        {
+            "label": "inv",
+            "url": "./inv"
+        },
+        {
+            "label": "pinv",
+            "url": "./pinv"
+        },
+        {
+            "label": "linsolve",
+            "url": "./linsolve"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "det",
+            "url": "./det"
+        },
+        {
+            "label": "norm",
+            "url": "./norm"
+        },
+        {
+            "label": "rank",
+            "url": "./rank"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/math/linalg/solve/cond.rs",
+        "url": "crates/runmat-runtime/src/builtins/math/linalg/solve/cond.rs"
+    },
+    "gpu_residency": "```matlab:runnable\nG = gpuArray([]);      % Empty 0x0 matrix on the GPU\nk = cond(G);           % Returns 0 and keeps residency when possible\nresult = gather(k);\n```\nExpected output:\n```matlab\nresult = 0\n```",
+    "gpu_behavior": [
+        "When the input already lives on a GPU, RunMat first looks for an acceleration provider that exposes the custom `cond` hook registered below. Current providers gather the matrix to host memory, reuse the shared CPU implementation, and then re-upload the scalar so downstream GPU computations preserve residency. This mirrors MATLAB semantics while keeping the user-facing API uniform."
+    ],
+    "key": "cond",
+    "slug": "cond",
+    "categoryPath": [
+        "math",
+        "linalg",
+        "solve"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=cond.js.map

package/dist/generated/builtins/cond.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cond.js","sourceRoot":"","sources":["../../../src/generated/builtins/cond.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/conj.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=conj.d.ts.map

package/dist/generated/builtins/conj.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conj.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/conj.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAgOjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/conj.js

@@ -0,0 +1,229 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "conj",
+    "category": "math/elementwise",
+    "keywords": [
+        "conj",
+        "complex conjugate",
+        "complex",
+        "elementwise",
+        "gpu"
+    ],
+    "summary": "Compute the complex conjugate of scalars, vectors, matrices, or N-D tensors.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Uses the provider's unary_conj hook for real-valued tensors; complex tensors gather to the host today while native complex kernels are still in flight. Fusion treats conj as a pass-through for real data so pipelines stay resident on GPU."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::conj::tests",
+        "integration": "builtins::math::elementwise::conj::tests::conj_gpu_provider_roundtrip"
+    },
+    "description": "`conj(x)` negates the imaginary component of every element in `x`; real values are returned unchanged. The builtin mirrors MathWorks MATLAB semantics for scalars, vectors, matrices, and N-D tensors.",
+    "behaviors": [
+        "Complex scalars and arrays have their imaginary components multiplied by `-1`; when a result has no imaginary part it collapses to a real scalar or tensor just like MATLAB.",
+        "Purely real numeric inputs (double, single, integer) are returned unchanged.",
+        "Logical arrays are promoted to double precision with `true → 1.0` and `false → 0.0`.",
+        "Character arrays are promoted to double precision containing their Unicode code points; the Conjugate operation does not alter the codes because they are real-valued.",
+        "String arrays are not supported and raise an error."
+    ],
+    "examples": [
+        {
+            "description": "Complex conjugate of a scalar value in MATLAB",
+            "input": "z = 3 + 4i;\nresult = conj(z)",
+            "output": "result = 3 - 4i"
+        },
+        {
+            "description": "Apply conj to every element of a complex matrix",
+            "input": "Z = [1+2i, 4-3i; -5+0i, 7+8i];\nC = conj(Z)",
+            "output": "C =\n   1 - 2i   4 + 3i\n  -5 + 0i   7 - 8i"
+        },
+        {
+            "description": "Ensure conj leaves real inputs unchanged",
+            "input": "data = [-2.5 0 9.75];\nunchanged = conj(data)",
+            "output": "unchanged = [-2.5 0 9.75]"
+        },
+        {
+            "description": "Use conj on logical masks converted to doubles",
+            "input": "mask = logical([0 1 0; 1 1 0]);\nnumeric = conj(mask)",
+            "output": "numeric =\n     0     1     0\n     1     1     0"
+        },
+        {
+            "description": "Convert MATLAB char arrays to numeric codes with conj",
+            "input": "chars = 'RunMat';\ncodes = conj(chars)\noutputClass = class(codes)",
+            "output": "codes = [82 117 110 77 97 116];\noutputClass = 'double'"
+        },
+        {
+            "description": "Compute conjugate on GPU-resident arrays",
+            "input": "G = rand(4096, 256, \"gpuArray\");\nH = conj(G)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `conj` change purely real inputs?",
+            "answer": "No. Real values (including logical and character data) are returned unchanged, although logical and character inputs become double precision arrays just like in MATLAB."
+        },
+        {
+            "question": "How does `conj` handle complex zeros?",
+            "answer": "`conj(0 + 0i)` returns `0`. Imaginary zeros remain zero after negation."
+        },
+        {
+            "question": "Can I call `conj` on string arrays?",
+            "answer": "No. The builtin only accepts numeric, logical, or character inputs. Convert strings with `double(string)` if you need numeric codes."
+        },
+        {
+            "question": "Does `conj` allocate a new array?",
+            "answer": "Yes. The builtin materialises a new tensor (or scalar). Fusion may eliminate the allocation when the surrounding expression can be fused safely, especially when the data stays on the GPU."
+        },
+        {
+            "question": "What happens on the GPU without `unary_conj`?",
+            "answer": "RunMat gathers the tensor to host memory, applies the CPU semantics (including complex negation), and allows later operations to re-upload data if advantageous."
+        },
+        {
+            "question": "Is GPU execution numerically identical to CPU?",
+            "answer": "Yes. For real tensors the result is an exact copy; the conjugate matches CPU results bit-for-bit for supported precisions."
+        },
+        {
+            "question": "Does `conj` participate in fusion?",
+            "answer": "Yes. The fusion planner can fold `conj` into neighbouring elementwise kernels, letting providers keep tensors on the GPU whenever possible."
+        }
+    ],
+    "links": [
+        {
+            "label": "real",
+            "url": "./real"
+        },
+        {
+            "label": "imag",
+            "url": "./imag"
+        },
+        {
+            "label": "abs",
+            "url": "./abs"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "angle",
+            "url": "./angle"
+        },
+        {
+            "label": "double",
+            "url": "./double"
+        },
+        {
+            "label": "exp",
+            "url": "./exp"
+        },
+        {
+            "label": "expm1",
+            "url": "./expm1"
+        },
+        {
+            "label": "factorial",
+            "url": "./factorial"
+        },
+        {
+            "label": "gamma",
+            "url": "./gamma"
+        },
+        {
+            "label": "hypot",
+            "url": "./hypot"
+        },
+        {
+            "label": "ldivide",
+            "url": "./ldivide"
+        },
+        {
+            "label": "log",
+            "url": "./log"
+        },
+        {
+            "label": "log10",
+            "url": "./log10"
+        },
+        {
+            "label": "log1p",
+            "url": "./log1p"
+        },
+        {
+            "label": "log2",
+            "url": "./log2"
+        },
+        {
+            "label": "minus",
+            "url": "./minus"
+        },
+        {
+            "label": "plus",
+            "url": "./plus"
+        },
+        {
+            "label": "pow2",
+            "url": "./pow2"
+        },
+        {
+            "label": "power",
+            "url": "./power"
+        },
+        {
+            "label": "rdivide",
+            "url": "./rdivide"
+        },
+        {
+            "label": "sign",
+            "url": "./sign"
+        },
+        {
+            "label": "single",
+            "url": "./single"
+        },
+        {
+            "label": "sqrt",
+            "url": "./sqrt"
+        },
+        {
+            "label": "times",
+            "url": "./times"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/elementwise/conj.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/conj.rs"
+    },
+    "gpu_residency": "You usually do **not** need to call `gpuArray` explicitly. RunMat's fusion planner and Accelerate layer manage residency and offload decisions automatically, keeping tensors on the GPU whenever device execution is beneficial. Explicit `gpuArray` and `gather` remain available for MATLAB compatibility or fine-grained residency control.",
+    "gpu_behavior": [
+        "**Hook available:** Real tensors stay on the GPU and are processed in-place (both the in-process provider used for tests and the WGPU provider expose this path).",
+        "**Fusion and auto-offload:** Because `conj` is tagged as an elementwise unary builtin, the fusion planner treats it as a pass-through for real-valued kernels. Native auto-offload therefore keeps fused expressions resident on the GPU whenever the surrounding ops are profitable.",
+        "**Hook missing or complex input:** RunMat gathers the data to host memory, applies the CPU semantics (including complex negation and type promotion), and returns the result. The planner may re-upload tensors later if profitable.\n\nComplex tensors are currently materialised on the host because GPU-side complex layouts are still under development. Providers can add native complex kernels later without changing this builtin."
+    ],
+    "key": "conj",
+    "slug": "conj",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=conj.js.map

package/dist/generated/builtins/conj.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conj.js","sourceRoot":"","sources":["../../../src/generated/builtins/conj.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/containers.Map.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=containers.Map.d.ts.map

package/dist/generated/builtins/containers.Map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"containers.Map.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/containers.Map.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAiIjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/containers.Map.js

@@ -0,0 +1,134 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "containers.Map",
+    "category": "containers/map",
+    "keywords": [
+        "containers.Map",
+        "map",
+        "dictionary",
+        "hash map",
+        "lookup"
+    ],
+    "summary": "Create MATLAB-compatible dictionary objects that map keys to values.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/containers.map-class.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Map storage lives on the host. GPU inputs are gathered when constructing maps or fetching values."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::containers::map::containers_map::tests"
+    },
+    "description": "`containers.Map` builds dictionary objects that associate unique keys with values. Keys can be character vectors, string scalars, or numeric scalars (./logical). Values default to MATLAB's `'any'` semantics, letting you store arbitrary scalars, arrays, structs, or handle objects. Each map tracks insertion order, supports key-based indexing, and exposes methods such as `keys`, `values`, `isKey`, and `remove`.",
+    "behaviors": [
+        "Keys must be unique. Constructing a map or assigning a key that already exists overwrites the stored value (matching MATLAB's behaviour).",
+        "The `KeyType`, `ValueType`, and `Count` properties are readable with dot-indexing.",
+        "`map(key)` returns the associated value; requesting a missing key raises the MATLAB-compatible error *\"The specified key is not present in this container.\"*",
+        "Assignments of the form `map(key) = value` update or insert entries.",
+        "Methods `keys(map)`, `values(map)`, `isKey(map, keySpec)`, and `remove(map, keySpec)` are fully compatible. When `keySpec` is a cell or string array, the result matches MATLAB's shape.",
+        "GPU tensors presented as values are gathered to host memory before insertion. When values or keys arrive on the GPU and need to be expanded element-wise (for example, vector-valued constructor arguments), RunMat downloads them to materialise individual scalars.",
+        "The `'UniformValues'` flag is accepted; when `true`, RunMat validates that every inserted value has the same MATLAB class. Retrieval still returns a cell array, matching MATLAB behaviour when the value type is `'any'`."
+    ],
+    "examples": [
+        {
+            "description": "Create an empty map with default types",
+            "input": "m = containers.Map();\nm.KeyType\nm.ValueType\nm.Count",
+            "output": "ans =\n    'char'\nans =\n    'any'\nans =\n     0"
+        },
+        {
+            "description": "Build a map from paired cell arrays",
+            "input": "keys = {'apple', 'pear', 'banana'};\nvals = {42, [1 2 3], true};\nfruit = containers.Map(keys, vals);\nenergy = fruit('apple')",
+            "output": "energy =\n    42"
+        },
+        {
+            "description": "Update an existing key and add a new one",
+            "input": "fruit('apple') = 99;\nfruit('peach') = struct('ripe', true)",
+            "output": "fruit('apple')\nans =\n    99"
+        },
+        {
+            "description": "Query keys, values, and membership",
+            "input": "allKeys = keys(fruit);\nallVals = values(fruit);\nmask = isKey(fruit, {'apple', 'durian'})",
+            "output": "allKeys =\n  1×4 cell array\n    {'apple'}    {'pear'}    {'banana'}    {'peach'}\n\nallVals =\n  1×4 cell array\n    {[99]}    {[1 2 3]}    {[1]}    {1×1 struct}\n\nmask =\n  1×2 logical array\n     1     0"
+        },
+        {
+            "description": "Remove keys and inspect the map length",
+            "input": "remove(fruit, {'pear', 'banana'});\nn = length(fruit);\nremaining = keys(fruit)",
+            "output": "n =\n     2\nremaining =\n  1×2 cell array\n    {'apple'}    {'peach'}"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Which key types are supported?",
+            "answer": "`containers.Map` accepts `'char'`, `'string'`, `'double'`, `'single'`, `'int32'`, `'uint32'`, `'int64'`, `'uint64'`, and `'logical'`. Keys supplied during construction or assignment are coerced to the declared type and must be scalar."
+        },
+        {
+            "question": "What happens when I provide duplicate keys at construction time?",
+            "answer": "Duplicate keys raise the same error as MATLAB: *\"Duplicate key name was provided.\"* During assignment, duplicate keys overwrite the existing value."
+        },
+        {
+            "question": "Does RunMat honour `'UniformValues', true`?",
+            "answer": "Yes. When this option is set, RunMat enforces that each inserted value matches the MATLAB class of the first value. Retrieval still uses cell arrays, mirroring MATLAB when `'ValueType'` is `'any'`."
+        },
+        {
+            "question": "Can I store GPU arrays as map values?",
+            "answer": "Yes. RunMat automatically gathers GPU tensors to host memory before inserting them so it can apply the same validation and coercion rules as MATLAB. This ensures constructors that rely on vector expansion continue to produce predictable host-side values."
+        },
+        {
+            "question": "How does `length(map)` behave?",
+            "answer": "`length(map)` returns the number of stored keys (identical to the `Count` property). `size(map)` remains `[1 1]`, matching MATLAB's handle semantics."
+        },
+        {
+            "question": "What error is raised when a key is missing?",
+            "answer": "Indexing a missing key produces the MATLAB-compatible error message *\"The specified key is not present in this container.\"*"
+        },
+        {
+            "question": "Does the map preserve insertion order?",
+            "answer": "Yes. `keys(map)` and `values(map)` return entries in the order they were first inserted, matching the behaviour of MATLAB's `containers.Map`."
+        },
+        {
+            "question": "Is the implementation thread-safe?",
+            "answer": "Yes. A global read/write lock guards the backing storage so concurrent reads are allowed while write operations remain exclusive."
+        },
+        {
+            "question": "How do I remove every entry?",
+            "answer": "Call `remove(map, keys(map))` or reassign a new empty map. RunMat currently keeps the internal storage until the handle is cleared, matching MATLAB's lifetime semantics."
+        },
+        {
+            "question": "What happens if I pass a non-scalar key?",
+            "answer": "Keys must be scalar. Passing vectors, matrices, or nested cell arrays of keys raises a descriptive error pointing to the offending argument."
+        }
+    ],
+    "links": [
+        {
+            "label": "length",
+            "url": "./length"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/containers/map/containers.map.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/containers/map/containers.map.rs"
+    },
+    "gpu_behavior": [
+        "The data structure itself resides on the CPU. When you construct a map with GPU arrays, RunMat first downloads the inputs so it can perform MATLAB-compatible validation and coercion. Maps never retain device buffers internally, so the GPU provider does not need to implement special hooks for this builtin."
+    ],
+    "key": "containers.map",
+    "slug": "containers.map",
+    "categoryPath": [
+        "containers",
+        "map"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=containers.Map.js.map

package/dist/generated/builtins/containers.Map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containers.Map.js","sourceRoot":"","sources":["../../../src/generated/builtins/containers.Map.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,gBAAgB;IACzB,UAAU,EAAE,gBAAgB;IAC5B,UAAU,EAAE;QACV,gBAAgB;QAChB,KAAK;QACL,YAAY;QACZ,UAAU;QACV,QAAQ;KACT;IACD,SAAS,EAAE,sEAAsE;IACjF,YAAY,EAAE;QACZ,qEAAqE;KACtE;IACD,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,mGAAmG;KAC7G;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,kDAAkD;KAC3D;IACD,aAAa,EAAE,6ZAA6Z;IAC5a,WAAW,EAAE;QACX,2IAA2I;QAC3I,oFAAoF;QACpF,gKAAgK;QAChK,sEAAsE;QACtE,0LAA0L;QAC1L,uQAAuQ;QACvQ,4NAA4N;KAC7N;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,wCAAwC;YACvD,OAAO,EAAE,wDAAwD;YACjE,QAAQ,EAAE,oDAAoD;SAC/D;QACD;YACE,aAAa,EAAE,qCAAqC;YACpD,OAAO,EAAE,gIAAgI;YACzI,QAAQ,EAAE,kBAAkB;SAC7B;QACD;YACE,aAAa,EAAE,0CAA0C;YACzD,OAAO,EAAE,6DAA6D;YACtE,QAAQ,EAAE,+BAA+B;SAC1C;QACD;YACE,aAAa,EAAE,oCAAoC;YACnD,OAAO,EAAE,4FAA4F;YACrG,QAAQ,EAAE,iNAAiN;SAC5N;QACD;YACE,aAAa,EAAE,wCAAwC;YACvD,OAAO,EAAE,iFAAiF;YAC1F,QAAQ,EAAE,wEAAwE;SACnF;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,gCAAgC;YAC5C,QAAQ,EAAE,4OAA4O;SACvP;QACD;YACE,UAAU,EAAE,kEAAkE;YAC9E,QAAQ,EAAE,uJAAuJ;SAClK;QACD;YACE,UAAU,EAAE,6CAA6C;YACzD,QAAQ,EAAE,uMAAuM;SAClN;QACD;YACE,UAAU,EAAE,uCAAuC;YACnD,QAAQ,EAAE,gQAAgQ;SAC3Q;QACD;YACE,UAAU,EAAE,gCAAgC;YAC5C,QAAQ,EAAE,uJAAuJ;SAClK;QACD;YACE,UAAU,EAAE,6CAA6C;YACzD,QAAQ,EAAE,+HAA+H;SAC1I;QACD;YACE,UAAU,EAAE,wCAAwC;YACpD,QAAQ,EAAE,+IAA+I;SAC1J;QACD;YACE,UAAU,EAAE,oCAAoC;YAChD,QAAQ,EAAE,mIAAmI;SAC9I;QACD;YACE,UAAU,EAAE,8BAA8B;YAC1C,QAAQ,EAAE,2KAA2K;SACtL;QACD;YACE,UAAU,EAAE,0CAA0C;YACtD,QAAQ,EAAE,8IAA8I;SACzJ;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,uEAAuE;QAChF,KAAK,EAAE,oHAAoH;KAC5H;IACD,cAAc,EAAE;QACd,oTAAoT;KACrT;IACD,KAAK,EAAE,gBAAgB;IACvB,MAAM,EAAE,gBAAgB;IACxB,cAAc,EAAE;QACd,YAAY;QACZ,KAAK;KACN;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/contains.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=contains.d.ts.map

package/dist/generated/builtins/contains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contains.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/contains.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAgJjB,CAAC;AAEF,eAAe,UAAU,CAAC"}