From cc852042c9da5892fb5cdedfb6cf49740004755c Mon Sep 17 00:00:00 2001 From: practicalswift Date: Sat, 29 Oct 2016 10:22:58 +0200 Subject: [PATCH] [gardening] Fix accidental trailing whitespace. --- CMakeLists.txt | 18 +- LICENSE.txt | 4 +- apinotes/CoreGraphics.apinotes | 14 +- apinotes/GameplayKit.apinotes | 2 +- apinotes/README.md | 4 +- cmake/modules/AddSwift.cmake | 10 +- cmake/modules/FindICU.cmake | 2 +- docs/ABI.rst | 8 +- docs/AccessControl.rst | 6 +- docs/CMakeLists.txt | 20 +- docs/CallingConvention.rst | 4 +- docs/ContinuousIntegration.md | 8 +- docs/DependencyAnalysis.rst | 2 +- docs/Driver.md | 4 +- docs/DriverInternals.rst | 6 +- docs/ErrorHandling.rst | 10 +- docs/ErrorHandlingRationale.rst | 4 +- docs/Generics.rst | 46 ++--- docs/GenericsManifesto.md | 14 +- docs/HighLevelSILOptimizations.rst | 4 +- docs/InitializerProblems.rst | 18 +- docs/Lexicon.rst | 32 +-- docs/LibraryEvolution.rst | 10 +- docs/Literals.rst | 8 +- docs/Modules.rst | 50 ++--- docs/MutationModel.rst | 12 +- docs/ObjectInitialization.rst | 26 +-- docs/OptimizationTips.rst | 12 +- docs/PatternMatching.rst | 6 +- docs/Runtime.md | 2 +- docs/SIL.rst | 96 ++++----- docs/SequencesAndCollections.rst | 10 +- docs/StdlibAPIGuidelines.rst | 24 +-- docs/StoredAndComputedVariables.rst | 10 +- docs/StringDesign.rst | 186 +++++++++--------- docs/TextFormatting.rst | 8 +- docs/TypeChecker.rst | 14 +- .../NamespaceLevelVarsAndTopLevelCode.rst | 2 +- docs/archive/Objective-CInteroperability.rst | 16 +- docs/archive/Resilience.rst | 24 +-- docs/doxygen.css | 8 +- docs/doxygen.intro | 10 +- docs/proposals/Accessors.rst | 10 +- docs/proposals/ArrayBridge.rst | 4 +- docs/proposals/CPointerArgumentInterop.rst | 2 +- .../CPointerInteropLanguageModel.rst | 4 +- docs/proposals/Concurrency.rst | 6 +- docs/proposals/DeclarationTypeChecker.rst | 2 +- docs/proposals/Enums.rst | 6 +- docs/proposals/Initialization.rst | 12 +- docs/proposals/InitializerInheritance.rst | 16 +- docs/proposals/InoutCOWOptimization.rst | 10 +- docs/proposals/Inplace.rst | 14 +- docs/proposals/ObjCInteroperation.rst | 46 ++--- docs/proposals/OptionSets.rst | 10 +- docs/proposals/README.txt | 2 +- docs/proposals/TypeState.rst | 2 +- docs/proposals/ValueSemantics.rst | 8 +- .../archive/MemoryAndConcurrencyModel.rst | 10 +- .../ProgramStructureAndCompilationModel.rst | 2 +- .../archive/UnifiedFunctionSyntax.rst | 8 +- ...dgingContainerProtocolsToClassClusters.rst | 4 +- docs/proposals/rejected/ClassConstruction.rst | 6 +- docs/proposals/rejected/Clonable.rst | 8 +- docs/proposals/rejected/Constructors.rst | 30 +-- docs/proposals/valref.rst | 4 +- docs/toc.js | 44 ++--- include/swift/ABI/MetadataKind.def | 2 +- include/swift/AST/Builtins.def | 18 +- .../swift/AST/DiagnosticsClangImporter.def | 2 +- include/swift/AST/DiagnosticsCommon.def | 4 +- include/swift/AST/DiagnosticsDriver.def | 2 +- include/swift/AST/DiagnosticsFrontend.def | 2 +- include/swift/AST/DiagnosticsIRGen.def | 2 +- include/swift/AST/DiagnosticsParse.def | 4 +- include/swift/AST/DiagnosticsSIL.def | 2 +- include/swift/AST/DiagnosticsSema.def | 22 +-- include/swift/AST/TypeNodes.def | 2 +- include/swift/Option/Options.td | 2 +- .../swift/SILOptimizer/PassManager/Passes.def | 2 +- lib/Basic/PartsOfSpeech.def | 2 +- lib/Basic/Unix/TaskQueue.inc | 2 +- lib/ClangImporter/MappedTypes.def | 2 +- lib/SILOptimizer/ARC/CMakeLists.txt | 2 +- .../CheckCollectionType.swift.gyb | 20 +- .../CheckMutableCollectionType.swift.gyb | 4 +- .../LoggingWrappers.swift.gyb | 12 +- .../StdlibUnittest/StdlibUnittest.swift.gyb | 24 +-- .../public/SDK/CoreGraphics/CGFloat.swift.gyb | 10 +- stdlib/public/SDK/Foundation/DataThunks.m | 10 +- .../public/SDK/Foundation/FileManagerThunks.m | 2 +- .../public/SDK/Foundation/NSNumber.swift.gyb | 2 +- stdlib/public/SDK/GLKit/GLKMath.swift.gyb | 2 +- .../SpriteKit/SpriteKitQuickLooks.swift.gyb | 2 +- .../UIKit_FoundationExtensions.swift.gyb | 10 +- stdlib/public/core/Arrays.swift.gyb | 18 +- .../core/CollectionAlgorithms.swift.gyb | 4 +- .../core/ExistentialCollection.swift.gyb | 20 +- stdlib/public/core/Filter.swift.gyb | 8 +- stdlib/public/core/FixedPoint.swift.gyb | 6 +- stdlib/public/core/Flatten.swift.gyb | 14 +- stdlib/public/core/FloatingPoint.swift.gyb | 12 +- .../public/core/FloatingPointTypes.swift.gyb | 8 +- .../public/core/HashedCollections.swift.gyb | 18 +- .../public/core/IntegerArithmetic.swift.gyb | 4 +- stdlib/public/core/Integers.swift.gyb | 8 +- stdlib/public/core/LazyCollection.swift.gyb | 18 +- stdlib/public/core/Range.swift.gyb | 2 +- .../core/RangeReplaceableCollection.swift.gyb | 4 +- .../public/core/SequenceAlgorithms.swift.gyb | 12 +- stdlib/public/core/Sort.swift.gyb | 2 +- ...StringRangeReplaceableCollection.swift.gyb | 2 +- stdlib/public/core/UnsafePointer.swift.gyb | 4 +- .../core/UnsafeRawBufferPointer.swift.gyb | 8 +- stdlib/public/core/UnsafeRawPointer.swift.gyb | 10 +- test/APINotes/Inputs/roundtrip.apinotes | 12 +- .../LinkFramework.framework/module.map | 2 +- .../Inputs/crash-simple/output.json | 2 +- .../Inputs/fail-chained/output.json | 2 +- .../Inputs/fail-interface-hash/output.json | 2 +- .../Inputs/fail-simple/output.json | 2 +- .../Inputs/fail-with-bad-deps/output.json | 2 +- test/IDE/Inputs/mock-sdk/Foo.printed.txt | 32 +-- test/IRGen/Inputs/usr/include/module.map | 8 +- .../clang-importer-sdk/usr/include/module.map | 10 +- test/LLVMPasses/contract.ll | 2 +- test/Prototypes/Algorithms.swift.gyb | 64 +++--- test/SILGen/Inputs/usr/include/module.map | 26 +-- test/SILOptimizer/Inputs/include/module.map | 4 +- .../arcsequenceopts_loops.sil.gyb | 2 +- test/stdlib/AnyHashableCasts.swift.gyb | 2 +- test/stdlib/ArrayBridge.swift.gyb | 38 ++-- test/stdlib/BridgeStorage.swift.gyb | 14 +- test/stdlib/CastTraps.swift.gyb | 6 +- test/stdlib/FloatingPoint.swift.gyb | 6 +- test/stdlib/Inputs/ArrayBridge/ArrayBridge.m | 6 +- .../SwiftNativeNSBase/SwiftNativeNSBase.m | 2 +- .../SwiftObjectNSObject/SwiftObjectNSObject.m | 12 +- test/stdlib/Inputs/flatMap.gyb | 2 +- test/stdlib/NumericParsing.swift.gyb | 20 +- test/stdlib/Runtime.swift.gyb | 6 +- test/stdlib/SegmentAlignment.c | 6 +- test/stdlib/Tuple.swift.gyb | 4 +- test/stdlib/UnsafePointer.swift.gyb | 4 +- tools/SourceKit/CMakeLists.txt | 14 +- tools/SourceKit/README.txt | 2 +- utils/UnicodeData/GraphemeBreakTest.txt | 6 +- utils/error_enum_to_cases.pl | 4 +- utils/swift-mode.el | 62 +++--- utils/swift-project-settings.el | 56 +++--- validation-test/stdlib/ArrayNew.swift.gyb | 4 +- .../stdlib/ArrayTrapsObjC.swift.gyb | 4 +- validation-test/stdlib/Arrays.swift.gyb | 2 +- .../stdlib/CollectionCasts.swift.gyb | 26 +-- .../stdlib/ExistentialCollection.swift.gyb | 8 +- .../FixedPointArithmeticTraps.swift.gyb | 4 +- .../stdlib/FixedPointConversion.swift.gyb | 6 +- validation-test/stdlib/NewArray.swift.gyb | 44 ++--- .../stdlib/NumericDiagnostics.swift.gyb | 4 +- .../Prototypes/PersistentVector.swift.gyb | 20 +- validation-test/stdlib/Range.swift.gyb | 4 +- .../stdlib/RangeReplaceable.swift.gyb | 6 +- validation-test/stdlib/SequenceType.swift.gyb | 10 +- validation-test/stdlib/Sort.swift.gyb | 2 +- .../stdlib/UnsafeBufferPointer.swift.gyb | 18 +- 165 files changed, 1002 insertions(+), 1002 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 28ed434767ed3..8f24a2110a97d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -506,12 +506,12 @@ if(XCODE) endif() # FIXME: the parameters we specify in SWIFT_SDKS are lacking architecture specifics, -# so we need to hard-code it. For example, the SDK for Android is just 'ANDROID', -# which we assume below to be armv7. +# so we need to hard-code it. For example, the SDK for Android is just 'ANDROID', +# which we assume below to be armv7. # The iOS SDKs all have their architectures hardcoded because they are just specified by name (e.g. 'IOS' or 'WATCHOS'). # We can't cross-compile the standard library for another linux architecture, # because the SDK list would just be 'LINUX' and we couldn't disambiguate it from the host. -# +# # To fix it, we would need to append the architecture to the SDKs, # for example: 'OSX-x86_64;IOS-armv7;...etc'. # We could easily do that - we have all of that information in build-script-impl. @@ -519,7 +519,7 @@ endif() # Darwin targets cheat and use `xcrun`. if("${SWIFT_HOST_VARIANT_SDK}" STREQUAL "LINUX") - + set(CMAKE_EXECUTABLE_FORMAT "ELF") set(SWIFT_HOST_VARIANT "linux" CACHE STRING "Deployment OS for Swift host tools (the compiler) [linux].") @@ -550,7 +550,7 @@ if("${SWIFT_HOST_VARIANT_SDK}" STREQUAL "LINUX") endif() elseif("${SWIFT_HOST_VARIANT_SDK}" STREQUAL "FREEBSD") - + set(CMAKE_EXECUTABLE_FORMAT "ELF") set(SWIFT_HOST_VARIANT "freebsd" CACHE STRING "Deployment OS for Swift host tools (the compiler) [freebsd].") @@ -563,13 +563,13 @@ elseif("${SWIFT_HOST_VARIANT_SDK}" STREQUAL "FREEBSD") "x86_64-unknown-freebsd${FREEBSD_SYSTEM_VERSION}" "/") set(SWIFT_PRIMARY_VARIANT_SDK_default "${SWIFT_HOST_VARIANT_SDK}") set(SWIFT_PRIMARY_VARIANT_ARCH_default "x86_64") - + elseif("${SWIFT_HOST_VARIANT_SDK}" STREQUAL "CYGWIN") - + # set(CMAKE_EXECUTABLE_FORMAT "ELF") set(SWIFT_HOST_VARIANT "windows" CACHE STRING "Deployment OS for Swift host tools (the compiler) [windows].") - + configure_sdk_unix(CYGWIN "Cygwin" "windows" "cygwin" "windows" "x86_64-unknown-windows-cygnus" "/") set(SWIFT_PRIMARY_VARIANT_SDK_default "${SWIFT_HOST_VARIANT_SDK}") set(SWIFT_PRIMARY_VARIANT_ARCH_default "x86_64") @@ -579,7 +579,7 @@ elseif("${SWIFT_HOST_VARIANT_SDK}" MATCHES "(OSX|IOS*|TVOS*|WATCHOS*)") set(SWIFT_HOST_VARIANT "macosx" CACHE STRING "Deployment OS for Swift host tools (the compiler) [macosx, iphoneos].") - # Display Xcode toolchain version. + # Display Xcode toolchain version. # The SDK configuration below prints each SDK version. execute_process( COMMAND "xcodebuild" "-version" diff --git a/LICENSE.txt b/LICENSE.txt index 4b3ed032f560f..61b0c78195f2d 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -200,8 +200,8 @@ See the License for the specific language governing permissions and limitations under the License. - - + + ## Runtime Library Exception to the Apache 2.0 License: ## diff --git a/apinotes/CoreGraphics.apinotes b/apinotes/CoreGraphics.apinotes index 42ffd870503a8..7c5c0f7845477 100644 --- a/apinotes/CoreGraphics.apinotes +++ b/apinotes/CoreGraphics.apinotes @@ -90,7 +90,7 @@ Functions: # replaced by Equatable / == SwiftName: CGAffineTransform.__equalTo(self:_:) SwiftPrivate: true - + # CGBitmapContext - Name: CGBitmapContextCreateWithData SwiftName: CGContext.init(data:width:height:bitsPerComponent:bytesPerRow:space:bitmapInfo:releaseCallback:releaseInfo:) @@ -114,7 +114,7 @@ Functions: SwiftName: getter:CGContext.alphaInfo(self:) - Name: CGBitmapContextCreateImage SwiftName: CGContext.makeImage(self:) - + # CGColor # - Name: CGColorCreate @@ -409,7 +409,7 @@ Functions: - Name: CGGetLastMouseDelta # replaced by a version that returns CGVector instead of using out-pointers SwiftPrivate: true - + # CGEvent - Name: CGEventCreateFromData SwiftName: CGEvent.init(withDataAllocator:data:) @@ -421,7 +421,7 @@ Functions: SwiftName: CGEvent.postToPid(_:self:) - Name: CGEventCreateSourceFromEvent SwiftName: CGEventSource.init(event:) - + # CGFont - Name: CGFontCreateWithDataProvider SwiftName: CGFont.init(_:) @@ -443,7 +443,7 @@ Functions: SwiftName: CGFont.table(self:for:) - Name: CGFontCreateCopyWithVariations SwiftName: CGFont.copy(self:withVariations:) - + # CGGeometry - Name: CGPointCreateDictionaryRepresentation SwiftName: getter:CGPoint.dictionaryRepresentation(self:) @@ -474,7 +474,7 @@ Functions: # hide in favor of an init (can't map to initializer because out-pointer) SwiftName: CGRect.__setFromDictionaryRepresentation(_:_:) SwiftPrivate: true - + # CGGradient - Name: CGGradientCreateWithColorComponents SwiftName: CGGradient.init(colorSpace:colorComponents:locations:count:) @@ -557,7 +557,7 @@ Functions: # CGPSConverter - Name: CGPSConverterIsConverting SwiftName: getter:CGPSConverter.isConverting(self:) - + # CGPath - Name: CGPathCreateCopy SwiftName: CGPath.copy(self:) diff --git a/apinotes/GameplayKit.apinotes b/apinotes/GameplayKit.apinotes index b5b8025bc579c..a59aa761eca22 100644 --- a/apinotes/GameplayKit.apinotes +++ b/apinotes/GameplayKit.apinotes @@ -206,7 +206,7 @@ Classes: - Selector: 'shuffledArrayWithRandomSource:' SwiftName: shuffled(using:) MethodKind: Instance -- Name: GKARC4RandomSource +- Name: GKARC4RandomSource Methods: - Selector: 'dropValuesWithCount:' SwiftName: dropValues(_:) diff --git a/apinotes/README.md b/apinotes/README.md index c27b931ef65f5..816ec911ab229 100644 --- a/apinotes/README.md +++ b/apinotes/README.md @@ -11,7 +11,7 @@ API notes are organized into a set of `.apinotes` files. Each written in YAML (FIXME: to be) described below. These YAML sources must be manually compiled into a binary representation (`.apinotesc`) that the Swift compiler will lazily load when it builds code, also -described below. +described below. # API Notes YAML Format @@ -42,7 +42,7 @@ When updating API notes for a system module, recompile the API notes and place the result in the appropriate directories listed above. The Swift compiler itself need not be recompiled except in rare cases where the changes affect how the SDK overlays are built. To recompile -API notes for a given module `$MODULE` and place them into their +API notes for a given module `$MODULE` and place them into their ### OS X ``` diff --git a/cmake/modules/AddSwift.cmake b/cmake/modules/AddSwift.cmake index 6a01cadc0cb18..a9e21ae7f7e27 100644 --- a/cmake/modules/AddSwift.cmake +++ b/cmake/modules/AddSwift.cmake @@ -95,7 +95,7 @@ endfunction() # ANALYZE_CODE_COVERAGE analyze_code_coverage # RESULT_VAR_NAME result_var_name # DEPLOYMENT_VERSION_IOS deployment_version_ios # If provided, overrides the default value of the iOS deployment target set by the Swift project for this compilation only. -# +# # ) function(_add_variant_c_compile_link_flags) set(oneValueArgs SDK ARCH BUILD_TYPE RESULT_VAR_NAME ENABLE_LTO ANALYZE_CODE_COVERAGE DEPLOYMENT_VERSION_IOS) @@ -104,7 +104,7 @@ function(_add_variant_c_compile_link_flags) "${oneValueArgs}" "" ${ARGN}) - + set(result ${${CFLAGS_RESULT_VAR_NAME}} "-target" "${SWIFT_SDK_${CFLAGS_SDK}_ARCH_${CFLAGS_ARCH}_TRIPLE}") @@ -1297,12 +1297,12 @@ function(add_swift_library name) message(FATAL_ERROR "Either SHARED, STATIC, or OBJECT_LIBRARY must be specified") endif() - + if(SWIFTLIB_TARGET_LIBRARY) if(NOT SWIFT_BUILD_RUNTIME_WITH_HOST_COMPILER) list(APPEND SWIFTLIB_DEPENDS clang) endif() - + # If we are building this library for targets, loop through the various # SDKs building the variants of this library. list_intersect( @@ -1675,7 +1675,7 @@ function(_add_swift_executable_single name) # Determine compiler flags. set(c_compile_flags) set(link_flags) - + # Add variant-specific flags. _add_variant_c_compile_flags( SDK "${SWIFTEXE_SINGLE_SDK}" diff --git a/cmake/modules/FindICU.cmake b/cmake/modules/FindICU.cmake index 91911781442f7..2dec985d67f25 100644 --- a/cmake/modules/FindICU.cmake +++ b/cmake/modules/FindICU.cmake @@ -8,7 +8,7 @@ set(ICU_REQUIRED) foreach(MODULE ${ICU_FIND_COMPONENTS}) string(TOUPPER "${MODULE}" MODULE) string(TOLOWER "${MODULE}" module) - list(APPEND ICU_REQUIRED + list(APPEND ICU_REQUIRED ICU_${MODULE}_INCLUDE_DIR ICU_${MODULE}_LIBRARIES) pkg_check_modules(PC_ICU_${MODULE} QUIET icu-${module}) diff --git a/docs/ABI.rst b/docs/ABI.rst index 2dc77c0a5eb1e..377825a3ac1da 100644 --- a/docs/ABI.rst +++ b/docs/ABI.rst @@ -29,7 +29,7 @@ Structs and tuples currently share the same layout algorithm, noted as the is as follows: - Start with a **size** of **0** and an **alignment** of **1**. -- Iterate through the fields, in element order for tuples, or in ``var`` +- Iterate through the fields, in element order for tuples, or in ``var`` declaration order for structs. For each field: * Update **size** by rounding up to the **alignment of the field**, that is, @@ -41,7 +41,7 @@ is as follows: **alignment of the field**. - The final **size** and **alignment** are the size and alignment of the - aggregate. The **stride** of the type is the final **size** rounded up to + aggregate. The **stride** of the type is the final **size** rounded up to **alignment**. Note that this differs from C or LLVM's normal layout rules in that *size* @@ -852,7 +852,7 @@ The first identifier in a ```` is a string that represents the file the original declaration came from. It should be considered unique within the enclosing module. The second identifier is the name of the entity. -Not all declarations marked ``private`` declarations will use the +Not all declarations marked ``private`` declarations will use the ```` mangling; if the entity's context is enough to uniquely identify the entity, the simple ``identifier`` form is preferred. @@ -929,7 +929,7 @@ Types type ::= 'b' type type // objc block function type type ::= 'c' type type // C function pointer type type ::= 'F' throws-annotation? type type // function type - type ::= 'f' throws-annotation? type type // uncurried function type + type ::= 'f' throws-annotation? type type // uncurried function type type ::= 'G' type + '_' // generic type application type ::= 'K' type type // @auto_closure function type type ::= 'M' type // metatype without representation diff --git a/docs/AccessControl.rst b/docs/AccessControl.rst index 25ad78158e93e..956a4eca99b06 100644 --- a/docs/AccessControl.rst +++ b/docs/AccessControl.rst @@ -25,7 +25,7 @@ This optimizes for the most common case—a single-target application project—while not accidentally revealing entities to clients of a framework module. -.. warning:: This document has not yet been updated for SE-0117, which adds the +.. warning:: This document has not yet been updated for SE-0117, which adds the "open" level of access. @@ -220,7 +220,7 @@ functionality beyond ``private``, ``fileprivate``, ``internal``, and ``public``. limited with regards to extensions. Beyond that, however, a "class-only" limit forces code to be declared within the class that might otherwise naturally be a top-level helper or an extension method on another type. - + ``private`` and ``fileprivate`` serve the use case of limiting access to the implementation details of a class (even from the rest of the module!) while not tying access to the notion of type. @@ -232,7 +232,7 @@ functionality beyond ``private``, ``fileprivate``, ``internal``, and ``public``. plans for resilient APIs. Additionally, it increases the complexity of the access control model for both the compiler and for developers, and like "class-only" it is not immediately clear how it interacts with extensions. - + Though it is not compiler-enforced, members that might be considered "protected" are effectively publicly accessible, and thus should be marked ``public`` in Swift. They can still be documented as intended for overriding diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index d91a99b772ea6..292c69f3f1c11 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -42,18 +42,18 @@ if(LITRE_EXECUTABLE) set(subdir_CMakeLists) foreach(rst ${rst_files}) - # Prepare a testing directory containing a CMakeLists.txt + # Prepare a testing directory containing a CMakeLists.txt # and example files extracted from the .rst set(test_dir "litre-tests/${rst}.litre-tests") add_custom_command( - OUTPUT + OUTPUT ${test_dir}/CMakeLists.txt - COMMAND - ${LITRE_EXECUTABLE} + COMMAND + ${LITRE_EXECUTABLE} --default_compiler=${CMAKE_BINARY_DIR}/bin/swift "--dump_dir=${test_dir}" - --traceback + --traceback --report=severe # suppress most .rst errors. We have lots of them. ${CMAKE_CURRENT_SOURCE_DIR}/${rst} DEPENDS @@ -71,7 +71,7 @@ if(LITRE_EXECUTABLE) OUTPUT litre-top-CMakeLists.cmake COMMAND - ${CMAKE_COMMAND} -DOUTPUT=litre-top-CMakeLists.cmake + ${CMAKE_COMMAND} -DOUTPUT=litre-top-CMakeLists.cmake -DSOURCE_DIR=${CMAKE_CURRENT_SOURCE_DIR} -P ${CMAKE_CURRENT_SOURCE_DIR}/GenerateTopLevelLitreCMakeLists.cmake ${rst_files} @@ -134,7 +134,7 @@ if (LLVM_ENABLE_DOXYGEN) if (DOXYGEN_FOUND) set(abs_srcdir ${CMAKE_CURRENT_SOURCE_DIR}) set(abs_builddir ${CMAKE_CURRENT_BINARY_DIR}) - + if (HAVE_DOT) set(DOT ${LLVM_PATH_DOT}) endif() @@ -152,7 +152,7 @@ if (DOXYGEN_FOUND) set(enable_external_search "NO") set(extra_search_mappings "") endif() - + configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY) @@ -164,11 +164,11 @@ if (DOXYGEN_FOUND) set(enable_server_based_search) set(enable_external_search) set(extra_search_mappings) - + add_custom_target(doxygen-swift ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "Generating swift doxygen documentation." VERBATIM) + COMMENT "Generating swift doxygen documentation." VERBATIM) if(LLVM_BUILD_DOCS) add_dependencies(doxygen doxygen-swift) diff --git a/docs/CallingConvention.rst b/docs/CallingConvention.rst index 096a46cfa2cb2..f8269e706cc5d 100644 --- a/docs/CallingConvention.rst +++ b/docs/CallingConvention.rst @@ -59,8 +59,8 @@ of an l-value, but Swift does, so it's pertinent. In general, the terms "pass-by-X" and "call-by-X" are used interchangeably. It's unfortunate, because these conventions are argument specific, and functions can be passed multiple arguments -that are each handled in a different way. As such, we'll prefer -"pass-by-X" for consistency and to emphasize that these conventions +that are each handled in a different way. As such, we'll prefer +"pass-by-X" for consistency and to emphasize that these conventions are argument-specific. Pass-by-reference diff --git a/docs/ContinuousIntegration.md b/docs/ContinuousIntegration.md index b2aec2d08d010..f831ebb6c2867 100644 --- a/docs/ContinuousIntegration.md +++ b/docs/ContinuousIntegration.md @@ -70,8 +70,8 @@ A smoke test on Linux does the following: Platform | Comment | Check Status ------------ | ------- | ------------ - All supported platforms | @swift-ci Please test | Swift Test Linux Platform (smoke test)
Swift Test OS X Platform (smoke test)
Swift Test Linux Platform
Swift Test OS X Platform
- All supported platforms | @swift-ci Please clean test | Swift Test Linux Platform (smoke test)
Swift Test OS X Platform (smoke test)
Swift Test Linux Platform
Swift Test OS X Platform
+ All supported platforms | @swift-ci Please test | Swift Test Linux Platform (smoke test)
Swift Test OS X Platform (smoke test)
Swift Test Linux Platform
Swift Test OS X Platform
+ All supported platforms | @swift-ci Please clean test | Swift Test Linux Platform (smoke test)
Swift Test OS X Platform (smoke test)
Swift Test Linux Platform
Swift Test OS X Platform
All supported platforms | @swift-ci Please test and merge | Swift Test Linux Platform (smoke test)
Swift Test OS X Platform (smoke test)
Swift Test Linux Platform
Swift Test OS X Platform All supported platforms | @swift-ci Please clean test and merge | Swift Test Linux Platform (smoke test)
Swift Test OS X Platform (smoke test)
Swift Test Linux Platform
Swift Test OS X Platform OS X platform | @swift-ci Please test OS X platform | Swift Test OS X Platform (smoke test)
Swift Test OS X Platform @@ -123,9 +123,9 @@ A validation test on Linux does the following: ## Cross Repository Testing -Simply provide the URL from corresponding pull requests in the same comment as "@swift-ci Please test" phrase. List all of the pull requests and then provide the specific test phrase you would like to trigger. Currently, it will only merge the main pull request you requested testing from as opposed to all of the PR's. +Simply provide the URL from corresponding pull requests in the same comment as "@swift-ci Please test" phrase. List all of the pull requests and then provide the specific test phrase you would like to trigger. Currently, it will only merge the main pull request you requested testing from as opposed to all of the PR's. -For example: +For example: ``` Please test with following pull request: diff --git a/docs/DependencyAnalysis.rst b/docs/DependencyAnalysis.rst index dd35f732afcca..e418fe447a1dc 100644 --- a/docs/DependencyAnalysis.rst +++ b/docs/DependencyAnalysis.rst @@ -20,7 +20,7 @@ to is tantamount to a debug-time miscompile! Kinds of Dependency =================== -There are four major kinds of dependency between files: +There are four major kinds of dependency between files: - ``top-level``: use of an unqualified name that is looked up at module scope, and definition of a name at module scope. This includes free functions, diff --git a/docs/Driver.md b/docs/Driver.md index ab21873500a8d..4b1ed15ce822d 100644 --- a/docs/Driver.md +++ b/docs/Driver.md @@ -270,10 +270,10 @@ past that, so: 1. Generate an output file map that contains all the per-file outputs you care about. Most likely this is just the object files and incremental build - dependency files; everything else is an intermediate. (There should probably + dependency files; everything else is an intermediate. (There should probably be a tool that does this, perhaps built on what the package manager does.) -2. Set TMPDIR to somewhere you don't mind uninteresting intermediate files +2. Set TMPDIR to somewhere you don't mind uninteresting intermediate files going. 3. Do one of the following: diff --git a/docs/DriverInternals.rst b/docs/DriverInternals.rst index 72cd01a9679b5..ab6bd9260dc67 100644 --- a/docs/DriverInternals.rst +++ b/docs/DriverInternals.rst @@ -24,10 +24,10 @@ Driver Stages The compiler driver for Swift roughly follows the same design as Clang's compiler driver: -1. Parse: Command-line arguments are parsed into ``Arg``\ s. A ToolChain is +1. Parse: Command-line arguments are parsed into ``Arg``\ s. A ToolChain is selected based on the current platform. -2. Pipeline: Based on the arguments and inputs, a tree of ``Action``\ s is - generated. These are the high-level processing steps that need to occur, +2. Pipeline: Based on the arguments and inputs, a tree of ``Action``\ s is + generated. These are the high-level processing steps that need to occur, such as "compile this file" or "link the output of all compilation actions". 3. Bind: The ToolChain converts the ``Action``\ s into a set of ``Job``\ s. These are individual commands that need to be run, such as diff --git a/docs/ErrorHandling.rst b/docs/ErrorHandling.rst index 8f3ff71cd90fa..e871880ea944a 100644 --- a/docs/ErrorHandling.rst +++ b/docs/ErrorHandling.rst @@ -78,16 +78,16 @@ convention: - Methods default to *not* producing errors unless they are explicitly marked. - + - The control flow within a function is still mostly explicit: a maintainer can tell exactly which statements can produce an error, and a simple inspection reveals how the function reacts to the error. - + - Throwing an error provides similar performance to allocating an error and returning it -- it isn't an expensive, table-based stack unwinding process. - + - Cocoa APIs using standard ``NSError`` patterns can be imported into this world automatically. Other common patterns (e.g. ``CFError``, ``errno``) can be added to the model in future versions of Swift. @@ -180,7 +180,7 @@ allowed to throw is rejected by the compiler. It isn't possible to overload functions solely based on whether the functions throw. That is, this is not legal:: - func foo() { + func foo() { func foo() throws { A throwing method cannot override a non-throwing method or satisfy a @@ -299,7 +299,7 @@ generalized ``do`` statement:: // a conditionally-executed catch clause } catch _ { - // a catch-all clause. + // a catch-all clause. } As with ``switch`` statements, Swift makes an effort to understand diff --git a/docs/ErrorHandlingRationale.rst b/docs/ErrorHandlingRationale.rst index 8828e3cbc60c8..4457ac6c9865b 100644 --- a/docs/ErrorHandlingRationale.rst +++ b/docs/ErrorHandlingRationale.rst @@ -777,7 +777,7 @@ not free: to resume normal execution from the landing pad: if the landing pad only has clean-ups and therefore always restarts propagation, those registers will have been saved and restored further out. - + * Languages like C++, ObjC ARC, and Swift that have non-trivial clean-ups for many local variables tend to have many functions with interesting frames. This means both that the context-saving @@ -1576,7 +1576,7 @@ wrapped around an arbitrary expression:: // This try applies to readBool(). if try stream.readBool() { - + // This try applies to both of these calls. let x = try stream.readInt() + stream.readInt() diff --git a/docs/Generics.rst b/docs/Generics.rst index eceff59d9a086..0d1f5d79afae8 100644 --- a/docs/Generics.rst +++ b/docs/Generics.rst @@ -20,7 +20,7 @@ might be expressed as:: T value; Node *next; }; - + Node *first; }; @@ -35,7 +35,7 @@ such as a simple, linear search algorithm:: for (typename List::Node *result = list.first; result; result = result->next) if (result->value == value) return result; - + return 0; } @@ -259,7 +259,7 @@ As previously noted, protocols can contain both function requirements (which are in effect requirements for instance methods) and associated type requirements. Protocols can also contain operators, properties, and subscript operators:: - + protocol RandomAccessContainer : Collection { var count: Int func == (lhs: Self, rhs: Self) @@ -284,16 +284,16 @@ example, given:: } One could write a Circle struct such as:: - + struct Circle { var center : Point var radius : Int - + func draw() { // draw it } } - + Circle provides a draw() method with the same input and result types as required by the Shape protocol. Therefore, Circle conforms to Shape. @@ -304,7 +304,7 @@ also know how to "draw!":: struct Cowboy { var gun : SixShooter - + func draw() { // draw! } @@ -382,7 +382,7 @@ meet if it wants to conform to the protocol. There is a natural tension here, then, between larger protocols that make it easier to write generic algorithms, and smaller protocols that make it easier to write conforming types. For example, should a Numeric protocol implement all operations, e.g.,:: - + protocol Numeric { func +(lhs : Self, rhs : Self) -> Self func -(lhs : Self, rhs : Self) -> Self @@ -404,7 +404,7 @@ algorithms)? Both of the protocols express the same thing (semantically), because one can use the core operations (binary +, unary -) to implement the other algorithms. However, it's far easier to allow the protocol itself to provide default implementations:: - + protocol Numeric { func +(lhs : Self, rhs : Self) -> Self func -(lhs : Self, rhs : Self) -> Self { return lhs + -rhs } @@ -452,7 +452,7 @@ to implement. We can now see how Self types interact with subtype polymorphism. For example, say we have two values of type Comparable, and we try to compare them:: - var x : Comparable = ... + var x : Comparable = ... var y : Comparable = ... if x.isEqual(y) { // well-typed? } @@ -465,7 +465,7 @@ mode (aborting, throwing an exception, etc.) if the dynamic type check fails. To express types that meet the requirements of several protocols, one can just create a new protocol aggregating those protocols:: - + protocol SerializableDocument : Document, Serializable { } var doc : SerializableDocument print(doc.title()) // okay: title() is part of the Document protocol, so we can call it @@ -508,13 +508,13 @@ polymorphism. Protocols provide a natural way to express the constraints of a generic function in Swift. For example, one could define a generic linked list as:: - + struct ListNode { var Value : T enum NextNode { case Node : ListNode, End } var Next : NextNode } - + struct List { var First : ListNode::NextNode } @@ -553,12 +553,12 @@ able to constrain associated types. To do so, we introduce the notion of a "where" clause, which follows the signature of the generic type or function. For example, let's generalize our find algorithm to work on any ordered collection:: - + protocol OrderedCollection : Collection { func size() -> Int func getAt(_ index : Int) -> Element // Element is an associated type } - + func find( _ collection : C, value : C.Element) -> Int { @@ -676,7 +676,7 @@ language (generic functions can be "virtual"). The translation model is fairly simple. Consider the generic find() we implemented for lists, above:: - + func find(_ list : List, value : T) -> Int { var index = 0 var current = list.First @@ -766,7 +766,7 @@ Overloading Generic functions can be overloaded based entirely on constraints. For example, consider a binary search algorithm:: - + func binarySearch< C : EnumerableCollection where C.Element : Comparable >(_ collection : C, value : C.Element) @@ -778,17 +778,17 @@ consider a binary search algorithm:: protocol RandomAccessEnumerator : Enumerator { // splits a range in half, returning both halves - func split() -> (Enumerator, Enumerator) + func split() -> (Enumerator, Enumerator) } func binarySearch< - C : EnumerableCollection - where C.Element : Comparable, + C : EnumerableCollection + where C.Element : Comparable, C.EnumeratorType: RandomAccessEnumerator >(_ collection : C, value : C.Element) -> C.EnumeratorType { - // We can perform log(N) comparisons and log(N) range splits, + // We can perform log(N) comparisons and log(N) range splits, // so this is logarithmic time } @@ -806,7 +806,7 @@ minimal requirements:: C : EnumerableCollection where C.Element : Ordered >( _ collection : C, value : C.Element - ) -> C.EnumeratorType + ) -> C.EnumeratorType { binarySearch(collection, value) } @@ -876,7 +876,7 @@ which can be interpreted as either:: (integer_literal 10))) or:: - + (constructor Matrix (tuple (integer_literal 10) diff --git a/docs/GenericsManifesto.md b/docs/GenericsManifesto.md index 5056097fa3130..030aaf322b31f 100644 --- a/docs/GenericsManifesto.md +++ b/docs/GenericsManifesto.md @@ -202,7 +202,7 @@ protocol Sequence { } ``` -### Default generic arguments +### Default generic arguments Generic parameters could be given the ability to provide default arguments, which would be used in cases where the type argument is not specified and type inference could not determine the type argument. For example: @@ -250,7 +250,7 @@ extension P { } class C : P { - // gets the protocol extension's + // gets the protocol extension's } class D : C { @@ -325,7 +325,7 @@ Variadic generics would allow us to abstract over a set of generic parameters. T public struct ZipIterator<... Iterators : IteratorProtocol> : Iterator { // zero or more type parameters, each of which conforms to IteratorProtocol public typealias Element = (Iterators.Element...) // a tuple containing the element types of each iterator in Iterators - var (...iterators): (Iterators...) // zero or more stored properties, one for each type in Iterators + var (...iterators): (Iterators...) // zero or more stored properties, one for each type in Iterators var reachedEnd = false public mutating func next() -> Element? { @@ -343,7 +343,7 @@ public struct ZipIterator<... Iterators : IteratorProtocol> : Iterator { // zer public struct ZipSequence<...Sequences : Sequence> : Sequence { public typealias Iterator = ZipIterator // get the zip iterator with the iterator types of our Sequences - var (...sequences): (Sequences...) // zero or more stored properties, one for each type in Sequences + var (...sequences): (Sequences...) // zero or more stored properties, one for each type in Sequences // details ... } @@ -352,7 +352,7 @@ public struct ZipSequence<...Sequences : Sequence> : Sequence { Such a design could also work for function parameters, so we can pack together multiple function arguments with different types, e.g., ```Swift -public func zip<... Sequences : SequenceType>(... sequences: Sequences...) +public func zip<... Sequences : SequenceType>(... sequences: Sequences...) -> ZipSequence { return ZipSequence(sequences...) } @@ -453,7 +453,7 @@ func containsAll(element One could move the `where` clause to the end of the signature, so that the most important parts—name, generic parameter, parameters, result type—precede it: ```Swift -func containsAll(elements: S) -> Bool +func containsAll(elements: S) -> Bool where Sequence.Iterator.Element == Element ``` @@ -616,7 +616,7 @@ The actual requested feature here is the ability to say "Any type that conforms More importantly, modeling `Sequence` with generic parameters rather than associated types is tantalizing but wrong: you don't want a type conforming to `Sequence` in multiple ways, or (among other things) your `for..in` loops stop working, and you lose the ability to dynamically cast down to an existential `Sequence` without binding the `Element` type (again, see "Generalized existentials"). Use cases similar to the `ConstructibleFromValue` protocol above seem too few to justify the potential for confusion between associated types and generic parameters of protocols; we're better off not having the latter. -### Private conformances +### Private conformances Right now, a protocol conformance can be no less visible than the minimum of the conforming type's access and the protocol's access. Therefore, a public type conforming to a public protocol must provide the conformance publicly. One could imagine removing that restriction, so that one could introduce a private conformance: diff --git a/docs/HighLevelSILOptimizations.rst b/docs/HighLevelSILOptimizations.rst index bd6652cae2476..7cb9e455a639a 100644 --- a/docs/HighLevelSILOptimizations.rst +++ b/docs/HighLevelSILOptimizations.rst @@ -289,9 +289,9 @@ string.concat(lhs: String, rhs: String) -> String This operation can be optimized away in case of both operands being string literals. In this case, it can be replaced by a string literal representing a concatenation of both operands. - + string.makeUTF8(start: RawPointer, utf8CodeUnitCount: Word, isASCII: Int1) -> String - + Converts a built-in UTF8-encoded string literal into a string. string.makeUTF16(start: RawPointer, utf16CodeUnitCount: Word) -> String diff --git a/docs/InitializerProblems.rst b/docs/InitializerProblems.rst index c990f01089734..f465a1760f6a1 100644 --- a/docs/InitializerProblems.rst +++ b/docs/InitializerProblems.rst @@ -16,12 +16,12 @@ aren't so complicated: initializers, and (b) all properties have initial values. | Convenience initializers delegate. - | Convenience initializers are inherited if all of the superclass's + | Convenience initializers are inherited if all of the superclass's designated initializers are present. - | If you want to call an initializer on a dynamic type, it must be marked + | If you want to call an initializer on a dynamic type, it must be marked required. - | Protocols are one way to do this, so initializers that satisfy protocol + | Protocols are one way to do this, so initializers that satisfy protocol requirements must be required. | If your superclass has a required initializer, you must provide it somehow. @@ -42,11 +42,11 @@ With all our rules, we actually rule out some important use cases, like this one ``initWithContentsOfURL:ofType:error:``. If you perform initializations that must be done when creating new documents but not when opening existing documents, override ``initWithType:error:``. If you have any initializations - that apply only to documents that are opened, override - ``initWithContentsOfURL:ofType:error:``. If you have general + that apply only to documents that are opened, override + ``initWithContentsOfURL:ofType:error:``. If you have general initializations, override ``init``. In all three cases, be sure to invoke the superclass implementation as the first action. - + -- `Document-Based App Programming Guide for Mac`__ __ https://developer.apple.com/library/mac/documentation/DataManagement/Conceptual/DocBasedAppProgrammingGuideForOSX/ManagingLifecycle/ManagingLifecycle.html#//apple_ref/doc/uid/TP40011179-CH4-SW11 @@ -73,7 +73,7 @@ there are some patterns that cannot be written in Swift, such as this one:: } // other generator stuff } - + class AnyGeneratorImpl : AnyGenerator { var wrapped: WrappedGenerator @@ -95,11 +95,11 @@ We've had a number of ideas for improving the state of the world, including - Allow designated initializers to delegate to other designated initializers (using static dispatch). This makes convenience initializers a niche feature. -- Add the concept of factory initializers, which don't promise to return +- Add the concept of factory initializers, which don't promise to return ``Self``. These are either never inherited or must always be overridden in a subclass. -- Allow convenience initializers to chain to superclass convenience +- Allow convenience initializers to chain to superclass convenience initializers. This isn't strictly safe, but it permits the NSDocument idiom. None of these solve all the initializer problems listed above on their own, and diff --git a/docs/Lexicon.rst b/docs/Lexicon.rst index 7589715daecff..5679765bdaf14 100644 --- a/docs/Lexicon.rst +++ b/docs/Lexicon.rst @@ -13,7 +13,7 @@ source code, tests, and commit messages. See also the `LLVM lexicon`_. .. note:: This document uses Sphinx-specific features. If you are viewing this on - GitHub, you'll have to use raw mode, or download and build the docs + GitHub, you'll have to use raw mode, or download and build the docs yourself. .. glossary:: @@ -21,7 +21,7 @@ source code, tests, and commit messages. See also the `LLVM lexicon`_. archetype A placeholder for a generic parameter or an associated type within a generic context. Sometimes known as a "rigid type variable" in formal - CS literature. Directly stores its conforming protocols and nested + CS literature. Directly stores its conforming protocols and nested archetypes, if any. canonical SIL @@ -40,18 +40,18 @@ source code, tests, and commit messages. See also the `LLVM lexicon`_. the AST level. See also `witness table`. contextual type - 1. The expected type for a Swift sub-expression based on the rest of the + 1. The expected type for a Swift sub-expression based on the rest of the statement. For example, in the statement ``print(6 * 9)``, the contextual type of the expression ``6 * 9`` is ``Any``. 2. The type of a value or declaration from inside a potentially generic - context. This type may contain `archetypes ` and cannot be + context. This type may contain `archetypes ` and cannot be used directly from outside the context. Compare with `interface type`. DI (definite initialization / definitive initialization) The feature that no uninitialized variables, constants, or properties will be read by a program, or the analysis pass that operates on SIL to guarantee this. This was `discussed on Apple's Swift blog`__. - + __ https://developer.apple.com/swift/blog/?id=28 dup @@ -71,7 +71,7 @@ source code, tests, and commit messages. See also the `LLVM lexicon`_. iff "`if and only if`__". This term comes from mathematics. - + __ https://en.wikipedia.org/wiki/If_and_only_if interface type @@ -112,14 +112,14 @@ source code, tests, and commit messages. See also the `LLVM lexicon`_. The type of a value representing a type. Greg Parker has a good explanation of `Objective-C's "metaclasses"`__; because Swift has types that are *not* classes, a more general term is used. - + We also sometimes refer to a value representing a type as a "metatype object" or just "metatype", usually within low-level contexts like IRGen and LLDB. This is technically incorrect (it's just a "type object"), but the malapropism happened early in the project and has stuck around. - + __ http://sealiesoftware.com/blog/archive/2009/04/14/objc_explain_Classes_and_metaclasses.html - + model A type that conforms to a particular protocol. Sometimes "concrete model". Example: "Array and Set are both models of CollectionType". @@ -127,8 +127,8 @@ source code, tests, and commit messages. See also the `LLVM lexicon`_. module Has *many* uses in the Swift world. We may want to rename some of them. #1 and #2 are the most common. - - 1. A unit of API distribution and grouping. The ``import`` declaration + + 1. A unit of API distribution and grouping. The ``import`` declaration brings modules into scope. Represented as ModuleDecl in the compiler. 2. A compilation unit; that is, source files that are compiled together. These files may contain cross-references. Represented as "the main @@ -147,7 +147,7 @@ source code, tests, and commit messages. See also the `LLVM lexicon`_. 7. Shorthand for a "precompiled module file"; effectively "precompiled headers" for an entire Clang module. Never used directly by Swift. See also `module cache`. - + __ http://clang.llvm.org/docs/Modules.html module cache @@ -167,7 +167,7 @@ source code, tests, and commit messages. See also the `LLVM lexicon`_. patches that change functionality. open existential - An `existential` value with its dynamic type pulled out, so that the + An `existential` value with its dynamic type pulled out, so that the compiler can do something with it. overlay @@ -177,10 +177,10 @@ source code, tests, and commit messages. See also the `LLVM lexicon`_. Apple has a number of overlays for its own SDKs in stdlib/public/SDK/. PR - 1. "Problem Report": An issue reported in `LLVM's bug tracker`__. + 1. "Problem Report": An issue reported in `LLVM's bug tracker`__. See also `SR`. 2. "pull request" - + __ https://llvm.org/bugs/ primary file @@ -200,7 +200,7 @@ source code, tests, and commit messages. See also the `LLVM lexicon`_. Radar `Apple's bug-tracking system`__, or an issue reported on that system. - + __ https://bugreport.apple.com raw SIL diff --git a/docs/LibraryEvolution.rst b/docs/LibraryEvolution.rst index 07f90452a7f17..8d47f687a31fa 100644 --- a/docs/LibraryEvolution.rst +++ b/docs/LibraryEvolution.rst @@ -180,7 +180,7 @@ versioning information as well. A *versioned entity* represents anything with a runtime presence that a client may rely on; its version records when the entity was first exposed publicly in its library. Put another way, it is the oldest version of the library where the entity may be used. - + - Classes, structs, enums, and protocols may all be versioned entities. - Methods, properties, subscripts, and initializers may be versioned entities. - Top-level functions, variables, and constants may be versioned entities. @@ -555,7 +555,7 @@ clients to access them more efficiently. This restricts changes a fair amount: break existing clients. - Changing the body of an accessor is a `binary-compatible source-breaking change`. -- Adding/removing observing accessors is likewise a `binary-compatible +- Adding/removing observing accessors is likewise a `binary-compatible source-breaking change`. - Changing the initial value of a stored variable is still permitted. - Changing the value of a constant is a `binary-compatible source-breaking @@ -984,7 +984,7 @@ Finally, classes allow the following changes that do not apply to structs: implementation. - A non-final override of a method, subscript, property, or initializer may be removed as long as the generic parameters, formal parameters, and return type - *exactly* match the overridden declaration. Any existing callers should + *exactly* match the overridden declaration. Any existing callers should automatically use the superclass implementation. - Within an ``open`` class, any public method, subscript, or property may be marked ``open`` if it is not already marked ``final``. @@ -1654,7 +1654,7 @@ Recompiling changes a protocol's implementation @available(2.0) func equip() { print("Equipped.") } } - + extension Wearable where Self: MagicType { @available(2.0) func equip() { print("You put it on.") } @@ -1764,7 +1764,7 @@ Glossary errors when a client is recompiled. In most cases, a client that *hasn't* been recompiled may use the new behavior or the old behavior, or even a mix of both; however, this will always be deterministic (same behavior when - a program is re-run) and will not break Swift's memory-safety and + a program is re-run) and will not break Swift's memory-safety and type-safety guarantees. It is recommended that these kinds of changes are avoided just like those that break binary compatibility. diff --git a/docs/Literals.rst b/docs/Literals.rst index a55471e41f39e..6392f4d1d4327 100644 --- a/docs/Literals.rst +++ b/docs/Literals.rst @@ -42,7 +42,7 @@ library's CompilerProtocols.swift:: // Conforming types can be initialized with arbitrary string literals. public protocol ExpressibleByStringLiteral : ExpressibleByExtendedGraphemeClusterLiteral { - + typealias StringLiteralType : _ExpressibleByBuiltinStringLiteral // Create an instance initialized to `value`. init(stringLiteral value: StringLiteralType) @@ -82,7 +82,7 @@ data from the literal, and the arguments describe that raw data. So, the general runtime behavior is now clear: 1. The compiler generates raw string data. -2. Some type conforming to _ExpressibleByBuiltinStringLiteral is constructed from +2. Some type conforming to _ExpressibleByBuiltinStringLiteral is constructed from the raw string data. This will be a standard library type. 3. Some type conforming to ExpressibleByStringLiteral is constructed from the object constructed in step 2. This may be a user-defined type. This is the @@ -100,11 +100,11 @@ types. This algorithm can go forwards or backwards, since it's actually defined in terms of constraints, but it's easiest to understand as a linear process. -1. Filter the types provided by the context to only include those that are +1. Filter the types provided by the context to only include those that are ExpressibleByStringLiteral. 2. Using the associated StringLiteralType, find the appropriate ``_convertFromBuiltinStringLiteral``. -3. Using the type from step 1, find the appropriate +3. Using the type from step 1, find the appropriate ``convertFromStringLiteral``. 4. Build an expression tree with the appropriate calls. diff --git a/docs/Modules.rst b/docs/Modules.rst index c2380f228953b..16dfc4fec974c 100644 --- a/docs/Modules.rst +++ b/docs/Modules.rst @@ -39,7 +39,7 @@ You can also selectively import certain declarations from a module:: .. admonition:: Comparison with Other Languages Importing a module is much like importing a library in Ruby, Python, or Perl, - importing a class in Java, or including a header file in a C-family language. + importing a class in Java, or including a header file in a C-family language. However, unlike C, module files are not textually included and must be valid programs on their own, and may not be in a textual format at all. Unlike Java, declarations in a module are not visible at all until imported. And unlike the @@ -81,7 +81,7 @@ visible. If more than one imported module declares the same name, the full The one exception to this rule is declarations that must be compatible with Objective-C. Such declarations follow the usual Objective-C rules for name conflicts: all classes must have unique names, all protocols must have unique - names, and all constructors, methods, and properties must have unique names + names, and all constructors, methods, and properties must have unique names within their class (including inherited methods and properties). @@ -91,7 +91,7 @@ Modules may contain code In addition to declarations, modules may contain implementations of the functions they define. The compiler may choose to use this information when optimizing a user's program, usually by inlining the module code into a caller. -In some cases [#]_, the compiler may even use a module's function +In some cases [#]_, the compiler may even use a module's function implementations to produce more effective diagnostics. Modules can also contain `autolinking` information, which the compiler passes @@ -158,7 +158,7 @@ module names are conventionally capitalized. Foundation.SupportType() // from the class or from the module? - In both cases, the type takes priority over the module, but this should still + In both cases, the type takes priority over the module, but this should still be avoided. .. admonition:: TODO @@ -216,7 +216,7 @@ loaded with ``import``, but with a few important differences: .. admonition:: FIXME - This wouldn't belong in the user model at all except for the implicit + This wouldn't belong in the user model at all except for the implicit visibility thing. Is there a better way to talk about this? @@ -261,18 +261,18 @@ Submodules For large projects, it is usually desirable to break a single application or framework into subsystems, which Swift calls "submodules". A submodule is a -development-time construct used for grouping within a module. By default, -declarations within a submodule are considered "submodule-private", which +development-time construct used for grouping within a module. By default, +declarations within a submodule are considered "submodule-private", which means they are only visible within that submodule (rather than across the entire module). These declarations will not conflict with declarations in other -submodules that may have the same name. +submodules that may have the same name. Declarations explicitly marked "whole-module" or "API" are still visible across the entire module (even if declared within a submodule), and must have a unique name within that space. The `qualified name` of a declaration within a submodule consists of the -top-level module name, followed by the submodule name, followed by the +top-level module name, followed by the submodule name, followed by the declaration. .. note:: @@ -284,16 +284,16 @@ declaration. We need to decide once and for all whether implicit visibility applies across submodule boundaries, i.e. "can I access the public Swift.AST.Module from Swift.Sema without an import, or do I have to say ``import Swift.AST``?" - + Advantages of module-wide implicit visibility: - + - Better name conflict checking. (The alternative is a linker error, or worse *no* linker error if the names have different manglings.) - Less work if things move around. - Build time performance is consistent whether or not you use this feature. - + Advantages of submodule-only implicit visibility: - + - Code completion will include names of public things you don't care about. - We haven't actually tested the build time performance of any large Swift projects, so we don't know if we can actually handle targets that contain @@ -303,7 +303,7 @@ declaration. - In this mode, we could allow two "whole-module" declarations to have the same name, since they won't. (We could allow this in the other mode too but then the qualified name would always be required.) - + Both cases still use "submodule-only" as the default access control, so this only affects the implicit visibility of whole-module and public declarations. @@ -337,7 +337,7 @@ Clang Submodules ---------------- Clang also has a concept of "submodules", which are essentially hierarchically- -named modules. Unlike Swift's :ref:`submodules`, Clang submodules are visible +named modules. Unlike Swift's :ref:`submodules`, Clang submodules are visible from outside the module. It is conventional for a top-level Clang module to re-export all of its submodules, but sometimes certain submodules are specified to require an explicit import:: @@ -382,13 +382,13 @@ Accessing Swift declarations from Objective-C Using the new ``@import`` syntax, Objective-C translation units can import Swift modules as well. Swift declarations will be mirrored into Objective-C and can be called natively, just as Objective-C declarations are mirrored into -Swift for `Clang modules `. In this case, only the declarations +Swift for `Clang modules `. In this case, only the declarations compatible with Objective-C will be visible. .. admonition:: TODO - We need to actually do this, but it requires working on a branch of Clang, so - we're pushing it back in the schedule as far as possible. The workaround is + We need to actually do this, but it requires working on a branch of Clang, so + we're pushing it back in the schedule as far as possible. The workaround is to manually write header files for imported Swift classes. .. admonition:: TODO @@ -412,7 +412,7 @@ Glossary specify them at link time. Clang module - A module whose contents are generated from a C-family header or set of + A module whose contents are generated from a C-family header or set of headers. See Clang's Modules__ documentation for more information. __ http://clang.llvm.org/docs/Modules.html @@ -427,7 +427,7 @@ Glossary be created by users. import - To locate and read a module, then make its declarations available in the + To locate and read a module, then make its declarations available in the current context. library @@ -457,15 +457,15 @@ Glossary included the former module. serialized module - A particular encoding of a module that contains declarations that have - already been processed by the compiler. It may also contain implementations + A particular encoding of a module that contains declarations that have + already been processed by the compiler. It may also contain implementations of some function declarations in `SIL` form. - + SIL "Swift Intermediate Language", a stable IR for the distribution of inlineable code. - - + + target A dynamic library, framework, plug-in, or application to be built. A natural LTO boundary, and roughly the same as what Xcode requires diff --git a/docs/MutationModel.rst b/docs/MutationModel.rst index 4ef9016330d4a..7dce3526ef047 100644 --- a/docs/MutationModel.rst +++ b/docs/MutationModel.rst @@ -42,10 +42,10 @@ Consider:: What do we do with this? Since ``+=`` has an ``inout`` first argument, we detect this situation statically (hopefully one day we'll -have a better error message): +have a better error message): .. code-block:: swift-console - + :1:9: error: expression does not type-check w.title += " (parenthesized remark)" ~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -126,7 +126,7 @@ implicitly: var x = Number(42) x.increment() // mutating operation - + * passing it to a function attributed with ``@assignment``:: var y = 31 @@ -162,7 +162,7 @@ A subscript or property access expression is an rvalue if value type For example, consider this extension to our ``Number`` struct: - + .. parsed-literal:: extension Number { @@ -223,9 +223,9 @@ The Big Rule .. Error:: A program that applies a mutating operation to an rvalue is ill-formed :class: warning - + For example: - + .. parsed-literal:: clay = 43 // OK; a var is always assignable diff --git a/docs/ObjectInitialization.rst b/docs/ObjectInitialization.rst index e992645045943..fbe1b77060074 100644 --- a/docs/ObjectInitialization.rst +++ b/docs/ObjectInitialization.rst @@ -70,7 +70,7 @@ example, the following is a valid initializer:: completeInit() } - func completeInit() { /* ... */ } + func completeInit() { /* ... */ } } After all stored properties have been initialized, one is free to use @@ -96,7 +96,7 @@ in that order. For example, consider a subclass ``B`` of ``A``:: completeInitForB() // perform other tasks } - func completeInitForB() { /* ... */ } + func completeInitForB() { /* ... */ } } Consider the following construction of an object of type ``B``:: @@ -109,7 +109,7 @@ Consider the following construction of an object of type ``B``:: initialize stored properties *before* chaining to the superclass initializer. This is part of Swift's memory safety guarantee, and is discussed further in the section on `Three-Phase - Initialization`_. + Initialization`_. Initialization proceeds in several steps: @@ -164,7 +164,7 @@ to construct objects, using the same syntax. For example, the ``A`` initializer above can be used to build a new ``A`` object without any arguments:: - var a2 = A() // uses convenience initializer + var a2 = A() // uses convenience initializer Initializer Inheritance ~~~~~~~~~~~~~~~~~~~~~~~ @@ -189,14 +189,14 @@ Initialization proceeds as follows: ``B``'s designated initializer. 4. ``B``'s designated initializer initializes the stored property ``d`` to ``17.0``. -5. ``B``'s designated initializer chains to ``A``'s designated +5. ``B``'s designated initializer chains to ``A``'s designated initializer. 6. ``A``'s designated initializer initialize's the stored properties ``i`` and ``s``'. 7. ``A``'s designated initializer calls ``completeInit()``, then returns. 8. ``B``'s designated initializer calls ``completeInitForB()``, then - returns. + returns. 9. ``A``'s convenience initializer returns. Convenience initializers are only inherited under certain @@ -276,7 +276,7 @@ When a particular class does not specify any designated initializers, the implementation will synthesize initializers for the class when all of the class's stored properties have initial values in the class. The form of the synthesized initializers depends on the superclass (if -present). +present). When a superclass is present, the compiler synthesizes a new designated initializer in the subclass for each designated initializer @@ -356,8 +356,8 @@ the subclass might have taken over its own initialization (as with particular initializer, use the ``required`` attribute as follows:: class View { - @required init frame(Rect) { - /* initialize view */ + @required init frame(Rect) { + /* initialize view */ } } @@ -444,7 +444,7 @@ itself during initialization, one can write a de-initializer using The statements within a de-initializer (here, the call to ``close``) execute first, then the superclass's de-initializer is called. Finally, stored properties are released and the object is -deallocated. +deallocated. Methods Returning ``Self`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -560,7 +560,7 @@ call to the superclass initializer:: resilient to ``nil`` objects, this default behavior eliminates (or hides) many such initialization bugs. In Swift, however, the zero-initialized state is less likely to be valid, and the memory - safety goals are stronger, so zero-initialization does not suffice. + safety goals are stronger, so zero-initialization does not suffice. When initializing a ``B`` object, the ``NSLog`` statement will print:: @@ -576,10 +576,10 @@ of the current class (not its superclasses!). Additionally, this initialization directly writes to the storage of the stored properties, and does not call any setter or ``willSet``/``didSet`` method. In this phase, it is not possible to read any of the stored -properties. +properties. 2. Call to superclass initializer, if any. As with the first step, -``self`` cannot be accessed at all. +``self`` cannot be accessed at all. 3. Perform any additional initialization tasks, which may call methods on ``self``, access properties, and so on. diff --git a/docs/OptimizationTips.rst b/docs/OptimizationTips.rst index be37779cc5476..158a94146696c 100644 --- a/docs/OptimizationTips.rst +++ b/docs/OptimizationTips.rst @@ -360,21 +360,21 @@ about 10 times. :: - /// --------------- + /// --------------- /// Framework.swift public protocol Pingable { func ping() -> Self } public protocol Playable { func play() } - + extension Int : Pingable { public func ping() -> Int { return self + 1 } } - + public class Game : Playable { var t : T - + public init (_ v : T) {t = v} - + @_specialize(Int) public func play() { for _ in 0...100_000_000 { t = t.ping() } @@ -599,7 +599,7 @@ Footnotes .. [#] i.e. a direct load of a class's field or a direct call to a function. -.. [#] An optimization technique in which a copy will be made if and only if +.. [#] An optimization technique in which a copy will be made if and only if a modification happens to the original copy, otherwise a pointer will be given. .. [#] In certain cases the optimizer is able to via inlining and ARC diff --git a/docs/PatternMatching.rst b/docs/PatternMatching.rst index 9247fe9748789..25f7ab1165c12 100644 --- a/docs/PatternMatching.rst +++ b/docs/PatternMatching.rst @@ -21,7 +21,7 @@ When type theorists consider a programming language, we break it down like this: Swift has a pretty small set of types right now: -* Fundamental types: currently i1, i8, i16, i32, and i64; +* Fundamental types: currently i1, i8, i16, i32, and i64; float and double; eventually maybe others. * Function types. * Tuples. Heterogeneous fixed-length products. Swift's system @@ -297,7 +297,7 @@ braces end up causing a lot of unnecessary vertical whitespace, like so:: case .bar { // … } - + So instead, let's require the switch statement to have braces, and we'll allow the cases to be written without them:: @@ -441,7 +441,7 @@ I think this should bind looser than any binary operators except assignments; effectively we should have:: expr-binary ::= # most of the current expr grammar - + expr ::= expr-binary expr ::= expr-binary 'is' expr-primary pattern-guard? diff --git a/docs/Runtime.md b/docs/Runtime.md index aa2155923f805..2da081396fba6 100644 --- a/docs/Runtime.md +++ b/docs/Runtime.md @@ -23,7 +23,7 @@ information that only pertains to ObjC interop, are marked **ObjC-only**. Entry points in this section are intended to be removed or internalized before ABI stabilization. -### Exported C++ symbols +### Exported C++ symbols **ABI TODO**: Any exported C++ symbols are implementation details that are not intended to be part of the stable runtime interface. diff --git a/docs/SIL.rst b/docs/SIL.rst index 96c8ec3ce8e03..0cd328b68f5c2 100644 --- a/docs/SIL.rst +++ b/docs/SIL.rst @@ -12,13 +12,13 @@ Abstract SIL is an SSA-form IR with high-level semantic information designed to implement the Swift programming language. SIL accommodates the following use cases: -- A set of guaranteed high-level optimizations that provide a predictable +- A set of guaranteed high-level optimizations that provide a predictable baseline for runtime and diagnostic behavior. - Diagnostic dataflow analysis passes that enforce Swift language requirements, such as definitive initialization of variables and constructors, code reachability, switch coverage. - High-level optimization passes, including retain/release optimization, - dynamic method devirtualization, closure inlining, memory allocation promotion, + dynamic method devirtualization, closure inlining, memory allocation promotion, and generic function instantiation. - A stable distribution format that can be used to distribute "fragile" inlineable or generic code with Swift library modules, to be optimized into @@ -80,8 +80,8 @@ predictable. of which performs capture analysis to promote ``alloc_box`` instructions to ``alloc_stack``, and the second of which promotes non-address-exposed ``alloc_stack`` instructions to SSA registers. -- **Constant propagation** folds constant expressions and propagates the constant values. - If an arithmetic overflow occurs during the constant expression computation, a diagnostic +- **Constant propagation** folds constant expressions and propagates the constant values. + If an arithmetic overflow occurs during the constant expression computation, a diagnostic is issued. - **Return analysis** verifies that each function returns a value on every code path and doesn't "fall of the end" of its definition, which is an error. @@ -375,7 +375,7 @@ Addresses of address-only types (see below) can only be used with instructions that manipulate their operands indirectly by address, such as ``copy_addr`` or ``destroy_addr``, or as arguments to functions. It is illegal to have a value of type ``$T`` if ``T`` is address-only. - + Addresses are not reference-counted pointers like class values are. They cannot be retained or released. @@ -492,7 +492,7 @@ number of ways: instructions. These arguments appear in the order in which they appear in the result list, always before any parameters. - Direct results correspond to direct return values of type ``T``. A + Direct results correspond to direct return values of type ``T``. A SIL function type has a ``return type`` derived from its direct results in the following way: when there is a single direct result, the return type is the type of that result; otherwise, it is the tuple type of the @@ -653,7 +653,7 @@ types. Function types are transformed in order to encode additional attributes: @convention(*convention*) attribute. This is similar to the language-level ``@convention`` - attribute, though SIL extends the set of supported conventions with + attribute, though SIL extends the set of supported conventions with additional distinctions not exposed at the language level: - ``@convention(thin)`` indicates a "thin" function reference, which uses @@ -872,7 +872,7 @@ Some SIL instructions need to reference Swift declarations directly. These references are introduced with the ``#`` sigil followed by the fully qualified name of the Swift declaration. Some Swift declarations are decomposed into multiple entities at the SIL level. These are distinguished by -following the qualified name with ``!`` and one or more ``.``-separated component +following the qualified name with ``!`` and one or more ``.``-separated component entity discriminators: - ``getter``: the getter function for a ``var`` declaration @@ -935,7 +935,7 @@ different SIL modules are *linked*, i.e. treated as the same object. A linkage is *external* if it ends with the suffix ``external``. An object must be a definition if its linkage is not external. -All functions, global variables, and witness tables have linkage. +All functions, global variables, and witness tables have linkage. The default linkage of a definition is ``public``. The default linkage of a declaration is ``public_external``. (These may eventually change to ``hidden`` and ``hidden_external``, respectively.) @@ -1292,7 +1292,7 @@ separate arguments, both in the entry point basic block of the callee, and in the ``apply`` instructions used by callers:: func foo(_ x:Int, y:Int) - + sil @foo : $(x:Int, y:Int) -> () { entry(%x : $Int, %y : $Int): ... @@ -1619,10 +1619,10 @@ Consider the following SIL:: } struct S1 { var elt: Element - } + } struct S2 { var elt: Element - } + } %adr1 = struct_element_addr %ptr1 : $*S1, #S.elt %adr2 = struct_element_addr %ptr2 : $*S2, #S.elt @@ -1811,7 +1811,7 @@ of the allocated memory. If a type is runtime-sized, the compiler must emit code to potentially dynamically allocate memory. So there is no guarantee that the allocated -memory is really located on the stack. +memory is really located on the stack. ``alloc_stack`` marks the start of the lifetime of the value; the allocation must be balanced with a ``dealloc_stack`` instruction to @@ -1892,7 +1892,7 @@ for ``alloc_ref``. See ``alloc_ref`` for details. alloc_box ````````` :: - + sil-instruction ::= 'alloc_box' sil-type (',' debug-var-attr)* %1 = alloc_box $T @@ -2095,9 +2095,9 @@ debug_value :: sil-instruction ::= debug_value sil-operand (',' debug-var-attr)* - + debug_value %1 : $Int - + This indicates that the value of a declaration with loadable type has changed value to the specified operand. The declaration in question is identified by the SILLocation attached to the debug_value instruction. @@ -2122,9 +2122,9 @@ debug_value_addr :: sil-instruction ::= debug_value_addr sil-operand (',' debug-var-attr)* - + debug_value_addr %7 : $*SomeProtocol - + This indicates that the value of a declaration with address-only type has changed value to the specified operand. The declaration in question is identified by the SILLocation attached to the @@ -2468,7 +2468,7 @@ bind_memory Binds memory at ``Builtin.RawPointer`` value ``%0`` to type ``$T`` with enough capacity to hold ``%1`` values. See SE-0107: UnsafeRawPointer. - + Reference Counting ~~~~~~~~~~~~~~~~~~ @@ -2508,7 +2508,7 @@ for several reasons: strong_retain ````````````` :: - + sil-instruction ::= 'strong_retain' sil-operand strong_retain %0 : $T @@ -2547,7 +2547,7 @@ execution of this instruction. strong_retain_unowned ````````````````````` :: - + sil-instruction ::= 'strong_retain_unowned' sil-operand strong_retain_unowned %0 : $@unowned T @@ -2559,7 +2559,7 @@ is still positive, then increases it by one. unowned_retain `````````````` :: - + sil-instruction ::= 'unowned_retain' sil-operand unowned_retain %0 : $@unowned T @@ -2570,7 +2570,7 @@ Increments the unowned reference count of the heap object underlying ``%0``. unowned_release ``````````````` :: - + sil-instruction ::= 'unowned_release' sil-operand unowned_release %0 : $@unowned T @@ -2881,7 +2881,7 @@ If: - the referenced method is not a ``foreign`` method, - and the static type of the class instance is known, or the method is known to be final, - + then the instruction is a candidate for devirtualization optimization. A devirtualization pass can consult the module's `VTables`_ to find the SIL function that implements the method and promote the instruction to a @@ -2893,7 +2893,7 @@ super_method sil-instruction ::= 'super_method' sil-method-attributes? sil-operand ',' sil-decl-ref ':' sil-type - + %1 = super_method %0 : $T, #Super.method!1.foreign : $@convention(thin) U -> V // %0 must be of a non-root class type or class metatype $T // #Super.method!1.foreign must be a reference to an ObjC method of T's @@ -2941,7 +2941,7 @@ dynamic_method // #X.method!1 must be a reference to an @objc method of any class // or protocol type // - // The "self" argument of the method type $@convention(thin) U -> V must be + // The "self" argument of the method type $@convention(thin) U -> V must be // Builtin.UnknownObject Looks up the implementation of an Objective-C method with the same @@ -2954,13 +2954,13 @@ It is undefined behavior if the dynamic type of the operand does not have an implementation for the Objective-C method with the selector to which the ``dynamic_method`` instruction refers, or if that implementation has parameter or result types that are incompatible -with the method referenced by ``dynamic_method``. +with the method referenced by ``dynamic_method``. This instruction should only be used in cases where its result will be immediately consumed by an operation that performs the selector check itself (e.g., an ``apply`` that lowers to ``objc_msgSend``). To query whether the operand has an implementation for the given method and safely handle the case where it does not, use -`dynamic_method_br`_. +`dynamic_method_br`_. Function Application ~~~~~~~~~~~~~~~~~~~~ @@ -3112,7 +3112,7 @@ following example:: } lowers to an uncurried entry point and is curried in the enclosing function:: - + func @bar : $@convention(thin) (Int, @box Int, *Int) -> Int { entry(%y : $Int, %x_box : $@box Int, %x_address : $*Int): // ... body of bar ... @@ -3319,7 +3319,7 @@ autorelease_value tuple ````` :: - + sil-instruction ::= 'tuple' sil-tuple-elements sil-tuple-elements ::= '(' (sil-operand (',' sil-operand)*)? ')' sil-tuple-elements ::= sil-type '(' (sil-value (',' sil-value)*)? ')' @@ -3479,10 +3479,10 @@ discriminator and is done with the `switch_enum`_ terminator:: sil @switch_foo : $(Foo) -> () { entry(%foo : $Foo): switch_enum %foo : $Foo, case #Foo.A!enumelt.1: a_dest, case #Foo.B!enumelt.1: b_dest - + a_dest(%a : $Int): /* use %a */ - + b_dest(%b : $String): /* use %b */ } @@ -3497,11 +3497,11 @@ projecting the enum value with `unchecked_take_enum_data_addr`_:: entry(%foo : $*Foo): switch_enum_addr %foo : $*Foo, case #Foo.A!enumelt.1: a_dest, \ case #Foo.B!enumelt.1: b_dest - + a_dest: %a = unchecked_take_enum_data_addr %foo : $*Foo, #Foo.A!enumelt.1 /* use %a */ - + b_dest: %b = unchecked_take_enum_data_addr %foo : $*Foo, #Foo.B!enumelt.1 /* use %b */ @@ -3749,7 +3749,7 @@ more expensive ``alloc_existential_box``:: init_existential_addr ````````````````````` :: - + sil-instruction ::= 'init_existential_addr' sil-operand ',' sil-type %1 = init_existential_addr %0 : $*P, $T @@ -3795,8 +3795,8 @@ open_existential_addr %1 = open_existential_addr %0 : $*P to $*@opened P // %0 must be of a $*P type for non-class protocol or protocol composition // type P - // $*@opened P must be a unique archetype that refers to an opened - // existential type P. + // $*@opened P must be a unique archetype that refers to an opened + // existential type P. // %1 will be of type $*P Obtains the address of the concrete value inside the existential @@ -3829,14 +3829,14 @@ open_existential_ref %1 = open_existential_ref %0 : $P to $@opened P // %0 must be of a $P type for a class protocol or protocol composition - // $@opened P must be a unique archetype that refers to an opened + // $@opened P must be a unique archetype that refers to an opened // existential type P // %1 will be of type $@opened P Extracts the class instance reference from a class existential container. The protocol conformances associated with this existential -container are associated directly with the archetype ``@opened P``. This -pointer can be used with any operation on archetypes, such as +container are associated directly with the archetype ``@opened P``. This +pointer can be used with any operation on archetypes, such as ``witness_method``. When the operand is of metatype type, the result will be the metatype of the opened archetype. @@ -3926,7 +3926,7 @@ Projects the address of the value inside a boxed existential container, and uses the enclosed type and protocol conformance metadata to bind the opened archetype ``$@opened P``. The result address is dependent on both the owning box and the enclosing function; in order to "open" a boxed -existential that has directly adopted a class reference, temporary scratch +existential that has directly adopted a class reference, temporary scratch space may need to have been allocated. dealloc_existential_box @@ -4122,7 +4122,7 @@ heap object reference to an address using ``pointer_to_address``. raw_pointer_to_ref `````````````````` :: - + sil-instruction ::= 'raw_pointer_to_ref' sil-operand 'to' sil-type %1 = raw_pointer_to_ref %0 : $Builtin.RawPointer to $C @@ -4408,7 +4408,7 @@ a basic block. unreachable ``````````` :: - + sil-terminator ::= 'unreachable' unreachable @@ -4421,7 +4421,7 @@ no-return function. return `````` :: - + sil-terminator ::= 'return' sil-operand return %0 : $T @@ -4441,7 +4441,7 @@ A function must not contain more than one ``return`` instruction. throw ````` :: - + sil-terminator ::= 'throw' sil-operand throw %0 : $T @@ -4668,7 +4668,7 @@ dynamic_method_br ````````````````` :: - sil-terminator ::= 'dynamic_method_br' sil-operand ',' sil-decl-ref + sil-terminator ::= 'dynamic_method_br' sil-operand ',' sil-decl-ref ',' sil-identifier ',' sil-identifier dynamic_method_br %0 : $P, #X.method!1, bb1, bb2 @@ -4738,7 +4738,7 @@ transferred to ``bb2``. try_apply ````````` :: - + sil-terminator ::= 'try_apply' sil-value sil-apply-substitution-list? '(' (sil-value (',' sil-value)*)? ')' @@ -4749,7 +4749,7 @@ try_apply normal bb1, error bb2 bb1(%3 : R): bb2(%4 : E): - + // Note that the type of the callee '%0' is specified *after* the arguments // %0 must be of a concrete function type $(A, B, ...) -> (R, @error E) // %1, %2, etc. must be of the argument types $A, $B, etc. diff --git a/docs/SequencesAndCollections.rst b/docs/SequencesAndCollections.rst index d79d88b093eb9..ee40a71f9e2d8 100644 --- a/docs/SequencesAndCollections.rst +++ b/docs/SequencesAndCollections.rst @@ -86,7 +86,7 @@ something like this:: protocol NaiveIteratorProtocol { typealias Element var current() -> Element // get the current element - mutating func advance() // advance to the next element + mutating func advance() // advance to the next element var isExhausted: Bool // detect whether there are more elements } @@ -123,7 +123,7 @@ implement a generic `for`\ …\ `in` loop. support for buffering would fit nicely into the scheme, should it prove important:: - public protocol BufferedIteratorProtocol + public protocol BufferedIteratorProtocol : IteratorProtocol { var latest: Element? {get} } @@ -140,7 +140,7 @@ implement a generic `for`\ …\ `in` loop. } public func next() -> Element? { latest = _baseIterator.next() ?? latest - return latest + return latest } public private(set) var latest: I.Element? private var _baseIterator: I @@ -156,7 +156,7 @@ end. For example:: // Return an array containing the elements of `source`, with // `separator` interposed between each consecutive pair. func array( - _ source: S, + _ source: S, withSeparator separator: S.Iterator.Element ) -> [S.Iterator.Element] { var result: [S.Iterator.Element] = [] @@ -215,7 +215,7 @@ Collections A **collection** is a stable sequence with addressable "positions," represented by an associated `Index` type:: - + protocol CollectionType : SequenceType { typealias Index : ForwardIndexType // a position subscript(i: Index) -> Iterator.Element {get} diff --git a/docs/StdlibAPIGuidelines.rst b/docs/StdlibAPIGuidelines.rst index de7ca59357bbd..6c9cdb92335e2 100644 --- a/docs/StdlibAPIGuidelines.rst +++ b/docs/StdlibAPIGuidelines.rst @@ -31,7 +31,7 @@ The First Parameter * The first parameter to a function, method, or initializer typically does not have an argument label: - + .. parsed-literal:: alligators.insert(fred) // yes @@ -64,21 +64,21 @@ The First Parameter aPosition.distance\ **To**\ (otherPosition) // we're not "indexing x" - if let position = aSet.index\ **Of**\ (x) { ... } + if let position = aSet.index\ **Of**\ (x) { ... } * Argument labels are used on first parameters to denote special cases: - + .. parsed-literal:: // Normal case: result has same value as argument (traps on overflow) - Int(aUInt) + Int(aUInt) // Special: interprets the sign bit as a high bit, changes value - Int(**bitPattern**: aUInt) + Int(**bitPattern**: aUInt) // Special: keeps only the bits that fit, losing information - Int32(**truncatingBitPattern**: anInt64) + Int32(**truncatingBitPattern**: anInt64) Subsequent Parameters --------------------- @@ -91,7 +91,7 @@ Subsequent Parameters x.replaceSubrange(r, **with:** someElements) p.initializeFrom(q, **count:** n) - + * Second and later parameters are always labeled except in cases where there's no useful distinction of roles:: @@ -101,7 +101,7 @@ Subsequent Parameters Other Differences ----------------- - + * We don't use namespace prefixes such as "`NS`", relying instead on the language's own facilities. @@ -168,10 +168,10 @@ library, but are compatible with the Cocoa guidelines. /// /// Complexity: O(\`count\`) mutating func reserveCapacity(_ **minimumCapacity**: Int) - -* Type parameter names of generic types describe the role of the + +* Type parameter names of generic types describe the role of the parameter, e.g. - + .. parsed-literal:: struct Dictionary<**Key**, **Value**> { // *not* Dictionary<**K**, **V**> @@ -208,7 +208,7 @@ Prefixes and Suffixes * `Any` is used as a prefix to denote "type erasure," e.g. `AnySequence` wraps any sequence with element type `T`, conforms to `SequenceType` itself, and forwards all operations to the - wrapped sequence. When handling the wrapper, the specific type of + wrapped sequence. When handling the wrapper, the specific type of the wrapped sequence is fully hidden. * `Custom` is used as a prefix for special protocols that will always diff --git a/docs/StoredAndComputedVariables.rst b/docs/StoredAndComputedVariables.rst index 42bd2084979de..3d8c1964be9f9 100644 --- a/docs/StoredAndComputedVariables.rst +++ b/docs/StoredAndComputedVariables.rst @@ -11,7 +11,7 @@ Stored and Computed Variables Variables are declared using the ``var`` keyword. These declarations are valid at the top level, within types, and within code bodies, and are respectively known as *global variables,* *member variables,* and *local variables.* -Member variables are commonly referred to as *properties.* +Member variables are commonly referred to as *properties.* Every variable declaration can be classified as either *stored* or *computed.* Member variables inherited from a superclass obey slightly different rules. @@ -187,7 +187,7 @@ in the usual way:: return .Black } } - + class Colorful : Base { var color : Color } @@ -199,7 +199,7 @@ The new stored variable may have observing accessors:: class MemoryColorful : Base { var oldColors : Array = [] - + var color : Color { willSet { oldColors.append(color) @@ -239,7 +239,7 @@ A subclass may override the superclass's variable with a new computed variable:: } } } - + class BrightlyColored : ColorBase { var color : Color { get { @@ -265,7 +265,7 @@ member variable:: class TrackingColored : ColorBase { var prevColor : Color? - + var color : Color { willSet { prevColor = color diff --git a/docs/StringDesign.rst b/docs/StringDesign.rst index d80004cc18e48..19de9a50a57a8 100644 --- a/docs/StringDesign.rst +++ b/docs/StringDesign.rst @@ -4,8 +4,8 @@ .. raw:: html -