charset_normalizer_dart 0.1.0

Charset detection for Dart and Flutter, ported from Python charset_normalizer.

Charset Normalizer for Dart

English | 简体中文

A Dart port of the Python charset_normalizer library.

charset_normalizer_dart is a library that helps you read text from an unknown charset encoding. It is a direct Dart implementation of the famous Python library.

Features

• Detect the encoding of text from raw bytes, files, or paths.
• Provides support for both Dart IO and Web environments.
• Returns CharsetMatch or CharsetMatches with best-guess encodings.
• Exposes a clean Dart-style API (fromBytes, fromPath, isBinary, etc.).

Related Package

charset_normalizer_dart uses the independently published charset_codec package for codec behavior alignment. If you only need charset encode/decode, charset_codec is the lower-level package.

Getting Started

Add the package from pub.dev:

dart pub add charset_normalizer_dart

Usage

import 'package:charset_normalizer_dart/charset_normalizer_dart.dart';

void main() async {
  // From Bytes
  final bytes = [0x48, 0x65, 0x6c, 0x6c, 0x6f];
  final matches = fromBytes(bytes);
  print(matches.best()?.encoding); // e.g. 'ascii' or 'utf_8'

  // From File Path (IO only)
  final matchesFromFile = await fromPath('path/to/your/file.txt');
  print(matchesFromFile.best()?.encoding);

  // Synchronous File Read (IO only)
  final matchesSync = fromPathSync('path/to/your/file.txt');
  print(matchesSync.best()?.encoding);

  // Bounded prefix detection for large files (IO only)
  final sampled = await detectPathSampled(
    'path/to/large-file.txt',
    maxBytes: 1024 * 1024,
  );
  print('${sampled.best()?.encoding} from ${sampled.sampledBytes} bytes');
}

fromPath preserves the complete raw payload in its matches. For large files, prefer detectPathSampled or detectFileSampled; their result explicitly reports fileSize, sampledBytes, and whether detection was truncated.

API Reference

Core Functions

• fromBytes(List<int> sequences, ...): Detects encoding from a byte representation.
• fromFile(File file, ...): Detects encoding from a Dart File object asynchronously.
• fromFileSync(File file, ...): Detects encoding from a Dart File object synchronously.
• fromPath(String path, ...): Detects encoding from a file path asynchronously.
• fromPathSync(String path, ...): Detects encoding from a file path synchronously.
• detectPathSampled(String path, ...): Detects from a bounded file prefix and reports the sampling boundary.
• isBinary(Object fpOrPathOrPayload, ...): Checks if the content is binary asynchronously.
• isBinarySync(Object fpOrPathOrPayload, ...): Checks if the content is binary synchronously.
• detect(List<int> byteStr): Legacy chardet compatible API.

Acknowledgments

This project is a Dart rewrite of the incredible work done by jawah in the charset_normalizer repository.