{
  "$schema": "../../schemas/utility.schema.json",
  "kind": "utility",
  "name": "Arrays",
  "version": "1.0.0-draft.1",
  "purpose": "Arrays value operations. No hidden external Service communication.",
  "types": "types.json",
  "functions": {
    "size": {
      "parameters": [
        {
          "name": "array",
          "type": {
            "arrayOf": "core.data"
          },
          "required": true
        }
      ],
      "returns": "core.integer",
      "purpose": "Integer length.",
      "statementOnly": false
    },
    "contains": {
      "parameters": [
        {
          "name": "array",
          "type": {
            "arrayOf": "core.data"
          },
          "required": true
        },
        {
          "name": "value",
          "type": "core.data",
          "required": true
        }
      ],
      "returns": "core.boolean",
      "purpose": "Structural data membership.",
      "statementOnly": false
    },
    "slice": {
      "parameters": [
        {
          "name": "array",
          "type": {
            "arrayOf": "core.data"
          },
          "required": true
        },
        {
          "name": "start",
          "type": "core.integer",
          "required": true
        },
        {
          "name": "count",
          "type": "core.integer",
          "required": true
        }
      ],
      "returns": {
        "arrayOf": "core.data"
      },
      "purpose": "New array of the checked range.",
      "statementOnly": false
    },
    "map": {
      "parameters": [
        {
          "name": "array",
          "type": {
            "arrayOf": "core.data"
          },
          "required": true
        },
        {
          "name": "helper",
          "type": "core.Mapper",
          "required": true
        }
      ],
      "returns": {
        "arrayOf": "core.data"
      },
      "purpose": "New array of helper(item) results, in order.",
      "statementOnly": false
    },
    "filter": {
      "parameters": [
        {
          "name": "array",
          "type": {
            "arrayOf": "core.data"
          },
          "required": true
        },
        {
          "name": "helper",
          "type": "core.Predicate",
          "required": true
        }
      ],
      "returns": {
        "arrayOf": "core.data"
      },
      "purpose": "New array of items for which helper(item) returns true.",
      "statementOnly": false
    },
    "sort": {
      "parameters": [
        {
          "name": "array",
          "type": {
            "arrayOf": "core.data"
          },
          "required": true
        },
        {
          "name": "helper",
          "type": "core.Comparator",
          "required": true
        }
      ],
      "returns": {
        "arrayOf": "core.data"
      },
      "purpose": "New stable ordered array; helper(left, right) returns negative/zero/positive integer.",
      "statementOnly": false
    }
  },
  "rules": [
    "Arrays are ordered typed data. size returns the count. contains uses structural equality. slice checks its bounds.",
    "map, filter and sort accept named helpers. filter requires boolean results; sort requires a signed integer comparison and is stable.",
    "Operations return new containers. Items retain their data references unless explicitly copied. The array add method is a separate statement-only mutation."
  ]
}
