Merge pull request #1 from apple/master

merge mainline

Author: milseman

0000-template.md

@@ -26,7 +26,7 @@ developers create better Swift code.
 
 Describe your solution to the problem. Provide examples and describe
 how they work. Show how your solution is better than current
-workarounds: is a cleaner, safer, or more efficient?
+workarounds: is it cleaner, safer, or more efficient?
 
 ## Detailed design
 
@@ -39,7 +39,7 @@ reasonably implement the feature.
 
 ## Impact on existing code
 
-Describe the impact this change will have on existing code. Will some
+Describe the impact that this change will have on existing code. Will some
 Swift applications stop compiling due to this change? Will applications still
 compile but produce different behavior than they used to? Is it
 possible to migrate existing Swift code to use a new feature or API

README.md

@@ -43,7 +43,7 @@ concretely, this release is focused on several key areas:
 * **API design guidelines**: The way in which Swift is used in popular
   libraries has almost as much of an effect on the character of Swift
   code as the Swift language itself. The [API design
-  guidelines](https://swift.org/documentation/api-design-guidelines.html) provide guidance for
+  guidelines](https://swift.org/documentation/api-design-guidelines/) provide guidance for
   building great Swift APIs. For Swift 3.0, the Swift standard library
   and core libraries are being updated to match these guidelines, and
   Swift's Objective-C importer will [automatically map](proposals/0005-objective-c-name-translation.md) from the [Cocoa guidelines for
@@ -76,9 +76,11 @@ sampling of potentially good ideas that are not in scope for Swift
   interoperability with C++ is a significant undertaking that is out
   of scope for Swift 3.0.
 
-* **Hygienic Macros**: A first-class macro system is something we may consider
-  in future releases.  We don't want the existence of a macro system to be a
-  workaround that reduces the incentive for making the core language great.
+* **Hygienic Macros** and **Compile-Time Evaluation**: A first-class macro
+  system, or support for compile-time code execution in general, is something
+  we may consider in future releases.  We don't want the existence of a macro
+  system to be a workaround that reduces the incentive for making the core
+  language great.
 
 * **Major new library functionality**: The Swift Standard Library is focused on
   providing core "language" functionality as well as common data structures.  The
@@ -91,14 +93,30 @@ sampling of potentially good ideas that are not in scope for Swift
   with the Swift Package Manager.  Beyond Swift 3 we may consider standardizing
   popular packages or expanding the scope of the project.  
 
+### Implemented proposals for Swift 3
+
+* [SE-0005: Better Translation of Objective-C APIs Into Swift](proposals/0005-objective-c-name-translation.md)
+* [SE-0006: Apply API Guidelines to the Standard Library](proposals/0006-apply-api-guidelines-to-the-standard-library.md)
+* [SE-0019: Swift Testing](proposals/0019-package-manager-testing.md)
+* [SE-0031: Adjusting inout Declarations for Type Decoration](proposals/0031-adjusting-inout-declarations.md)
+* [SE-0023: API Design Guidelines](proposals/0006-apply-api-guidelines-to-the-standard-library.md)
+* [SE-0028: Modernizing Swift's Debugging Identifiers (\__FILE__, etc)](proposals/0028-modernizing-debug-identifiers.md)
+* [SE-0034: Disambiguating Line Control Statements from Debugging Identifiers](proposals/0034-disambiguating-line.md)
+* [SE-0040: Replacing Equal Signs with Colons For Attribute Arguments](proposals/0040-attributecolons.md)
+
 ### Accepted proposals for Swift 3.0
 
-* [Better Translation of Objective-C APIs Into Swift](proposals/0005-objective-c-name-translation.md) (SE-0005)
-* [Removing currying `func` declaration syntax](proposals/0002-remove-currying.md) (SE-0002)
-* [Removing `var` from Function Parameters](proposals/0003-remove-var-parameters.md)
-* [Remove the `++` and `--` operators](proposals/0004-remove-pre-post-inc-decrement.md) (SE-0004)
-* [Remove C-style for-loops with conditions and incrementers](proposals/0007-remove-c-style-for-loops.md) (SE-0007)
-* [Swift Testing](proposals/0019-package-manager-testing.md) (SE-0019)
+* [SE-0002: Removing currying `func` declaration syntax](proposals/0002-remove-currying.md)
+* [SE-0003: Removing `var` from Function Parameters](proposals/0003-remove-var-parameters.md)
+* [SE-0004: Remove the `++` and `--` operators](proposals/0004-remove-pre-post-inc-decrement.md)
+* [SE-0007: Remove C-style for-loops with conditions and incrementers](proposals/0007-remove-c-style-for-loops.md)
+* [SE-0029: Remove implicit tuple splat behavior from function applications](proposals/0029-remove-implicit-tuple-splat.md)
+* [SE-0033: Import Objective-C Constants as Swift Types](proposals/0033-import-objc-constants.md)
+* [SE-0035: Limiting `inout` capture to `@noescape` contexts](proposals/0035-limit-inout-capture.md)
+* [SE-0037: Clarify interaction between comments & operators](proposals/0037-clarify-comments-and-operators.md)
+* [SE-0038: Package Manager C Language Target Support](proposals/0038-swiftpm-c-language-targets.md)
+* [SE-0039: Modernizing Playground Literals](proposals/0039-playgroundliterals.md)
+* [SE-0046: Establish consistent label behavior across all parameters including first labels](proposals/0046-first-label.md)
 
 ## Development minor version:  Swift 2.2
 
@@ -116,25 +134,35 @@ sooner.
 
 ### Implemented proposals for Swift 2.2
 
-* [Allow (most) keywords as argument labels](proposals/0001-keywords-as-argument-labels.md) (SE-0001)
-* [Tuple comparison operators](proposals/0015-tuple-comparison-operators.md) (SE-0015)
-* [Constraining `AnySequence.init`](proposals/0014-constrained-AnySequence.md) (SE-0014)
-* [Replace `typealias` keyword with `associatedtype` for associated type declarations](proposals/0011-replace-typealias-associated.md) (SE-0011)
-* [Naming Functions with Argument Labels](proposals/0021-generalized-naming.md) (SE-0021)
+* [SE-0001: Allow (most) keywords as argument labels](proposals/0001-keywords-as-argument-labels.md)
+* [SE-0015: Tuple comparison operators](proposals/0015-tuple-comparison-operators.md)
+* [SE-0014: Constraining `AnySequence.init`](proposals/0014-constrained-AnySequence.md)
+* [SE-0011: Replace `typealias` keyword with `associatedtype` for associated type declarations](proposals/0011-replace-typealias-associated.md)
+* [SE-0021: Naming Functions with Argument Labels](proposals/0021-generalized-naming.md)
+* [SE-0022: Referencing the Objective-C selector of a method](proposals/0022-objc-selectors.md)
 
 ### Accepted proposals for Swift 2.2
-* [Add a Lazy flatMap for Sequences of Optionals](proposals/0008-lazy-flatmap-for-optionals.md) (SE-0008)
-* [Swift Language Version Build Configuration](proposals/0020-if-swift-version.md) (SE-0020)
-* [Referencing the Objective-C selector of a method](proposals/0022-objc-selectors.md) (SE-0022)
+* [SE-0008: Add a Lazy flatMap for Sequences of Optionals](proposals/0008-lazy-flatmap-for-optionals.md)
+* [SE-0020: Swift Language Version Build Configuration](proposals/0020-if-swift-version.md)
 
 # Other Proposals
 
 ### Rejected proposals
-* [Require self for accessing instance members](proposals/0009-require-self-for-accessing-instance-members.md) (SE-0009)
-* [Remove Partial Application of Non-Final Super Methods (Swift 2.2)](proposals/0013-remove-partial-application-super.md) (SE-0013, Jan 9-13)
+* [SE-0009: Require self for accessing instance members](proposals/0009-require-self-for-accessing-instance-members.md)
+* [SE-0010: Add StaticString.UnicodeScalarView](proposals/0010-add-staticstring-unicodescalarview.md)
+* [SE-0013: Remove Partial Application of Non-Final Super Methods (Swift 2.2)](proposals/0013-remove-partial-application-super.md)
+* [SE-0024: Optional Value Setter `??=`](proposals/0024-optional-value-setter.md)
+* [SE-0027: Expose code unit initializers on String](proposals/0027-string-from-code-units.md)
 
 ## Review
 [Swift Evolution Review Schedule](https://github.com/apple/swift-evolution/blob/master/schedule.md)
 
 ### Returned for Revision
-* [Flexible Memberwise Initialization](proposals/0018-flexible-memberwise-initialization.md) (SE-0018)
+
+* [SE-0018: Flexible Memberwise Initialization](proposals/0018-flexible-memberwise-initialization.md)
+* [SE-0025: Scoped Access Level](proposals/0025-scoped-access-level.md)
+* [SE-0030: Property Behaviors](proposals/0030-property-behavior-decls.md)
+
+### Deferred for Future Discussion
+
+* [SE-0026: Abstract classes and methods](proposals/0026-abstract-classes-and-methods.md)

commonly_proposed.md

@@ -24,10 +24,18 @@ Several of the discussions below refer to "C Family" languages.  This is intende
 
 * [Rename `guard` to `unless`](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160104/005534.html): It is a common request to ask that `guard` be renamed `unless`. People requesting this change argue that `guard` is simply a logically-inverted `if` statement, and therefore `unless` is a more obvious keyword. However, such requests stem from a fundamental misunderstanding of the functionality provided by `guard`. Unlike `if`, `guard` *enforces* that the code within its curly braces provides an early exit from the codepath. In other words, a `guard` block **must** `return`, `throw`, `break`, `continue` or call a `@noreturn` function such as `fatalError()`. This differs from `if` quite significantly, and therefore the parallels assumed between `guard` and `if` are not valid.
 
+* [Use Garbage Collection instead of ARC](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160208/009403.html): Mark and sweep garbage collection is a well known technique used in many popular and widely used languages (e.g. Java and Javascript) and it has the advantage of automatically collecting reference cycles that ARC requires the programmer to reason about.  That said, garbage collection has a [large number of disadvantages](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160208/009422.html) and using it would prevent Swift from successfully targeting a number of systems programming domains.  For example, real time systems (video or audio processing), deeply embedded controllers, and most kernels find GC to be generally unsuitable.  Further, GC is only efficient when given 3-4x more memory to work with than the process is using at any time, and this tradeoff is not acceptable for Swift.
+
 Here are some other less-commonly proposed changes that have also been rejected:
 
 * [Remove `;` Semicolons](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20151214/002421.html): Semicolons within a line are an intentional expressivity feature.  Semicolons at the end of the line should be handled by a "linter", not by the compiler.
 
 * [Remove support for `default:` in Switch, and just use `case _:`](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20151207/001422.html): `default` is widely used, `case _` is too magical, and default is widely precedented in many C family languages.
 
 * [SE-0009: Require self for accessing instance members  ](proposals/0009-require-self-for-accessing-instance-members.md)
+
+* [SE-0024: Optional Value Setter `??=`](proposals/0024-optional-value-setter.md)
+
+* [SE-0027: Expose code unit initializers on String](proposals/0027-string-from-code-units.md)
+
+* [SE-0010: Add StaticString.UnicodeScalarView](proposals/0010-add-staticstring-unicodescalarview.md)

proposals/0005-objective-c-name-translation.md

@@ -2,7 +2,7 @@
 
 * Proposal: [SE-0005](https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md)
 * Author(s): [Doug Gregor](https://github.com/DougGregor), [Dave Abrahams](https://github.com/dabrahams)
-* Status: **Under Review** (January 22...February 5, 2016)
+* Status: **Accepted** ([Rationale](http://thread.gmane.org/gmane.comp.lang.swift.evolution/8590))
 * Review manager: [Doug Gregor](https://github.com/DougGregor)
 
 ## Reviewer notes
@@ -107,11 +107,11 @@ control over the process.
 
 5. **Prepend "is" to Boolean properties**: [Boolean properties should read as assertions on the receiver](https://swift.org/documentation/api-design-guidelines.html#boolean-assertions), but the Objective-C Coding Guidelines for Cocoa [prohibit the use of "is" on properties](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingIvarsAndTypes.html#//apple_ref/doc/uid/20001284-BAJGIIJE). Import such properties with "is" prepended.
 
-6. **Strip the "NS" prefix from Foundation APIs**: Foundation is a
-fundamental part of the [Swift Core Libraries][core-libraries], and
-having the prefixes on these cross-platform APIs feels
-anachronistic. Therefore, remove the "NS" prefix from entities defined
-in the Foundation module (and other specifically identified modules where it makes sense).
+6. **Lowercase values**: The Swift API Design Guidelines have non-type
+declarations lowercased. Lowercase non-prefixed values whenever they
+are imported, including enumerators (whether they end up in Swift as
+enum cases or option sets) and any other properties/functions (e.g., a
+property named `URLHandler` will be lowercased to `urlHandler`).
 
 7. **Adopt Comparable to classes that implement** `compare(_:) -> NSComparisonResult`: The objective-c classes that implement compare all have declared a capability of being compared in an ordered manner. `Comparable` formalizes this declaration into an implementable operator by the import process.
 
@@ -137,21 +137,21 @@ the imported `UIBezierPath` API in Swift 2:
 
 And the same API imported under our current, experimental implementation of this proposal:
 
-    class UIBezierPath : Object, Copying, Coding {
-      convenience init(ovalIn: CGRect)
-      func moveTo(_: CGPoint)
-      func addLineTo(_: CGPoint)
-      func addCurveTo(_: CGPoint, controlPoint1: CGPoint, controlPoint2: CGPoint)
-      func addQuadCurveTo(_: CGPoint, controlPoint: CGPoint)
-      func append(_: UIBezierPath)
+    class UIBezierPath : NSObject, NSCopying, NSCoding {
+      convenience init(ovalIn rect: CGRect)
+      func move(to point: CGPoint)
+      func addLine(to point: CGPoint)
+      func addCurve(to endPoint: CGPoint, controlPoint1 controlPoint1: CGPoint, controlPoint2 controlPoint2: CGPoint)
+      func addQuadCurve(to endPoint: CGPoint, controlPoint controlPoint: CGPoint)
+      func append(_ bezierPath: UIBezierPath)
       func reversing() -> UIBezierPath
-      func apply(_: CGAffineTransform)
+      func apply(_ transform: CGAffineTransform)
       var isEmpty: Bool { get }
-      func contains(_: CGPoint) -> Bool
-      func fillWith(_: CGBlendMode, alpha: CGFloat)
-      func strokeWith(_: CGBlendMode, alpha: CGFloat)
-      func copy(zone _: Zone = nil) -> AnyObject
-      func encodeWith(_: Coder)
+      func contains(_ point: CGPoint) -> Bool
+      func fill(_ blendMode: CGBlendMode, alpha alpha: CGFloat)
+      func stroke(_ blendMode: CGBlendMode, alpha alpha: CGFloat)
+      func copy(with zone: NSZone = nil) -> AnyObject
+      func encode(with aCoder: NSCoder)
     }
 
 In the latter case, a number of words that restated type information
@@ -612,18 +612,18 @@ to become:
 
 #### Add First Argument Labels
 
-When the first parameter of a method is defaulted, **split the first
-selector piece if it contains a preposition**, turning everything
+If the first selector piece contains a preposition, **split the first
+selector piece at the last preposition**, turning everything
 starting with the last preposition into a *required* label for the
-first argument. If the generated first argument label starts with the
-word "with", drop the "with".
+first argument.
 
-This heuristic eliminates words that refer only to the first
+As well as creating first argument label for a significant number of
+APIs, this heuristic eliminates words that refer only to the first
 argument from call sites where the argument's default value is
 used. For example, instead of:
 
 <pre>
-extension NSArray {
+extension UIBezierPath {
   func enumerateObjects<b>With</b>(_: NSEnumerationOptions <b>= []</b>, using: (AnyObject, UnsafeMutablePointer<ObjCBool>) -> Void)
 }
 
@@ -670,33 +670,6 @@ extension NSBezierPath {
 if path.<b>isEmpty</b> { ... }
 </pre>
 
-### Stripping the "NS" Prefix
-
-The removal of the "NS" prefix for the Foundation module (or other
-specifically identified modules) is a mechanical translation for all
-global symbols defined within that module that can be performed in the
-Clang importer. Note that this removal can create conflicts with the
-standard library. For example, `NSString` and `NSArray` will become
-`String` and `Array`, respectively, and Foundation's versions will
-shadow the standard library's versions. In cases where the Swift 3
-names of standard library entities conflict with prefix-stripped
-Foundation entities, we retain the `NS` prefix. These Foundation
-entities are: `NSArray`, `NSDictionary`, `NSInteger`, `NSRange`,
-`NSSet`, and `NSString`.
-
-When the `NS` prefix is stripped from a non-type, lowercase the
-initial word. For example:
-
-<pre>
-var NSDateComponentUndefined: Int { get }
-</pre>
-
-will become
-
-<pre>
-var dateComponentUndefined: Int { get }
-</pre>
-  
 ### Conformance of implementers of compare method
 
 Currently, in comparing protocols, for example developers usually have