1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
<!-- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
<!-- contributed by Drew Willcoxon [adw@mozilla.com] -->
<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] -->
The `text-streams` module provides streams for reading and writing text using
particular character encodings.
<api name="TextReader">
@class
<api name="TextReader">
@constructor
Creates a buffered input stream that reads text from a backing stream using a
given text encoding.
@param inputStream {stream}
The backing stream, an [`nsIInputStream`](http://mxr.mozilla.org/mozilla-central/source/xpcom/io/nsIInputStream.idl).
It must already be opened.
@param [charset] {string}
`inputStream` is expected to be in the character encoding named by this value.
If not specified, "UTF-8" is assumed. See [`nsICharsetConverterManager.idl`](http://mxr.mozilla.org/mozilla-central/source/intl/uconv/idl/nsICharsetConverterManager.idl)
for documentation on how to determine other valid values for this.
</api>
<api name="closed">
@property {boolean}
True if the stream is closed.
</api>
<api name="close">
@method
Closes both the stream and its backing stream.
</api>
<api name="read">
@method
Reads and returns a string from the stream. If the stream is closed, an
exception is thrown.
@param [numChars] {number}
The number of characters to read. If not given, the remainder of the stream
is read.
@returns {string}
The string read. If the stream is at the end, the empty string is returned.
</api>
</api>
<api name="TextWriter">
@class
<api name="TextWriter">
@constructor
Creates a buffered output stream that writes text to a backing stream using a
given text encoding.
@param outputStream {stream}
The backing stream, an [`nsIOutputStream`](http://mxr.mozilla.org/mozilla-central/source/xpcom/io/nsIOutputStream.idl).
It must already be opened.
@param [charset] {string}
Text will be written to `outputStream` using the character encoding named by
this value. If not specified, "UTF-8" is assumed. See [`nsICharsetConverterManager.idl`](http://mxr.mozilla.org/mozilla-central/source/intl/uconv/idl/nsICharsetConverterManager.idl)
for documentation on how to determine other valid values for this.
</api>
<api name="closed">
@property {boolean}
True if the stream is closed.
</api>
<api name="close">
@method
Flushes the backing stream's buffer and closes both the stream and the backing
stream. If the stream is already closed, an exception is thrown.
</api>
<api name="flush">
@method
Flushes the backing stream's buffer.
</api>
<api name="write">
@method
Writes a string to the stream. If the stream is closed, an exception is
thrown.
@param str {string}
The string to write.
</api>
<api name="writeAsync">
@method
Writes a string on a background thread. After the write completes, the
backing stream's buffer is flushed, and both the stream and the backing stream
are closed, also on the background thread. If the stream is already closed,
an exception is thrown immediately.
@param str {string}
The string to write.
@param [callback] {callback}
*`callback`*, if given, must be a function. It's called as `callback(error)`
when the write completes. `error` is an `Error` object or undefined if there
was no error. Inside *`callback`*, `this` is the `TextWriter` object.
</api>
</api>
|
