Tweak the docs (#63)
Be consistent about zero- vs. null-terminated (the latter was more
commonly used, but using the former was suggested in #61). Furthermore,
align UTF-8/16 spelling and fix a couple of minor typos and formatting
issues.
diff --git a/README.md b/README.md
index 48e5873..4418533 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
[](https://travis-ci.org/dart-lang/ffi)
Utilities for working with Foreign Function Interface (FFI) code, incl.
-converting between Dart strings and C strings encoded with utf8 and utf16.
+converting between Dart strings and C strings encoded with UTF-8 and UTF-16.
For additional details about Dart FFI (`dart:ffi`), see
https://dart.dev/guides/libraries/c-interop.
diff --git a/example/main.dart b/example/main.dart
index a343a02..b00ccbb 100644
--- a/example/main.dart
+++ b/example/main.dart
@@ -9,7 +9,7 @@
print(pointer.value);
free(pointer);
- // Use the Utf8 helper to encode null-terminated Utf8 strings in native memory.
+ // Use the Utf8 helper to encode zero-terminated UTF-8 strings in native memory.
final String myString = '😎👿💬';
final Pointer<Utf8> charPointer = Utf8.toUtf8(myString);
print('First byte is: ${charPointer.cast<Uint8>().value}');
diff --git a/lib/src/utf16.dart b/lib/src/utf16.dart
index f1b64fa..67bc6a7 100644
--- a/lib/src/utf16.dart
+++ b/lib/src/utf16.dart
@@ -8,21 +8,21 @@
import 'package:ffi/ffi.dart';
-/// [Utf16] implements conversion between Dart strings and null-terminated
+/// [Utf16] implements conversion between Dart strings and zero-terminated
/// UTF-16 encoded "char*" strings in C.
///
-/// [Utf16] is respresented as a struct so that `Pointer<Utf16>` can be used in
+/// [Utf16] is represented as a struct so that `Pointer<Utf16>` can be used in
/// native function signatures.
class Utf16 extends Struct {
- /// Convert a [String] to a Utf16-encoded null-terminated C string.
+ /// Convert a [String] to a UTF-16 encoded zero-terminated C string.
///
- /// If 'string' contains NULL bytes, the converted string will be truncated
+ /// If [string] contains NULL characters, the converted string will be truncated
/// prematurely. Unpaired surrogate code points in [string] will be preserved
- /// in the UTF-8 encoded result. See [Utf8Encoder] for details on encoding.
+ /// in the UTF-16 encoded result. See [Utf16Encoder] for details on encoding.
///
/// Returns a malloc-allocated pointer to the result.
- static Pointer<Utf16> toUtf16(String s) {
- final units = s.codeUnits;
+ static Pointer<Utf16> toUtf16(String string) {
+ final units = string.codeUnits;
final Pointer<Uint16> result = allocate<Uint16>(count: units.length + 1);
final Uint16List nativeString = result.asTypedList(units.length + 1);
nativeString.setAll(0, units);
diff --git a/lib/src/utf8.dart b/lib/src/utf8.dart
index b585794..38476c7 100644
--- a/lib/src/utf8.dart
+++ b/lib/src/utf8.dart
@@ -12,17 +12,17 @@
const int _kMaxSmi32 = (1 << 30) - 1;
final int _maxSize = sizeOf<IntPtr>() == 8 ? _kMaxSmi64 : _kMaxSmi32;
-/// [Utf8] implements conversion between Dart strings and null-terminated
-/// Utf8-encoded "char*" strings in C.
+/// [Utf8] implements conversion between Dart strings and zero-terminated
+/// UTF-8 encoded "char*" strings in C.
///
-/// [Utf8] is respresented as a struct so that `Pointer<Utf8>` can be used in
+/// [Utf8] is represented as a struct so that `Pointer<Utf8>` can be used in
/// native function signatures.
//
// TODO(https://github.com/dart-lang/ffi/issues/4): No need to use
// 'asTypedList' when Pointer operations are performant.
class Utf8 extends Struct {
- /// Returns the length of a null-terminated string -- the number of (one-byte)
- /// characters before the first null byte.
+ /// Returns the length of a zero-terminated string — the number of
+ /// bytes before the first zero byte.
static int strlen(Pointer<Utf8> string) {
final Pointer<Uint8> array = string.cast<Uint8>();
final Uint8List nativeString = array.asTypedList(_maxSize);
@@ -42,9 +42,9 @@
string.cast<Uint8>().asTypedList(length).buffer, 0, length));
}
- /// Convert a [String] to a Utf8-encoded null-terminated C string.
+ /// Convert a [String] to a UTF-8 encoded zero-terminated C string.
///
- /// If 'string' contains NULL bytes, the converted string will be truncated
+ /// If [string] contains NULL characters, the converted string will be truncated
/// prematurely. Unpaired surrogate code points in [string] will be encoded
/// as replacement characters (U+FFFD, encoded as the bytes 0xEF 0xBF 0xBD)
/// in the UTF-8 encoded result. See [Utf8Encoder] for details on encoding.
