parseAddress function

ParsedAddress parseAddress(
  1. String address
)

Parses a free-form Pakistani address into structured components.

Extracts the postal code, matches known cities, districts and provinces from the datasets, and assigns the remaining segments to ParsedAddress.street and ParsedAddress.area. Works with or without commas between components.

Implementation

ParsedAddress parseAddress(String address) {
  final raw = normalizeWhitespace(address);
  if (raw.isEmpty) return ParsedAddress(raw: raw);

  final warnings = <String>[];
  var working = raw;
  final postalMatch = _findPostalCode(working);
  final postalCode = postalMatch?.code;
  if (postalMatch != null) {
    working = '${working.substring(0, postalMatch.index)} '
        '${working.substring(postalMatch.index + postalMatch.code.length)}';
  }

  final segments = [
    for (final part in working.split(','))
      if (normalizeWhitespace(part).isNotEmpty) normalizeWhitespace(part),
  ];

  String? province;
  String? city;
  String? district;

  // Match whole segments first, from the end of the address.
  for (var i = segments.length - 1; i >= 0; i--) {
    final segment = segments[i];

    final matchedProvince =
        province == null ? _matchExact(segment, _provinces) : null;
    if (matchedProvince != null) {
      province = matchedProvince;
      segments[i] = '';
      continue;
    }

    final matchedCity = city == null ? _matchExact(segment, _cityNames) : null;
    if (matchedCity != null) {
      city = matchedCity;
      segments[i] = '';
      continue;
    }

    final matchedDistrict =
        district == null ? _matchExact(segment, _districtNames) : null;
    if (matchedDistrict != null) {
      district = matchedDistrict;
      segments[i] = '';
    }
  }

  // Then look for names at the end of a segment ("12 Model Town Lahore").
  for (var i = segments.length - 1; i >= 0; i--) {
    if (province == null) {
      final found = _matchTrailing(segments[i], _provinces);
      if (found != null) {
        province = found.match;
        segments[i] = found.rest;
      }
    }
    if (city == null) {
      final found = _matchTrailing(segments[i], _cityNames);
      if (found != null) {
        city = found.match;
        segments[i] = found.rest;
      }
    }
  }

  if (city == null && district != null) city = district;
  if (postalCode != null && city == null) {
    city = getCityByPostalCode(postalCode);
  }

  final inferredProvince = city != null
      ? (getProvince(city) ?? getDistrictProvince(city))
      : district != null
          ? getDistrictProvince(district)
          : null;

  if (province == null) {
    province = inferredProvince;
  } else if (inferredProvince != null && inferredProvince != province) {
    warnings.add(
      '${city ?? district} is in $inferredProvince, '
      'but the address says $province',
    );
  }

  final remaining = [
    for (final part in segments)
      if (part.isNotEmpty) part,
  ];

  return ParsedAddress(
    raw: raw,
    street: remaining.isEmpty ? null : remaining.first,
    area: remaining.length > 1 ? remaining.sublist(1).join(', ') : null,
    city: city,
    district: district,
    province: province,
    postalCode: postalCode,
    warnings: List.unmodifiable(warnings),
  );
}