convert 3.1.2: Configure fallback handling and validation bounds for unmapped characters and undefined byte sequences in CodePage

# CodePage Fallback Configuration and Validation in convert

## Prior Art Search

A search with package `convert` yielded no existing public contracts for `convert` (matching only unrelated samples for `crypto`, `clap`, and `zap`). This sample investigates the configuration settings and error handling behavior of `CodePage` in `package:convert`.

## Target Version

Pinned release: `convert` 3.1.2.

## Finding and Failure Mode

Naive implementations expect `CodePage.encode` and `CodePage.decode` to automatically substitute unmapped characters or undefined byte values with fallback tokens (such as `?` or `\uFFFD`), or silently drop them.

In reality:
- `CodePage.encode` throws `FormatException` ("Not a character in this code page") on unmapped code points (e.g. Euro `'€'` in `latin2` / ISO-8859-2) unless the optional `invalidCharacter` parameter is explicitly provided.
- If `invalidCharacter` is provided but falls outside the 0..255 byte interval (e.g. `256` or `-1`), `RangeError` is thrown immediately.
- `CodePage.decode` throws `FormatException` ("Not defined in this code page") on undefined byte entries (e.g. byte `0x80` in `latin2`) unless `allowInvalid: true` is explicitly configured, in which case `\uFFFD` is emitted.
- `CodePage.decode` throws `FormatException` ("Not a byte value") on integers outside 0..255 when `allowInvalid` is false, and emits `\uFFFD` when `allowInvalid` is true.
- Custom `CodePage` construction (`CodePage(name, characters)`) validates that the mapping table contains exactly 256 code points, throwing `ArgumentError` if the string length differs.

{"case":{"believed":"CodePage.encode and CodePage.decode silently replace unmapped characters or undefined bytes with fallback tokens rather than throwing FormatException.","caseId":"case:sha256:71fe249b63247abe2608ef8636a0424df58125632909fbc1d2914c17f91c933e","contract":["CodePage.encode throws FormatException on unmapped characters unless configured with an in-range invalidCharacter byte, and CodePage.decode throws FormatException on undefined byte entries unless allowInvalid is set to true.","latin2.encode('Price: 10€') throws FormatException because the Euro symbol is unmapped in ISO-8859-2.","latin2.encode('Price: 10€', invalidCharacter: 0x3F) succeeds and substitutes the question mark byte 0x3F for the unmapped Euro character.","latin2.encode('Price: 10€', invalidCharacter: 256) throws RangeError because invalidCharacter must be an integer within 0..255.","latin2.decode([0x50, 0x80, 0x51]) throws FormatException because 0x80 is an undefined code point in ISO-8859-2.","latin2.decode([0x50, 0x80, 0x51], allowInvalid: true) succeeds and emits Unicode replacement character U+FFFD for 0x80.","latin2.decode([256]) throws FormatException with 'Not a byte value' while allowInvalid: true emits U+FFFD.","CodePage('custom', 'ABC') throws ArgumentError because CodePage table definitions require exactly 256 characters."],"goal":"Configure fallback handling and validation bounds for unmapped characters and undefined byte sequences in CodePage","kind":"HOW","packages":["pkg:pub/convert@3.1.2"],"schemaVersion":1,"symbols":["CodePage","CodePage.encode","CodePage.decode","latin2"]},"contractCommand":["dart","test/contract.dart"],"environment":{"arch":"x64","ecosystem":"pub","executionContext":"dart","language":"dart","os":"linux","packageManager":"pub","runtime":"dart","schemaVersion":1},"license":"MIT-0","packages":["pkg:pub/convert@3.1.2"],"schemaVersion":1,"symbols":["CodePage","CodePage.encode","CodePage.decode","latin2"],"verifierAdapter":"pub@1"}

# Generated by pub
# See https://dart.dev/tools/pub/glossary#lockfile
packages:
  collection:
    dependency: transitive
    description:
      name: collection
      sha256: "2f5709ae4d3d59dd8f7cd309b4e023046b57d8a6c82130785d2b0e5868084e76"
      url: "https://pub.dev"
    source: hosted
    version: "1.19.1"
  convert:
    dependency: "direct main"
    description:
      name: convert
      sha256: b30acd5944035672bc15c6b7a8b47d773e41e2f17de064350988c5d02adb1c68
      url: "https://pub.dev"
    source: hosted
    version: "3.1.2"
  typed_data:
    dependency: transitive
    description:
      name: typed_data
      sha256: f9049c039ebfeb4cf7a7104a675823cd72dba8297f264b6637062516699fa006
      url: "https://pub.dev"
    source: hosted
    version: "1.4.0"
sdks:
  dart: ">=3.5.0 <4.0.0"

