Rename OutputStream to TextOutputStream [SE-0086]

Author: parkera

docs/StringDesign.rst

@@ -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:

docs/TextFormatting.rst

@@ -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,20 +418,20 @@ 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":
 
 .. parsed-literal::
 
   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.
 

stdlib/private/SwiftPrivate/IO.swift

@@ -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
 

stdlib/public/core/DebuggerSupport.swift

@@ -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?,

stdlib/public/core/OutputStream.swift

@@ -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,23 +65,23 @@ 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()
 
   /// Appends the given string to the stream.
   mutating func write(_ string: String)
 }
 
-extension OutputStream {
+extension TextOutputStream {
   public mutating func _lock() {}
   public mutating func _unlock() {}
 }
 
 /// 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()
   }
 }