{
  "$schema": "../cases.schema.json",
  "format": 1,
  "domain": "areaCode",
  "title": {
    "en": "Area code (DDD)",
    "pt-BR": "DDD"
  },
  "functions": [
    {
      "id": "areaCode.getByMunicipalityCode",
      "level": "extended",
      "summary": "Gets the DDD (area code) in force for a Brazilian municipality, from its 7-digit IBGE code.",
      "description": "Returns the DDD (area code, the Código Nacional of the Plano Geral de Numeração) that a municipality dials, given its 7-digit IBGE code.\n\n- `code` is read as `municipality.getByCode` reads it: a string with every non-digit removed, or a non-negative integer.\n- Each of the 5,571 municipalities has exactly one DDD, so `null` only means that the code is not a municipality.\n- A DDD mostly follows state lines. The exceptions: 61, the DDD of Brasília, also covers 12 municipalities of Goiás. Porto União (SC) dials 42, Rio Negro (PR) dials 47 and Barracão (PR) dials 49.\n- `areaCode.getInfo` gives the state and region the DDD is seated in.\n- The table comes from the Anatel Códigos Nacionais file of 21/09/2026, rows in force only.",
      "params": [
        {
          "name": "code",
          "type": "string | number"
        }
      ],
      "returns": "number?",
      "cases": [
        {
          "id": "areaCode.getByMunicipalityCode#[\"3550308\"]",
          "args": [
            "3550308"
          ],
          "expect": {
            "returns": 11
          },
          "note": "from the maintainer briefing, #597"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[\"4122305\"]",
          "args": [
            "4122305"
          ],
          "expect": {
            "returns": 47
          },
          "note": "from the maintainer briefing, #597: Rio Negro (PR) dials the DDD of Santa Catarina"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[\"3509502\"]",
          "args": [
            "3509502"
          ],
          "expect": {
            "returns": 19
          },
          "note": "JavaScript's own test: should return the DDD of a municipality"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[\"3304557\"]",
          "args": [
            "3304557"
          ],
          "expect": {
            "returns": 21
          },
          "note": "JavaScript's own test: should return the DDD of a municipality"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[\"1200401\"]",
          "args": [
            "1200401"
          ],
          "expect": {
            "returns": 68
          },
          "note": "JavaScript's own test: should return the DDD of a municipality"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[\"2605459\"]",
          "args": [
            "2605459"
          ],
          "expect": {
            "returns": 81
          },
          "note": "JavaScript's own test: should return the DDD of a municipality"
        },
        {
          "id": "areaCode.getByMunicipalityCode#number",
          "args": [
            3518800
          ],
          "expect": {
            "returns": 11
          },
          "note": "JavaScript's own test: should accept a number"
        },
        {
          "id": "areaCode.getByMunicipalityCode#masked",
          "args": [
            " 355-030-8 "
          ],
          "expect": {
            "returns": 11
          },
          "note": "JavaScript's own test: should strip non-digit characters from a string"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[\"3550308 SP\"]",
          "args": [
            "3550308 SP"
          ],
          "expect": {
            "returns": 11
          },
          "note": "JavaScript's own test: should read the digits of a string, as getMunicipalityByCode does"
        },
        {
          "id": "areaCode.getByMunicipalityCode#brasilia",
          "args": [
            "5300108"
          ],
          "expect": {
            "returns": 61
          },
          "note": "JavaScript's own test: should give DDD 61 to Brasília and to the municipalities of Goiás around it"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[\"5212501\"]",
          "args": [
            "5212501"
          ],
          "expect": {
            "returns": 61
          },
          "note": "JavaScript's own test: should give DDD 61 to Brasília and to the municipalities of Goiás around it"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[\"5222203\"]",
          "args": [
            "5222203"
          ],
          "expect": {
            "returns": 61
          },
          "note": "JavaScript's own test: should give DDD 61 to Brasília and to the municipalities of Goiás around it"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[\"4213609\"]",
          "args": [
            "4213609"
          ],
          "expect": {
            "returns": 42
          },
          "note": "JavaScript's own test: should give the neighboring state's DDD to the three municipalities that dial it: Porto União (SC)"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[\"4102604\"]",
          "args": [
            "4102604"
          ],
          "expect": {
            "returns": 49
          },
          "note": "JavaScript's own test: should give the neighboring state's DDD to the three municipalities that dial it: Barracão (PR)"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[\"0000000\"]",
          "args": [
            "0000000"
          ],
          "expect": {
            "returns": null
          },
          "note": "JavaScript's own test: should return null for a code that is not a municipality"
        },
        {
          "id": "areaCode.getByMunicipalityCode#too-short",
          "args": [
            "355030"
          ],
          "expect": {
            "returns": null
          },
          "note": "JavaScript's own test: should return null for a code that is not a municipality"
        },
        {
          "id": "areaCode.getByMunicipalityCode#too-long",
          "args": [
            "35503080"
          ],
          "expect": {
            "returns": null
          }
        },
        {
          "id": "areaCode.getByMunicipalityCode#empty",
          "args": [
            ""
          ],
          "expect": {
            "returns": null
          },
          "note": "JavaScript's own test: should return null for a code that is not a municipality"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[\"SP\"]",
          "args": [
            "SP"
          ],
          "expect": {
            "returns": null
          },
          "note": "JavaScript's own test: should return null for a string without digits"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[-3550308]",
          "args": [
            -3550308
          ],
          "expect": {
            "returns": null
          },
          "note": "JavaScript's own test: should return null for a negative or fractional number"
        },
        {
          "id": "areaCode.getByMunicipalityCode#[355030.8]",
          "args": [
            355030.8
          ],
          "expect": {
            "returns": null
          },
          "note": "JavaScript's own test: should return null for a negative or fractional number"
        }
      ]
    },
    {
      "id": "areaCode.getInfo",
      "level": "extended",
      "summary": "Gets the state (and its region) that a Brazilian DDD (area code) belongs to.",
      "description": "Returns the state and region that a DDD (area code) belongs to, among the 67 DDDs in use under the Anatel Plano Geral de Numeração.\n\n- `areaCode` may be a string or a non-negative integer.\n- A string has every character that is not a digit removed first, as in 2.4.0: `\"(0xx11)\"` and `\" 11 \"` resolve to 11.\n- The result carries the DDD, the state it is seated in (code and name), its region (code and name) and every state it serves.\n- The seat is the state of the city the code was allocated around, not necessarily the state with most of its municipalities: DDD 61 is seated in DF, which holds only 1 of its 13 municipalities (Brasília).\n- Four DDDs straddle a state border (61, 42, 47 and 49). For these, the list of states also has the other state, with the seat first: 61 gives `DF, GO`, 42 gives `PR, SC`, 47 and 49 give `SC, PR`.\n- Returns `null` for a DDD not in use, a negative or non-integer number, or anything else.",
      "params": [
        {
          "name": "areaCode",
          "type": "string | number"
        }
      ],
      "returns": "AreaCodeInfo?",
      "cases": [
        {
          "id": "areaCode.getInfo#[\"11\"]",
          "args": [
            "11"
          ],
          "expect": {
            "returns": {
              "areaCode": 11,
              "stateCode": "SP",
              "stateName": "São Paulo",
              "regionCode": "SE",
              "regionName": "Sudeste",
              "stateCodes": [
                "SP"
              ]
            }
          }
        },
        {
          "id": "areaCode.getInfo#number",
          "args": [
            11
          ],
          "expect": {
            "returns": {
              "areaCode": 11,
              "stateCode": "SP",
              "stateName": "São Paulo",
              "regionCode": "SE",
              "regionName": "Sudeste",
              "stateCodes": [
                "SP"
              ]
            }
          }
        },
        {
          "id": "areaCode.getInfo#distrito-federal",
          "args": [
            "61"
          ],
          "expect": {
            "returns": {
              "areaCode": 61,
              "stateCode": "DF",
              "stateName": "Distrito Federal",
              "regionCode": "CO",
              "regionName": "Centro-Oeste",
              "stateCodes": [
                "DF",
                "GO"
              ]
            }
          }
        },
        {
          "id": "areaCode.getInfo#multi-state",
          "args": [
            42
          ],
          "expect": {
            "returns": {
              "areaCode": 42,
              "stateCode": "PR",
              "stateName": "Paraná",
              "regionCode": "S",
              "regionName": "Sul",
              "stateCodes": [
                "PR",
                "SC"
              ]
            }
          }
        },
        {
          "id": "areaCode.getInfo#[\"00\"]",
          "args": [
            "00"
          ],
          "expect": {
            "returns": null
          }
        },
        {
          "id": "areaCode.getInfo#unassigned",
          "args": [
            "20"
          ],
          "expect": {
            "returns": null
          }
        },
        {
          "id": "areaCode.getInfo#empty",
          "args": [
            ""
          ],
          "expect": {
            "returns": null
          }
        },
        {
          "id": "areaCode.getInfo#[\"68\"]",
          "args": [
            "68"
          ],
          "expect": {
            "returns": {
              "areaCode": 68,
              "stateCode": "AC",
              "stateName": "Acre",
              "regionCode": "N",
              "regionName": "Norte",
              "stateCodes": [
                "AC"
              ]
            }
          },
          "note": "JavaScript's own test: should resolve DDD 68 to Acre, Norte"
        },
        {
          "id": "areaCode.getInfo#[-11]",
          "args": [
            -11
          ],
          "expect": {
            "returns": null
          },
          "note": "JavaScript's own test: should return null for a negative number, not read it as the DDD 11"
        },
        {
          "id": "areaCode.getInfo#[1.1]",
          "args": [
            1.1
          ],
          "expect": {
            "returns": null
          },
          "note": "JavaScript's own test: should return null for a fractional number, not read it as the DDD 11"
        },
        {
          "id": "areaCode.getInfo#[\"(0xx11)\"]",
          "args": [
            "(0xx11)"
          ],
          "expect": {
            "returns": {
              "areaCode": 11,
              "stateCode": "SP",
              "stateName": "São Paulo",
              "regionCode": "SE",
              "regionName": "Sudeste",
              "stateCodes": [
                "SP"
              ]
            }
          },
          "note": "from the maintainer briefing, #596: every non-digit is removed from a string, as in 2.4.0"
        },
        {
          "id": "areaCode.getInfo#[\" 11 \"]",
          "args": [
            " 11 "
          ],
          "expect": {
            "returns": {
              "areaCode": 11,
              "stateCode": "SP",
              "stateName": "São Paulo",
              "regionCode": "SE",
              "regionName": "Sudeste",
              "stateCodes": [
                "SP"
              ]
            }
          },
          "note": "from the maintainer briefing, #596: every non-digit is removed from a string, as in 2.4.0"
        },
        {
          "id": "areaCode.getInfo#[\"DDD 11\"]",
          "args": [
            "DDD 11"
          ],
          "expect": {
            "returns": {
              "areaCode": 11,
              "stateCode": "SP",
              "stateName": "São Paulo",
              "regionCode": "SE",
              "regionName": "Sudeste",
              "stateCodes": [
                "SP"
              ]
            }
          },
          "note": "JavaScript docs example: non-digit characters are stripped"
        }
      ]
    },
    {
      "id": "areaCode.listByState",
      "level": "extended",
      "summary": "Gets every DDD (area code) that serves a Brazilian state, under the Plano Geral de Numeração.",
      "description": "Returns every DDD (area code) that serves a state, sorted in ascending order.\n\n- `stateCode` is matched ignoring case and surrounding whitespace, as it already was in 2.4.0.\n- A DDD that straddles a border is listed under every state it serves.\n- Returns an empty list when `stateCode` is not a Brazilian state.",
      "params": [
        {
          "name": "stateCode",
          "type": "string"
        }
      ],
      "returns": "number[]",
      "cases": [
        {
          "id": "areaCode.listByState#[\"SP\"]",
          "args": [
            "SP"
          ],
          "expect": {
            "returns": [
              11,
              12,
              13,
              14,
              15,
              16,
              17,
              18,
              19
            ]
          }
        },
        {
          "id": "areaCode.listByState#lowercase",
          "args": [
            "sp"
          ],
          "expect": {
            "returns": [
              11,
              12,
              13,
              14,
              15,
              16,
              17,
              18,
              19
            ]
          }
        },
        {
          "id": "areaCode.listByState#[\"AC\"]",
          "args": [
            "AC"
          ],
          "expect": {
            "returns": [
              68
            ]
          }
        },
        {
          "id": "areaCode.listByState#[\"PE\"]",
          "args": [
            "PE"
          ],
          "expect": {
            "returns": [
              81,
              87
            ]
          }
        },
        {
          "id": "areaCode.listByState#shared-ddds",
          "args": [
            "SC"
          ],
          "expect": {
            "returns": [
              42,
              47,
              48,
              49
            ]
          }
        },
        {
          "id": "areaCode.listByState#[\"XX\"]",
          "args": [
            "XX"
          ],
          "expect": {
            "returns": []
          }
        },
        {
          "id": "areaCode.listByState#empty",
          "args": [
            ""
          ],
          "expect": {
            "returns": []
          }
        },
        {
          "id": "areaCode.listByState#[\"Sp\"]",
          "args": [
            "Sp"
          ],
          "expect": {
            "returns": [
              11,
              12,
              13,
              14,
              15,
              16,
              17,
              18,
              19
            ]
          },
          "note": "JavaScript's own test: should be case-insensitive"
        },
        {
          "id": "areaCode.listByState#[\"  SP  \"]",
          "args": [
            "  SP  "
          ],
          "expect": {
            "returns": [
              11,
              12,
              13,
              14,
              15,
              16,
              17,
              18,
              19
            ]
          },
          "note": "JavaScript's own test: should trim surrounding whitespace"
        },
        {
          "id": "areaCode.listByState#[\"GO\"]",
          "args": [
            "GO"
          ],
          "expect": {
            "returns": [
              61,
              62,
              64
            ]
          },
          "note": "JavaScript's own test: should list DDD 61 for Goiás, which the Entorno do Distrito Federal shares with the DF"
        },
        {
          "id": "areaCode.listByState#[\"DF\"]",
          "args": [
            "DF"
          ],
          "expect": {
            "returns": [
              61
            ]
          },
          "note": "JavaScript's own test: should list only DDD 61 for the Distrito Federal"
        },
        {
          "id": "areaCode.listByState#[\"PR\"]",
          "args": [
            "PR"
          ],
          "expect": {
            "returns": [
              41,
              42,
              43,
              44,
              45,
              46,
              47,
              49
            ]
          },
          "note": "JavaScript's own test: should list the border DDDs 42, 47 and 49 under both of their states"
        },
        {
          "id": "areaCode.listByState#[\"   \"]",
          "args": [
            "   "
          ],
          "expect": {
            "returns": []
          },
          "note": "JavaScript's own test: should return an empty array when it is a blank string"
        },
        {
          "id": "areaCode.listByState#[\"ac\"]",
          "args": [
            "ac"
          ],
          "expect": {
            "returns": [
              68
            ]
          },
          "note": "JavaScript docs example"
        }
      ]
    }
  ]
}