mirror of
https://github.com/dart-lang/sdk
synced 2024-09-06 00:59:09 +00:00
Documentation update for Convert library landing page
Convert library landing page updated. Closes https://github.com/dart-lang/sdk/pull/48133 https://github.com/dart-lang/sdk/pull/48133 GitOrigin-RevId: 5660d283d806e513385c931c687e672e5ade6f72 Change-Id: I0c1ddc8ae4d21c27422aad85fc3db1160fddde1d Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/227760 Reviewed-by: Lasse Nielsen <lrn@google.com> Commit-Queue: Lasse Nielsen <lrn@google.com>
This commit is contained in:
parent
82a7299316
commit
af4600b584
|
@ -2,13 +2,12 @@
|
|||
// for details. All rights reserved. Use of this source code is governed by a
|
||||
// BSD-style license that can be found in the LICENSE file.
|
||||
|
||||
///
|
||||
/// Encoders and decoders for converting between different data representations,
|
||||
/// including JSON and UTF-8.
|
||||
///
|
||||
/// In addition to converters for common data representations, this library
|
||||
/// provides support for implementing converters in a way which makes them easy to
|
||||
/// chain and to use with streams.
|
||||
/// provides support for implementing converters in a way which makes them easy
|
||||
/// to chain and to use with streams.
|
||||
///
|
||||
/// To use this library in your code:
|
||||
/// ```dart
|
||||
|
@ -17,21 +16,91 @@
|
|||
/// Two commonly used converters are the top-level instances of
|
||||
/// [JsonCodec] and [Utf8Codec], named [json] and [utf8], respectively.
|
||||
///
|
||||
/// JSON is a simple text format for representing
|
||||
/// structured objects and collections.
|
||||
/// The JSON encoder/decoder transforms between strings and
|
||||
/// ## JSON
|
||||
/// JSON is a simple text format for representing structured objects and
|
||||
/// collections.
|
||||
///
|
||||
/// A [JsonCodec] encodes JSON objects to strings and decodes strings to
|
||||
/// JSON objects. The [json] encoder/decoder transforms between strings and
|
||||
/// object structures, such as lists and maps, using the JSON format.
|
||||
///
|
||||
/// UTF-8 is a common variable-width encoding that can represent
|
||||
/// every character in the Unicode character set.
|
||||
/// The UTF-8 encoder/decoder transforms between Strings and bytes.
|
||||
/// The [json] is the default implementation of [JsonCodec].
|
||||
///
|
||||
/// Examples
|
||||
/// ```dart
|
||||
/// var encoded = json.encode([1, 2, { "a": null }]);
|
||||
/// var decoded = json.decode('["foo", { "bar": 499 }]');
|
||||
/// ```
|
||||
/// For more information, see also [JsonEncoder] and [JsonDecoder].
|
||||
///
|
||||
/// ## UTF-8
|
||||
/// A [Utf8Codec] encodes strings to UTF-8 code units (bytes) and decodes
|
||||
/// UTF-8 code units to strings.
|
||||
///
|
||||
/// The [utf8] is the default implementation of [Utf8Codec].
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// var encoded = utf8.encode('Îñţérñåţîöñåļîžåţîờñ');
|
||||
/// var decoded = utf8.decode([
|
||||
/// 195, 142, 195, 177, 197, 163, 195, 169, 114, 195, 177, 195, 165, 197,
|
||||
/// 163, 195, 174, 195, 182, 195, 177, 195, 165, 196, 188, 195, 174, 197,
|
||||
/// 190, 195, 165, 197, 163, 195, 174, 225, 187, 157, 195, 177]);
|
||||
/// ```
|
||||
/// For more information, see also [Utf8Encoder] and [Utf8Decoder].
|
||||
///
|
||||
/// ## ASCII
|
||||
/// An [AsciiCodec] encodes strings as ASCII codes stored as bytes and decodes
|
||||
/// ASCII bytes to strings. Not all characters can be represented as ASCII, so
|
||||
/// not all strings can be successfully converted.
|
||||
///
|
||||
/// The [ascii] is the default implementation of [AsciiCodec].
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// var encoded = ascii.encode('This is ASCII!');
|
||||
/// var decoded = ascii.decode([0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73,
|
||||
/// 0x20, 0x41, 0x53, 0x43, 0x49, 0x49, 0x21]);
|
||||
/// ```
|
||||
/// For more information, see also [AsciiEncoder] and [AsciiDecoder].
|
||||
///
|
||||
/// ## Latin-1
|
||||
/// A [Latin1Codec] encodes strings to ISO Latin-1 (aka ISO-8859-1) bytes
|
||||
/// and decodes Latin-1 bytes to strings. Not all characters can be represented
|
||||
/// as Latin-1, so not all strings can be successfully converted.
|
||||
///
|
||||
/// The [latin1] is the default implementation of [Latin1Codec].
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// var encoded = latin1.encode('blåbærgrød');
|
||||
/// var decoded = latin1.decode([0x62, 0x6c, 0xe5, 0x62, 0xe6,
|
||||
/// 0x72, 0x67, 0x72, 0xf8, 0x64]);
|
||||
/// ```
|
||||
/// For more information, see also [Latin1Encoder] and [Latin1Decoder].
|
||||
///
|
||||
/// ## Base64
|
||||
/// A [Base64Codec] encodes bytes using the default base64 alphabet,
|
||||
/// decodes using both the base64 and base64url alphabets,
|
||||
/// does not allow invalid characters and requires padding.
|
||||
///
|
||||
/// The [base64] is the default implementation of [Base64Codec].
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// var encoded = base64.encode([0x62, 0x6c, 0xc3, 0xa5, 0x62, 0xc3, 0xa6,
|
||||
/// 0x72, 0x67, 0x72, 0xc3, 0xb8, 0x64]);
|
||||
/// var decoded = base64.decode('YmzDpWLDpnJncsO4ZAo=');
|
||||
/// ```
|
||||
/// For more information, see also [Base64Encoder] and [Base64Decoder].
|
||||
///
|
||||
/// ## Converters
|
||||
/// Converters are often used with streams
|
||||
/// to transform the data that comes through the stream
|
||||
/// as it becomes available.
|
||||
/// The following code uses two converters.
|
||||
/// The first is a UTF-8 decoder, which converts the data from bytes to UTF-8
|
||||
/// as it's read from a file,
|
||||
/// as it is read from a file,
|
||||
/// The second is an instance of [LineSplitter],
|
||||
/// which splits the data on newline boundaries.
|
||||
/// ```dart import:io
|
||||
|
@ -51,6 +120,45 @@
|
|||
/// See the documentation for the [Codec] and [Converter] classes
|
||||
/// for information about creating your own converters.
|
||||
///
|
||||
/// ## HTML Escape
|
||||
/// [HtmlEscape] converter escapes characters with special meaning in HTML.
|
||||
/// The converter finds characters that are significant in HTML source and
|
||||
/// replaces them with corresponding HTML entities.
|
||||
///
|
||||
/// Custom escape modes can be created using the [HtmlEscapeMode.HtmlEscapeMode]
|
||||
/// constructor.
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// const htmlEscapeMode = HtmlEscapeMode(
|
||||
/// name: 'custom',
|
||||
/// escapeLtGt: true,
|
||||
/// escapeQuot: false,
|
||||
/// escapeApos: false,
|
||||
/// escapeSlash: false,
|
||||
/// );
|
||||
///
|
||||
/// const HtmlEscape htmlEscape = HtmlEscape(htmlEscapeMode);
|
||||
/// String unescaped = 'Text & subject';
|
||||
/// String escaped = htmlEscape.convert(unescaped);
|
||||
/// print(escaped); // Text & subject
|
||||
///
|
||||
/// unescaped = '10 > 1 and 1 < 10';
|
||||
/// escaped = htmlEscape.convert(unescaped);
|
||||
/// print(escaped); // 10 > 1 and 1 < 10
|
||||
///
|
||||
/// unescaped = "Single-quoted: 'text'";
|
||||
/// escaped = htmlEscape.convert(unescaped);
|
||||
/// print(escaped); // Single-quoted: 'text'
|
||||
///
|
||||
/// unescaped = 'Double-quoted: "text"';
|
||||
/// escaped = htmlEscape.convert(unescaped);
|
||||
/// print(escaped); // Double-quoted: "text"
|
||||
///
|
||||
/// unescaped = 'Path: /system/';
|
||||
/// escaped = htmlEscape.convert(unescaped);
|
||||
/// print(escaped); // Path: /system/
|
||||
/// ```
|
||||
/// {@category Core}
|
||||
library dart.convert;
|
||||
|
||||
|
|
Loading…
Reference in a new issue