ZetCode

Dart SystemEncoding

last modified October 18, 2026

The SystemEncoding class in Dart provides access to the system's default encoding for converting between bytes and strings. It's part of Dart's dart:io library and is available through the top-level systemEncoding constant.

SystemEncoding uses the platform's default encoding (often UTF-8 on modern systems). It's useful when working with system APIs or files that use the system's native encoding.

Basic Definition

SystemEncoding is a final class that extends Encoding and represents the default encoding of the current system. The predefined systemEncoding constant is the instance normally used. It handles text conversion based on the platform's locale settings.

Key methods include encode() for string-to-bytes conversion and decode() for bytes-to-string conversion. It's automatically used by many system APIs.

Basic SystemEncoding Usage

This example shows basic encoding and decoding using SystemEncoding.

main.dart 
import 'dart:io';

void main() {
  var encoding = systemEncoding;
  var text = 'Dart SystemEncoding';
  
  // Encode string to bytes
  var bytes = encoding.encode(text);
  print('Encoded bytes: $bytes');
  
  // Decode bytes back to string
  var decoded = encoding.decode(bytes);
  print('Decoded text: $decoded');
}

We use the predefined systemEncoding instance, encode a string to bytes, then decode it back. This demonstrates the basic conversion cycle using the system encoding. 

$ dart main.dart
Encoded bytes: [68, 97, 114, 116, 32, 83, 121, 115, 116, 101, 109, 69, 110, 99, 111, 100, 105, 110, 103]
Decoded text: Dart SystemEncoding

Working with File System

This example demonstrates using SystemEncoding when reading and writing files.

main.dart 
import 'dart:io';

void main() async {
  var file = File('system_encoding.txt');
  var encoding = systemEncoding;
  
  // Write using system encoding
  await file.writeAsString('System Encoding Test', encoding: encoding);
  
  // Read using system encoding
  var content = await file.readAsString(encoding: encoding);
  print('File content: $content');
  
  // Show raw bytes
  var bytes = await file.readAsBytes();
  print('File bytes: $bytes');
}

We use SystemEncoding to ensure proper text handling with the file system. The encoding parameter ensures consistent character conversion on all platforms. 

$ dart main.dart
File content: System Encoding Test
File bytes: [83, 121, 115, 116, 101, 109, 32, 69, 110, 99, 111, 100, 105, 110, 103, 32, 84, 101, 115, 116]

Handling Different Encodings

This example compares SystemEncoding with UTF-8 for non-ASCII text.

main.dart 
import 'dart:convert';
import 'dart:io';

void main() {
  var systemEnc = systemEncoding;
  var utf8Enc = utf8;
  var text = 'Dart ñ SystemEncoding';
  
  var systemBytes = systemEnc.encode(text);
  var utf8Bytes = utf8Enc.encode(text);
  
  print('SystemEncoding bytes: $systemBytes');
  print('UTF-8 bytes: $utf8Bytes');
  
  print('System decode: ${systemEnc.decode(systemBytes)}');
  print('UTF-8 decode: ${utf8Enc.decode(utf8Bytes)}');
}

We compare how SystemEncoding and UTF-8 handle non-ASCII characters. Results may vary based on the platform's default encoding. 

$ dart main.dart
SystemEncoding bytes: [68, 97, 114, 116, 32, 195, 177, 32, 83, 121, 115, 116, 101, 109, 69, 110, 99, 111, 100, 105, 110, 103]
UTF-8 bytes: [68, 97, 114, 116, 32, 195, 177, 32, 83, 121, 115, 116, 101, 109, 69, 110, 99, 111, 100, 105, 110, 103]
System decode: Dart ñ SystemEncoding
UTF-8 decode: Dart ñ SystemEncoding

Platform-Specific Behavior

This example demonstrates how SystemEncoding behaves differently across platforms.

main.dart 
import 'dart:io';

void main() {
  var encoding = systemEncoding;
  var text = 'Flutter 跨平台开发';
  
  try {
    var bytes = encoding.encode(text);
    print('Encoded successfully on ${Platform.operatingSystem}');
    print('Byte length: ${bytes.length}');
  } catch (e) {
    print('Encoding failed on ${Platform.operatingSystem}: $e');
  }
}

This code may succeed or fail based on the platform's default encoding capabilities. Some systems may not support all Unicode characters. 

$ dart main.dart
Encoded successfully on linux
Byte length: 23

Converting Between Encodings

This example shows converting between SystemEncoding and other encodings.

main.dart 
import 'dart:convert';
import 'dart:io';

void main() {
  var systemEnc = systemEncoding;
  var text = 'Dart Encoding: €';
  
  // Encode with system encoding
  var systemBytes = systemEnc.encode(text);
  print('System bytes: $systemBytes');
  
  // Latin-1 cannot represent the euro sign
  try {
    latin1.encode(text);
    print('Latin-1 conversion succeeded');
  } catch (e) {
    print('Conversion to Latin-1 failed');
  }
  
  // Round-trip through system encoding
  var roundTrip = systemEnc.decode(systemEnc.encode(text));
  print('Round-trip: $roundTrip');
}

We demonstrate potential issues when converting between encodings. The euro symbol (€) cannot be represented in Latin-1, so encoding it raises an error. The system encoding round-trip preserves it. 

$ dart main.dart
System bytes: [68, 97, 114, 116, 32, 69, 110, 99, 111, 100, 105, 110, 103, 58, 32, 226, 130, 172]
Conversion to Latin-1 failed
Round-trip: Dart Encoding: €

Best Practices

Source

Dart SystemEncoding Documentation

This tutorial covered Dart's SystemEncoding class with practical examples showing basic usage, platform considerations, and encoding conversion scenarios.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Dart tutorials.