Rename OutputStream to TextOutputStream [SE-0086]

This commit is contained in:
Tony Parker
2016-07-18 10:36:46 -07:00
parent e25c751693
commit 2a4e916296
12 changed files with 78 additions and 78 deletions

View File

@@ -993,7 +993,7 @@ Building
.. sidebar:: ``append``
the ``append`` method is a consequence of ``String``\ 's
conformance to ``OutputStream``. See the *Swift
conformance to ``TextOutputStream``. See the *Swift
formatting proposal* for details.
:Swift:

View File

@@ -109,18 +109,18 @@ Design Details
Output Streams
..............
The most fundamental part of this design is ``OutputStream``, a thing
The most fundamental part of this design is ``TextOutputStream``, a thing
into which we can stream text: [#character1]_
::
protocol OutputStream {
protocol TextOutputStream {
func append(_ text: String)
}
Every ``String`` can be used as an ``OutputStream`` directly::
Every ``String`` can be used as an ``TextOutputStream`` directly::
extension String : OutputStream {
extension String : TextOutputStream {
func append(_ text: String)
}
@@ -142,7 +142,7 @@ need to declare conformance: simply give the type a ``debugFormat()``::
Because ``String`` is a ``Streamable``, your implementation of
``debugFormat`` can just return a ``String``. If want to write
directly to the ``OutputStream`` for efficiency reasons,
directly to the ``TextOutputStream`` for efficiency reasons,
(e.g. if your representation is huge), you can return a custom
``DebugRepresentation`` type.
@@ -197,11 +197,11 @@ implement::
Because it's not always efficient to construct a ``String``
representation before writing an object to a stream, we provide a
``Streamable`` protocol, for types that can write themselves into an
``OutputStream``. Every ``Streamable`` is also a ``CustomStringConvertible``,
``TextOutputStream``. Every ``Streamable`` is also a ``CustomStringConvertible``,
naturally::
protocol Streamable : CustomStringConvertible {
func writeTo<T: OutputStream>(_ target: [inout] T)
func writeTo<T: TextOutputStream>(_ target: [inout] T)
// You'll never want to reimplement this
func format() -> PrintRepresentation {
@@ -224,7 +224,7 @@ adds surrounding quotes and escapes special characters::
struct EscapedStringRepresentation : Streamable {
var _value: String
func writeTo<T: OutputStream>(_ target: [inout] T) {
func writeTo<T: TextOutputStream>(_ target: [inout] T) {
target.append("\"")
for c in _value {
target.append(c.escape())
@@ -233,11 +233,11 @@ adds surrounding quotes and escapes special characters::
}
}
Besides modeling ``OutputStream``, ``String`` also conforms to
Besides modeling ``TextOutputStream``, ``String`` also conforms to
``Streamable``::
extension String : Streamable {
func writeTo<T: OutputStream>(_ target: [inout] T) {
func writeTo<T: TextOutputStream>(_ target: [inout] T) {
target.append(self) // Append yourself to the stream
}
@@ -275,12 +275,12 @@ complicated ``format(…)`` might be written::
struct RadixFormat<T: CustomStringConvertibleInteger> : Streamable {
var value: T, radix = 10, fill = " ", width = 0
func writeTo<S: OutputStream>(_ target: [inout] S) {
func writeTo<S: TextOutputStream>(_ target: [inout] S) {
_writeSigned(value, &target)
}
// Write the given positive value to stream
func _writePositive<T:CustomStringConvertibleInteger, S: OutputStream>(
func _writePositive<T:CustomStringConvertibleInteger, S: TextOutputStream>(
_ value: T, stream: [inout] S
) -> Int {
if value == 0 { return 0 }
@@ -293,7 +293,7 @@ complicated ``format(…)`` might be written::
return nDigits + 1
}
func _writeSigned<T:CustomStringConvertibleInteger, S: OutputStream>(
func _writeSigned<T:CustomStringConvertibleInteger, S: TextOutputStream>(
_ value: T, target: [inout] S
) {
var width = 0
@@ -333,15 +333,15 @@ considerable thought, they are included here for completeness and to
ensure our proposed design doesn't rule out important directions of
evolution.
``OutputStream`` Adapters
``TextOutputStream`` Adapters
.........................
Most text transformations can be expressed as adapters over generic
``OutputStream``\ s. For example, it's easy to imagine an upcasing
``TextOutputStream``\ s. For example, it's easy to imagine an upcasing
adapter that transforms its input to upper case before writing it to
an underlying stream::
struct UpperStream<UnderlyingStream:OutputStream> : OutputStream {
struct UpperStream<UnderlyingStream:TextOutputStream> : TextOutputStream {
func append(_ x: String) { base.append(x.toUpper()) }
var base: UnderlyingStream
}
@@ -353,26 +353,26 @@ processed and written to the underlying stream:
.. parsed-literal::
struct TrimStream<UnderlyingStream:OutputStream> : OutputStream {
struct TrimStream<UnderlyingStream:TextOutputStream> : TextOutputStream {
func append(_ x: String) { ... }
**func close() { ... }**
var base: UnderlyingStream
var bufferedWhitespace: String
}
This makes general ``OutputStream`` adapters more complicated to write
and use than ordinary ``OutputStream``\ s.
This makes general ``TextOutputStream`` adapters more complicated to write
and use than ordinary ``TextOutputStream``\ s.
``Streamable`` Adapters
.......................
For every conceivable ``OutputStream`` adaptor there's a corresponding
For every conceivable ``TextOutputStream`` adaptor there's a corresponding
``Streamable`` adaptor. For example::
struct UpperStreamable<UnderlyingStreamable:Streamable> {
var base: UnderlyingStreamable
func writeTo<T: OutputStream>(_ target: [inout] T) {
func writeTo<T: TextOutputStream>(_ target: [inout] T) {
var adaptedStream = UpperStream(target)
self.base.writeTo(&adaptedStream)
target = adaptedStream.base
@@ -418,12 +418,12 @@ least until we do, we opt not to trade away any CPU, memory, and
power.
If we were willing to say that only ``class``\ es can conform to
``OutputStream``, we could eliminate the explicit ``[inout]`` where
``OutputStream``\ s are passed around. Then, we'd simply need a
``TextOutputStream``, we could eliminate the explicit ``[inout]`` where
``TextOutputStream``\ s are passed around. Then, we'd simply need a
``class StringStream`` for creating ``String`` representations. It
would also make ``OutputStream`` adapters a *bit* simpler to use
would also make ``TextOutputStream`` adapters a *bit* simpler to use
because you'd never need to "write back" explicitly onto the target
stream. However, stateful ``OutputStream`` adapters would still need a
stream. However, stateful ``TextOutputStream`` adapters would still need a
``close()`` method, which makes a perfect place to return a copy of
the underlying stream, which can then be "written back":
@@ -431,7 +431,7 @@ the underlying stream, which can then be "written back":
struct AdaptedStreamable<T:Streamable> {
...
func writeTo<Target: OutputStream>(_ target: [inout] Target) {
func writeTo<Target: TextOutputStream>(_ target: [inout] Target) {
// create the stream that transforms the representation
var adaptedTarget = adapt(target, adapter);
// write the Base object to the target stream
@@ -444,7 +444,7 @@ the underlying stream, which can then be "written back":
}
We think anyone writing such adapters can handle the need for explicit
write-back, and the ability to use ``String`` as an ``OutputStream``
write-back, and the ability to use ``String`` as an ``TextOutputStream``
without additionally allocating a ``StringStream`` on the heap seems
to tip the balance in favor of the current design.

View File

@@ -81,7 +81,7 @@ public struct _FDInputStream {
}
}
public struct _Stderr : OutputStream {
public struct _Stderr : TextOutputStream {
public init() {}
public mutating func write(_ string: String) {
@@ -91,7 +91,7 @@ public struct _Stderr : OutputStream {
}
}
public struct _FDOutputStream : OutputStream {
public struct _FDOutputStream : TextOutputStream {
public let fd: CInt
public var isClosed: Bool = false

View File

@@ -158,7 +158,7 @@ public enum _DebuggerSupport {
}
}
internal static func printForDebuggerImpl<StreamType : OutputStream>(
internal static func printForDebuggerImpl<StreamType : TextOutputStream>(
value: Any?,
mirror: Mirror,
name: String?,

View File

@@ -20,8 +20,8 @@ import SwiftShims
///
/// You can send the output of the standard library's `print(_:to:)` and
/// `dump(_:to:)` functions to an instance of a type that conforms to the
/// `OutputStream` protocol instead of to standard output. Swift's `String`
/// type conforms to `OutputStream` already, so you can capture the output
/// `TextOutputStream` protocol instead of to standard output. Swift's `String`
/// type conforms to `TextOutputStream` already, so you can capture the output
/// from `print(_:to:)` and `dump(_:to:)` in a string instead of logging it to
/// standard output.
///
@@ -31,18 +31,18 @@ import SwiftShims
/// }
/// // s == "12345"
///
/// Conforming to the OutputStream Protocol
/// Conforming to the TextOutputStream Protocol
/// =======================================
///
/// To make your custom type conform to the `OutputStream` protocol, implement
/// the required `write(_:)` method. Functions that use an `OutputStream`
/// To make your custom type conform to the `TextOutputStream` protocol, implement
/// the required `write(_:)` method. Functions that use an `TextOutputStream`
/// target may call `write(_:)` multiple times per writing operation.
///
/// As an example, here's an implementation of an output stream that converts
/// any input to its plain ASCII representation before sending it to standard
/// output.
///
/// struct ASCIILogger: OutputStream {
/// struct ASCIILogger: TextOutputStream {
/// mutating func write(_ string: String) {
/// let ascii = string.unicodeScalars.lazy.map { scalar in
/// scalar == "\n"
@@ -65,7 +65,7 @@ import SwiftShims
/// var asciiLogger = ASCIILogger()
/// print(s, to: &asciiLogger)
/// // Prints "Hearts \u{2661} and Diamonds \u{2662}"
public protocol OutputStream {
public protocol TextOutputStream {
mutating func _lock()
mutating func _unlock()
@@ -73,7 +73,7 @@ public protocol OutputStream {
mutating func write(_ string: String)
}
extension OutputStream {
extension TextOutputStream {
public mutating func _lock() {}
public mutating func _unlock() {}
}
@@ -81,7 +81,7 @@ extension OutputStream {
/// A source of text-streaming operations.
///
/// Instances of types that conform to the `Streamable` protocol can write
/// their value to instances of any type that conforms to the `OutputStream`
/// their value to instances of any type that conforms to the `TextOutputStream`
/// protocol. The Swift standard library's text-related types, `String`,
/// `Character`, and `UnicodeScalar`, all conform to `Streamable`.
///
@@ -94,7 +94,7 @@ extension OutputStream {
public protocol Streamable {
/// Writes a textual representation of this instance into the given output
/// stream.
func write<Target : OutputStream>(to target: inout Target)
func write<Target : TextOutputStream>(to target: inout Target)
}
/// A type with a customized textual representation.
@@ -229,7 +229,7 @@ func _getEnumCaseName<T>(_ value: T) -> UnsafePointer<CChar>?
func _opaqueSummary(_ metadata: Any.Type) -> UnsafePointer<CChar>?
/// Do our best to print a value that cannot be printed directly.
internal func _adHocPrint_unlocked<T, TargetStream : OutputStream>(
internal func _adHocPrint_unlocked<T, TargetStream : TextOutputStream>(
_ value: T, _ mirror: Mirror, _ target: inout TargetStream,
isDebugPrint: Bool
) {
@@ -316,7 +316,7 @@ internal func _adHocPrint_unlocked<T, TargetStream : OutputStream>(
@inline(never)
@_semantics("stdlib_binary_only")
internal func _print_unlocked<T, TargetStream : OutputStream>(
internal func _print_unlocked<T, TargetStream : TextOutputStream>(
_ value: T, _ target: inout TargetStream
) {
// Optional has no representation suitable for display; therefore,
@@ -372,7 +372,7 @@ func _toStringReadOnlyPrintable<T : CustomStringConvertible>(_ x: T) -> String {
//===----------------------------------------------------------------------===//
@inline(never)
public func _debugPrint_unlocked<T, TargetStream : OutputStream>(
public func _debugPrint_unlocked<T, TargetStream : TextOutputStream>(
_ value: T, _ target: inout TargetStream
) {
if let debugPrintableObject = value as? CustomDebugStringConvertible {
@@ -394,7 +394,7 @@ public func _debugPrint_unlocked<T, TargetStream : OutputStream>(
_adHocPrint_unlocked(value, mirror, &target, isDebugPrint: true)
}
internal func _dumpPrint_unlocked<T, TargetStream : OutputStream>(
internal func _dumpPrint_unlocked<T, TargetStream : TextOutputStream>(
_ value: T, _ mirror: Mirror, _ target: inout TargetStream
) {
if let displayStyle = mirror.displayStyle {
@@ -463,7 +463,7 @@ internal func _dumpPrint_unlocked<T, TargetStream : OutputStream>(
// OutputStreams
//===----------------------------------------------------------------------===//
internal struct _Stdout : OutputStream {
internal struct _Stdout : TextOutputStream {
mutating func _lock() {
_swift_stdlib_flockfile_stdout()
}
@@ -489,7 +489,7 @@ internal struct _Stdout : OutputStream {
}
}
extension String : OutputStream {
extension String : TextOutputStream {
/// Appends the given string to this string.
///
/// - Parameter other: A string to append.
@@ -506,7 +506,7 @@ extension String : Streamable {
/// Writes the string into the given output stream.
///
/// - Parameter target: An output stream.
public func write<Target : OutputStream>(to target: inout Target) {
public func write<Target : TextOutputStream>(to target: inout Target) {
target.write(self)
}
}
@@ -515,7 +515,7 @@ extension Character : Streamable {
/// Writes the character into the given output stream.
///
/// - Parameter target: An output stream.
public func write<Target : OutputStream>(to target: inout Target) {
public func write<Target : TextOutputStream>(to target: inout Target) {
target.write(String(self))
}
}
@@ -525,7 +525,7 @@ extension UnicodeScalar : Streamable {
/// output stream.
///
/// - Parameter target: An output stream.
public func write<Target : OutputStream>(to target: inout Target) {
public func write<Target : TextOutputStream>(to target: inout Target) {
target.write(String(Character(self)))
}
}
@@ -534,9 +534,9 @@ extension UnicodeScalar : Streamable {
public var _playgroundPrintHook : ((String) -> Void)? = {_ in () }
internal struct _TeeStream<
L : OutputStream,
R : OutputStream
> : OutputStream {
L : TextOutputStream,
R : TextOutputStream
> : TextOutputStream {
var left: L
var right: R
@@ -548,12 +548,12 @@ internal struct _TeeStream<
mutating func _unlock() { right._unlock(); left._unlock() }
}
@available(*, unavailable, renamed: "OutputStream")
public typealias OutputStreamType = OutputStream
@available(*, unavailable, renamed: "TextOutputStream")
public typealias OutputStreamType = TextOutputStream
extension Streamable {
@available(*, unavailable, renamed: "write(to:)")
public func writeTo<Target : OutputStream>(_ target: inout Target) {
public func writeTo<Target : TextOutputStream>(_ target: inout Target) {
Builtin.unreachable()
}
}

View File

@@ -82,7 +82,7 @@ public func debugPrint(
/// - SeeAlso: `debugPrint`, `Streamable`, `CustomStringConvertible`,
/// `CustomDebugStringConvertible`
@inline(__always)
public func print<Target : OutputStream>(
public func print<Target : TextOutputStream>(
_ items: Any...,
separator: String = " ",
terminator: String = "\n",
@@ -103,7 +103,7 @@ public func print<Target : OutputStream>(
/// - SeeAlso: `print`, `Streamable`, `CustomStringConvertible`,
/// `CustomDebugStringConvertible`
@inline(__always)
public func debugPrint<Target : OutputStream>(
public func debugPrint<Target : TextOutputStream>(
_ items: Any...,
separator: String = " ",
terminator: String = "\n",
@@ -116,7 +116,7 @@ public func debugPrint<Target : OutputStream>(
@_versioned
@inline(never)
@_semantics("stdlib_binary_only")
internal func _print<Target : OutputStream>(
internal func _print<Target : TextOutputStream>(
_ items: [Any],
separator: String = " ",
terminator: String = "\n",
@@ -136,7 +136,7 @@ internal func _print<Target : OutputStream>(
@_versioned
@inline(never)
@_semantics("stdlib_binary_only")
internal func _debugPrint<Target : OutputStream>(
internal func _debugPrint<Target : TextOutputStream>(
_ items: [Any],
separator: String = " ",
terminator: String = "\n",
@@ -164,15 +164,15 @@ public func debugPrint<T>(_: T, appendNewline: Bool = true) {}
//===--- FIXME: Not working due to <rdar://22101775> ----------------------===//
@available(*, unavailable, message: "Please use the 'to' label for the target stream: 'print((...), to: &...)'")
public func print<T>(_: T, _: inout OutputStream) {}
public func print<T>(_: T, _: inout TextOutputStream) {}
@available(*, unavailable, message: "Please use the 'to' label for the target stream: 'debugPrint((...), to: &...))'")
public func debugPrint<T>(_: T, _: inout OutputStream) {}
public func debugPrint<T>(_: T, _: inout TextOutputStream) {}
@available(*, unavailable, message: "Please use 'terminator: \"\"' instead of 'appendNewline: false' and use the 'to' label for the target stream: 'print((...), terminator: \"\", to: &...)'")
public func print<T>(_: T, _: inout OutputStream, appendNewline: Bool = true) {}
public func print<T>(_: T, _: inout TextOutputStream, appendNewline: Bool = true) {}
@available(*, unavailable, message: "Please use 'terminator: \"\"' instead of 'appendNewline: false' and use the 'to' label for the target stream: 'debugPrint((...), terminator: \"\", to: &...)'")
public func debugPrint<T>(
_: T, _: inout OutputStream, appendNewline: Bool = true
_: T, _: inout TextOutputStream, appendNewline: Bool = true
) {}
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//

View File

@@ -140,7 +140,7 @@ internal func _reflect<T>(_ x: T) -> _Mirror
/// Dump an object's contents using its mirror to the specified output stream.
@discardableResult
public func dump<T, TargetStream : OutputStream>(
public func dump<T, TargetStream : TextOutputStream>(
_ value: T,
to target: inout TargetStream,
name: String? = nil,
@@ -183,7 +183,7 @@ public func dump<T>(
}
/// Dump an object's contents. User code should use dump().
internal func _dump_unlocked<TargetStream : OutputStream>(
internal func _dump_unlocked<TargetStream : TextOutputStream>(
_ value: Any,
to target: inout TargetStream,
name: String?,
@@ -282,7 +282,7 @@ internal func _dump_unlocked<TargetStream : OutputStream>(
/// Dump information about an object's superclass, given a mirror reflecting
/// that superclass.
internal func _dumpSuperclass_unlocked<TargetStream : OutputStream>(
internal func _dumpSuperclass_unlocked<TargetStream : TextOutputStream>(
mirror: Mirror,
to target: inout TargetStream,
indent: Int,

View File

@@ -353,7 +353,7 @@ class TestString : CustomStringConvertible, CustomDebugStringConvertible {
}
}
class TestStream : Streamable {
func write<Target : OutputStream>(to target: inout Target) {
func write<Target : TextOutputStream>(to target: inout Target) {
target.write("AStream")
}
}
@@ -368,7 +368,7 @@ func debugPrintStr<T>(_ a: T) -> String {
// Furthermore, printing an Optional should always print the debug
// description regardless of whether the wrapper type conforms to an
// output stream protocol.
OptionalTests.test("Optional OutputStream") {
OptionalTests.test("Optional TextOutputStream") {
let optNoString: TestNoString? = TestNoString()
expectFalse(optNoString is CustomStringConvertible)
expectFalse(canGenericCast(optNoString, CustomStringConvertible.self))

View File

@@ -4,7 +4,7 @@ var stream = ""
print(3, &stream) // expected-error{{'&' used with non-inout argument of type 'Any'}}
debugPrint(3, &stream) // expected-error{{'&' used with non-inout argument of type 'Any'}}
print(3, &stream, appendNewline: false) // expected-error {{cannot pass immutable value as inout argument: implicit conversion from 'String' to 'OutputStream' requires a temporary}}
debugPrint(3, &stream, appendNewline: false) // expected-error {{cannot pass immutable value as inout argument: implicit conversion from 'String' to 'OutputStream' requires a temporary}}
print(3, &stream, appendNewline: false) // expected-error {{cannot pass immutable value as inout argument: implicit conversion from 'String' to 'TextOutputStream' requires a temporary}}
debugPrint(3, &stream, appendNewline: false) // expected-error {{cannot pass immutable value as inout argument: implicit conversion from 'String' to 'TextOutputStream' requires a temporary}}
print(4, quack: 5) // expected-error {{argument labels '(_:, quack:)' do not match any available overloads}}
// expected-note@-1{{overloads for 'print' exist with these partially matching parameter lists: (Any..., separator: String, terminator: String), (T, appendNewline: Bool), (T, inout OutputStream), (T, inout OutputStream, appendNewline: Bool)}}
// expected-note@-1{{overloads for 'print' exist with these partially matching parameter lists: (Any..., separator: String, terminator: String), (T, appendNewline: Bool), (T, inout TextOutputStream), (T, inout TextOutputStream, appendNewline: Bool)}}

View File

@@ -295,10 +295,10 @@ func _Optional<T>(x: T) {
_ = Optional<T>.Some(x) // expected-error {{'Some' has been renamed to 'some'}} {{19-23=some}} {{none}}
}
func _OutputStream() {
func fn<S : OutputStreamType>(_: S) {} // expected-error {{'OutputStreamType' has been renamed to 'OutputStream'}} {{15-31=OutputStream}} {{none}}
func _TextOutputStream() {
func fn<S : OutputStreamType>(_: S) {} // expected-error {{'OutputStreamType' has been renamed to 'TextOutputStream'}} {{15-31=TextOutputStream}} {{none}}
}
func _OutputStream<S : Streamable, O : OutputStream>(s: S, o: O) {
func _TextOutputStream<S : Streamable, O : TextOutputStream>(s: S, o: O) {
var o = o
s.writeTo(&o) // expected-error {{'writeTo' has been renamed to 'write(to:)'}} {{5-12=write}} {{13-13=to: }} {{none}}
}
@@ -312,7 +312,7 @@ func _Print<T>(x: T) {
debugPrint(x, appendNewline: true) // expected-error {{'debugPrint(_:appendNewline:)' is unavailable: Please use 'terminator: ""' instead of 'appendNewline: false': 'debugPrint((...), terminator: "")'}} {{none}}
}
func _Print<T, O : OutputStream>(x: T, o: O) {
func _Print<T, O : TextOutputStream>(x: T, o: O) {
// FIXME: Not working due to <rdar://22101775>
//var o = o
//print(x, &o) // xpected-error {{}} {{none}}

View File

@@ -233,7 +233,7 @@ func someFuncUsingOldAttribute() { }
// <rdar://problem/23853709> Compiler crash on call to unavailable "print"
func OutputStreamTest(message: String, to: inout OutputStream) {
func TextOutputStreamTest(message: String, to: inout TextOutputStream) {
print(message, &to) // expected-error {{'print' is unavailable: Please use the 'to' label for the target stream: 'print((...), to: &...)'}}
}

View File

@@ -164,7 +164,7 @@ func _dumpRec(
}
}
struct _Stdout : OutputStream {
struct _Stdout : TextOutputStream {
mutating func _lock() {
_swift_stdlib_flockfile_stdout()
}