name: pub_convert_config
description: Proves CodePage configuration settings and error handling in package:convert.
publish_to: none
environment:
  sdk: ^3.5.0

dependencies:
  convert: 3.1.2

import 'dart:typed_data';
import 'package:convert/convert.dart';

void main() {
  // 1. CodePage.encode throws FormatException on unmapped characters when invalidCharacter is null (default).
  // In ISO-8859-2 (latin2), the Euro character '€' (U+20AC) does not exist (0xA4 maps to '¤').
  var threwEncodeException = false;
  try {
    latin2.encode('Price: 10€');
  } on FormatException catch (e) {
    if (e.message == 'Not a character in this code page') {
      threwEncodeException = true;
    }
  }
  if (!threwEncodeException) {
    throw StateError(
        'Expected FormatException when encoding unmapped character without invalidCharacter fallback');
  }

  // 2. Supplying invalidCharacter: 0x3F (ASCII '?') replaces unmapped character instead of throwing.
  final encodedWithFallback =
      latin2.encode('Price: 10€', invalidCharacter: 0x3F);
  final expectedBytes = [80, 114, 105, 99, 101, 58, 32, 49, 48, 63];
  if (encodedWithFallback.length != expectedBytes.length) {
    throw StateError(
        'Expected encoded length ${expectedBytes.length}, got ${encodedWithFallback.length}');
  }
  for (var i = 0; i < expectedBytes.length; i++) {
    if (encodedWithFallback[i] != expectedBytes[i]) {
      throw StateError(
          'Byte mismatch at index $i: expected ${expectedBytes[i]}, got ${encodedWithFallback[i]}');
    }
  }

  // 3. Supplying invalidCharacter outside the byte range 0..255 throws RangeError.
  var threwRangeErrorHigh = false;
  try {
    latin2.encode('Price: 10€', invalidCharacter: 256);
  } on RangeError catch (e) {
    if (e.name == 'invalidCharacter') {
      threwRangeErrorHigh = true;
    }
  }
  if (!threwRangeErrorHigh) {
    throw StateError('Expected RangeError when invalidCharacter is 256');
  }

  var threwRangeErrorLow = false;
  try {
    latin2.encode('Price: 10€', invalidCharacter: -1);
  } on RangeError catch (e) {
    if (e.name == 'invalidCharacter') {
      threwRangeErrorLow = true;
    }
  }
  if (!threwRangeErrorLow) {
    throw StateError('Expected RangeError when invalidCharacter is -1');
  }

  // 4. CodePage.decode throws FormatException when encountering undefined byte entries with allowInvalid: false (default).
  // In ISO-8859-2, byte 0x80 is undefined (\uFFFD).
  var threwDecodeException = false;
  try {
    latin2.decode([0x50, 0x80, 0x51]);
  } on FormatException catch (e) {
    if (e.message == 'Not defined in this code page') {
      threwDecodeException = true;
    }
  }
  if (!threwDecodeException) {
    throw StateError(
        'Expected FormatException when decoding undefined byte with allowInvalid: false');
  }

  // 5. Setting allowInvalid: true replaces undefined bytes with Unicode replacement character U+FFFD.
  final decodedWithAllowInvalid =
      latin2.decode([0x50, 0x80, 0x51], allowInvalid: true);
  if (decodedWithAllowInvalid != 'P\uFFFDQ') {
    throw StateError('Expected "P\\uFFFDQ", got "$decodedWithAllowInvalid"');
  }

  // 6. Non-byte integer values (> 255) throw FormatException with "Not a byte value" under allowInvalid: false,
  // and emit U+FFFD under allowInvalid: true.
  var threwNonByteDecodeException = false;
  try {
    latin2.decode([256]);
  } on FormatException catch (e) {
    if (e.message == 'Not a byte value') {
      threwNonByteDecodeException = true;
    }
  }
  if (!threwNonByteDecodeException) {
    throw StateError(
        'Expected FormatException("Not a byte value") when decoding integer 256');
  }

  final decodedNonByteLenient = latin2.decode([256], allowInvalid: true);
  if (decodedNonByteLenient != '\uFFFD') {
    throw StateError(
        'Expected "\\uFFFD" for non-byte integer with allowInvalid: true');
  }

  // 7. Custom CodePage constructor requires exactly 256 characters in table definition.
  var threwTableLengthException = false;
  try {
    CodePage('custom', 'ABC');
  } on ArgumentError catch (e) {
    if (e.name == 'characters') {
      threwTableLengthException = true;
    }
  }
  if (!threwTableLengthException) {
    throw StateError(
        'Expected ArgumentError when CodePage table definition has fewer than 256 characters');
  }
}