From 7e6752a193e1f6d22196a494e24bbe391501dd7f Mon Sep 17 00:00:00 2001 From: Jukka-Pekka Siitonen Date: Tue, 5 Oct 2021 14:36:10 +0300 Subject: [PATCH 1/8] examples added for AsciiEncoder & AsciiDecoder --- sdk/lib/convert/ascii.dart | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/sdk/lib/convert/ascii.dart b/sdk/lib/convert/ascii.dart index 9f62c2d9bcfe..495a1f5bddc2 100644 --- a/sdk/lib/convert/ascii.dart +++ b/sdk/lib/convert/ascii.dart @@ -104,6 +104,15 @@ class _UnicodeSubsetEncoder extends Converter> { } /// This class converts strings of only ASCII characters to bytes. +/// +/// Example: +/// ```dart +/// +/// const String sample = 'Dart'; +/// const AsciiEncoder asciiEncoder = AsciiEncoder(); +/// final Uint8List asciiValues = asciiEncoder.convert(sample); +/// print(asciiValues); // [[68, 97, 114, 116] +/// ``` class AsciiEncoder extends _UnicodeSubsetEncoder { const AsciiEncoder() : super(_asciiMask); } @@ -195,6 +204,25 @@ abstract class _UnicodeSubsetDecoder extends Converter, String> { Stream bind(Stream> stream) => super.bind(stream); } +/// This class converts ASCII bytes to strings +/// +/// Example: +/// ```dart +/// +/// const AsciiDecoder asciiDecoder = AsciiDecoder(); +/// final List asciiValues = [68, 97, 114, 116]; +/// final string = asciiDecoder.convert(asciiValues); +/// print(string); // Dart +/// ``` +/// +/// Example allow invalid ASCII characters: +/// ```dart +/// +/// const AsciiDecoder asciiDecoder = AsciiDecoder(allowInvalid: true); +/// final List asciiValues = [68, 97, 114, 116, 20, 0xFF]; +/// final string = asciiDecoder.convert(asciiValues); +/// print(string); // Dart � +/// ``` class AsciiDecoder extends _UnicodeSubsetDecoder { const AsciiDecoder({bool allowInvalid = false}) : super(allowInvalid, _asciiMask); From 5f8f375a61878d392bd3414d8fb828956fb7f14f Mon Sep 17 00:00:00 2001 From: Jukka-Pekka Siitonen Date: Tue, 5 Oct 2021 16:02:25 +0300 Subject: [PATCH 2/8] description for example updated --- sdk/lib/convert/ascii.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/lib/convert/ascii.dart b/sdk/lib/convert/ascii.dart index 495a1f5bddc2..e8bcbcd16d02 100644 --- a/sdk/lib/convert/ascii.dart +++ b/sdk/lib/convert/ascii.dart @@ -215,7 +215,7 @@ abstract class _UnicodeSubsetDecoder extends Converter, String> { /// print(string); // Dart /// ``` /// -/// Example allow invalid ASCII characters: +/// Allow invalid ASCII characters example: /// ```dart /// /// const AsciiDecoder asciiDecoder = AsciiDecoder(allowInvalid: true); From e6416acdff4476b2dff69bd53b63787a9efc2d0f Mon Sep 17 00:00:00 2001 From: Jukka-Pekka Siitonen Date: Wed, 6 Oct 2021 16:06:56 +0300 Subject: [PATCH 3/8] Update for AsciiDecoder description --- sdk/lib/convert/ascii.dart | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/sdk/lib/convert/ascii.dart b/sdk/lib/convert/ascii.dart index e8bcbcd16d02..9bbe5442bde9 100644 --- a/sdk/lib/convert/ascii.dart +++ b/sdk/lib/convert/ascii.dart @@ -215,7 +215,13 @@ abstract class _UnicodeSubsetDecoder extends Converter, String> { /// print(string); // Dart /// ``` /// -/// Allow invalid ASCII characters example: +/// If `bytes` contains values that are not in the range 0 .. 127, the decoder +/// throws [FormatException]. +/// +/// If `allowInvalid` is set to true on constructor, +/// the decoder replaces the invalid bytes using a character `U+FFFD` �. +/// +/// Example: /// ```dart /// /// const AsciiDecoder asciiDecoder = AsciiDecoder(allowInvalid: true); From a5432320b7c422b2032dc343134c2e6acf4091a3 Mon Sep 17 00:00:00 2001 From: Jukka-Pekka Siitonen Date: Fri, 8 Oct 2021 14:21:20 +0300 Subject: [PATCH 4/8] fixes after review --- sdk/lib/convert/ascii.dart | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sdk/lib/convert/ascii.dart b/sdk/lib/convert/ascii.dart index 9bbe5442bde9..83d7253e48f6 100644 --- a/sdk/lib/convert/ascii.dart +++ b/sdk/lib/convert/ascii.dart @@ -103,7 +103,7 @@ class _UnicodeSubsetEncoder extends Converter> { Stream> bind(Stream stream) => super.bind(stream); } -/// This class converts strings of only ASCII characters to bytes. +/// Converts strings of only ASCII characters to bytes. /// /// Example: /// ```dart @@ -204,7 +204,7 @@ abstract class _UnicodeSubsetDecoder extends Converter, String> { Stream bind(Stream> stream) => super.bind(stream); } -/// This class converts ASCII bytes to strings +/// Converts ASCII bytes to strings. /// /// Example: /// ```dart @@ -218,8 +218,8 @@ abstract class _UnicodeSubsetDecoder extends Converter, String> { /// If `bytes` contains values that are not in the range 0 .. 127, the decoder /// throws [FormatException]. /// -/// If `allowInvalid` is set to true on constructor, -/// the decoder replaces the invalid bytes using a character `U+FFFD` �. +/// If `allowInvalid` is set to true, +/// the decoder replaces the invalid bytes with the character `U+FFFD` �. /// /// Example: /// ```dart From 71ba6a9fd55eb038bc08e9f18945e41afdef023d Mon Sep 17 00:00:00 2001 From: Jukka-Pekka Siitonen Date: Thu, 28 Oct 2021 13:17:06 +0300 Subject: [PATCH 5/8] update to example codes for AsciiEncoder and AsciiDecoder --- sdk/lib/convert/ascii.dart | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/sdk/lib/convert/ascii.dart b/sdk/lib/convert/ascii.dart index 83d7253e48f6..e3ca680814d8 100644 --- a/sdk/lib/convert/ascii.dart +++ b/sdk/lib/convert/ascii.dart @@ -35,7 +35,7 @@ class AsciiCodec extends Encoding { /// Encoders will not accept invalid (non ASCII) characters. const AsciiCodec({bool allowInvalid = false}) : _allowInvalid = allowInvalid; - /// The name of this codec, "us-ascii". + /// The name of this codec is "us-ascii". String get name => "us-ascii"; Uint8List encode(String source) => encoder.convert(source); @@ -106,12 +106,11 @@ class _UnicodeSubsetEncoder extends Converter> { /// Converts strings of only ASCII characters to bytes. /// /// Example: -/// ```dart -/// -/// const String sample = 'Dart'; +/// ```dart import:typed_data /// const AsciiEncoder asciiEncoder = AsciiEncoder(); +/// const String sample = 'Dart'; /// final Uint8List asciiValues = asciiEncoder.convert(sample); -/// print(asciiValues); // [[68, 97, 114, 116] +/// print(asciiValues); // [68, 97, 114, 116] /// ``` class AsciiEncoder extends _UnicodeSubsetEncoder { const AsciiEncoder() : super(_asciiMask); @@ -208,11 +207,10 @@ abstract class _UnicodeSubsetDecoder extends Converter, String> { /// /// Example: /// ```dart -/// /// const AsciiDecoder asciiDecoder = AsciiDecoder(); /// final List asciiValues = [68, 97, 114, 116]; -/// final string = asciiDecoder.convert(asciiValues); -/// print(string); // Dart +/// final String result = asciiDecoder.convert(asciiValues); +/// print(result); // Dart /// ``` /// /// If `bytes` contains values that are not in the range 0 .. 127, the decoder @@ -221,13 +219,12 @@ abstract class _UnicodeSubsetDecoder extends Converter, String> { /// If `allowInvalid` is set to true, /// the decoder replaces the invalid bytes with the character `U+FFFD` �. /// -/// Example: +/// Example with `allowInvalid` set to true: /// ```dart -/// /// const AsciiDecoder asciiDecoder = AsciiDecoder(allowInvalid: true); -/// final List asciiValues = [68, 97, 114, 116, 20, 0xFF]; -/// final string = asciiDecoder.convert(asciiValues); -/// print(string); // Dart � +/// final List asciiValues = [68, 97, 114, 116, 20, 0xFF]; +/// final String result = asciiDecoder.convert(asciiValues); +/// print(result); // Dart � /// ``` class AsciiDecoder extends _UnicodeSubsetDecoder { const AsciiDecoder({bool allowInvalid = false}) @@ -314,4 +311,4 @@ class _SimpleAsciiDecoderSink extends ByteConversionSinkBase { } if (isLast) close(); } -} +} \ No newline at end of file From f567ba7aa0fb13231269af140d4679cb9f5203c4 Mon Sep 17 00:00:00 2001 From: Jukka-Pekka Siitonen Date: Thu, 4 Nov 2021 13:15:28 +0200 Subject: [PATCH 6/8] EOF fix --- sdk/lib/convert/ascii.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/lib/convert/ascii.dart b/sdk/lib/convert/ascii.dart index e3ca680814d8..b73da22f48b1 100644 --- a/sdk/lib/convert/ascii.dart +++ b/sdk/lib/convert/ascii.dart @@ -311,4 +311,4 @@ class _SimpleAsciiDecoderSink extends ByteConversionSinkBase { } if (isLast) close(); } -} \ No newline at end of file +} From 927f59127a188acf055eac2b5a55df4de5083091 Mon Sep 17 00:00:00 2001 From: Jukka-Pekka Siitonen Date: Tue, 9 Nov 2021 08:34:47 +0200 Subject: [PATCH 7/8] Ascii examples update after first review --- sdk/lib/convert/ascii.dart | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/sdk/lib/convert/ascii.dart b/sdk/lib/convert/ascii.dart index b73da22f48b1..d5e0653c0b1b 100644 --- a/sdk/lib/convert/ascii.dart +++ b/sdk/lib/convert/ascii.dart @@ -107,9 +107,9 @@ class _UnicodeSubsetEncoder extends Converter> { /// /// Example: /// ```dart import:typed_data -/// const AsciiEncoder asciiEncoder = AsciiEncoder(); -/// const String sample = 'Dart'; -/// final Uint8List asciiValues = asciiEncoder.convert(sample); +/// const asciiEncoder = AsciiEncoder(); +/// const sample = 'Dart'; +/// final asciiValues = asciiEncoder.convert(sample); /// print(asciiValues); // [68, 97, 114, 116] /// ``` class AsciiEncoder extends _UnicodeSubsetEncoder { @@ -207,24 +207,24 @@ abstract class _UnicodeSubsetDecoder extends Converter, String> { /// /// Example: /// ```dart -/// const AsciiDecoder asciiDecoder = AsciiDecoder(); -/// final List asciiValues = [68, 97, 114, 116]; -/// final String result = asciiDecoder.convert(asciiValues); +/// const asciiDecoder = AsciiDecoder(); +/// final asciiValues = [68, 97, 114, 116]; +/// final result = asciiDecoder.convert(asciiValues); /// print(result); // Dart /// ``` +/// Throws a [FormatException] if [bytes] contains values that are not +/// in the range 0 .. 127, and [allowInvalid] is `false` (the default). /// -/// If `bytes` contains values that are not in the range 0 .. 127, the decoder -/// throws [FormatException]. -/// -/// If `allowInvalid` is set to true, -/// the decoder replaces the invalid bytes with the character `U+FFFD` �. +/// If [allowInvalid] is true, any byte outside the range 0..127 is replaced +/// by the Unicode invalid character, U+FFFD ('�'). /// /// Example with `allowInvalid` set to true: /// ```dart -/// const AsciiDecoder asciiDecoder = AsciiDecoder(allowInvalid: true); -/// final List asciiValues = [68, 97, 114, 116, 20, 0xFF]; -/// final String result = asciiDecoder.convert(asciiValues); +/// const asciiDecoder = AsciiDecoder(allowInvalid: true); +/// final asciiValues = [68, 97, 114, 116, 20, 0xFF]; +/// final result = asciiDecoder.convert(asciiValues); /// print(result); // Dart � +/// print(result.codeUnits.last.toRadixString(16)); // fffd /// ``` class AsciiDecoder extends _UnicodeSubsetDecoder { const AsciiDecoder({bool allowInvalid = false}) From cb1a9401cd13ff82376d1be90cc9c3e01cf3181b Mon Sep 17 00:00:00 2001 From: Jukka-Pekka Siitonen Date: Tue, 9 Nov 2021 12:53:43 +0200 Subject: [PATCH 8/8] fixes for review comments --- sdk/lib/convert/ascii.dart | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sdk/lib/convert/ascii.dart b/sdk/lib/convert/ascii.dart index d5e0653c0b1b..30a959982364 100644 --- a/sdk/lib/convert/ascii.dart +++ b/sdk/lib/convert/ascii.dart @@ -203,7 +203,7 @@ abstract class _UnicodeSubsetDecoder extends Converter, String> { Stream bind(Stream> stream) => super.bind(stream); } -/// Converts ASCII bytes to strings. +/// Converts ASCII bytes to string. /// /// Example: /// ```dart @@ -215,8 +215,8 @@ abstract class _UnicodeSubsetDecoder extends Converter, String> { /// Throws a [FormatException] if [bytes] contains values that are not /// in the range 0 .. 127, and [allowInvalid] is `false` (the default). /// -/// If [allowInvalid] is true, any byte outside the range 0..127 is replaced -/// by the Unicode invalid character, U+FFFD ('�'). +/// If [allowInvalid] is `true`, any byte outside the range 0..127 is replaced +/// by the Unicode replacement character, U+FFFD ('�'). /// /// Example with `allowInvalid` set to true: /// ```dart