HTTP/2 200 date: Fri, 25 Jul 2025 05:01:52 GMT content-type: text/plain; charset=utf-8 vary: X-PJAX, X-PJAX-Container, Turbo-Visit, Turbo-Frame, X-Requested-With,Accept-Encoding, Accept, X-Requested-With x-repository-download: git clone https://github.com/radex/swift_stdlib.git etag: W/"75df1716a383e1f7f0006d76a868acaf" cache-control: max-age=0, private, must-revalidate strict-transport-security: max-age=31536000; includeSubdomains; preload x-frame-options: deny x-content-type-options: nosniff x-xss-protection: 0 referrer-policy: no-referrer-when-downgrade content-security-policy: default-src 'none'; base-uri 'self'; child-src github.githubassets.com github.com/assets-cdn/worker/ github.com/assets/ gist.github.com/assets-cdn/worker/; connect-src 'self' uploads.github.com www.githubstatus.com collector.github.com raw.githubusercontent.com api.github.com github-cloud.s3.amazonaws.com github-production-repository-file-5c1aeb.s3.amazonaws.com github-production-upload-manifest-file-7fdce7.s3.amazonaws.com github-production-user-asset-6210df.s3.amazonaws.com *.rel.tunnels.api.visualstudio.com wss://*.rel.tunnels.api.visualstudio.com objects-origin.githubusercontent.com copilot-proxy.githubusercontent.com proxy.individual.githubcopilot.com proxy.business.githubcopilot.com proxy.enterprise.githubcopilot.com *.actions.githubusercontent.com wss://*.actions.githubusercontent.com productionresultssa0.blob.core.windows.net/ productionresultssa1.blob.core.windows.net/ productionresultssa2.blob.core.windows.net/ productionresultssa3.blob.core.windows.net/ productionresultssa4.blob.core.windows.net/ productionresultssa5.blob.core.windows.net/ productionresultssa6.blob.core.windows.net/ productionresultssa7.blob.core.windows.net/ productionresultssa8.blob.core.windows.net/ productionresultssa9.blob.core.windows.net/ productionresultssa10.blob.core.windows.net/ productionresultssa11.blob.core.windows.net/ productionresultssa12.blob.core.windows.net/ productionresultssa13.blob.core.windows.net/ productionresultssa14.blob.core.windows.net/ productionresultssa15.blob.core.windows.net/ productionresultssa16.blob.core.windows.net/ productionresultssa17.blob.core.windows.net/ productionresultssa18.blob.core.windows.net/ productionresultssa19.blob.core.windows.net/ github-production-repository-image-32fea6.s3.amazonaws.com github-production-release-asset-2e65be.s3.amazonaws.com insights.github.com wss://alive.github.com api.githubcopilot.com api.individual.githubcopilot.com api.business.githubcopilot.com api.enterprise.githubcopilot.com; font-src github.githubassets.com; form-action 'self' github.com gist.github.com copilot-workspace.githubnext.com objects-origin.githubusercontent.com; frame-ancestors 'none'; frame-src viewscreen.githubusercontent.com notebooks.githubusercontent.com; img-src 'self' data: blob: github.githubassets.com media.githubusercontent.com camo.githubusercontent.com identicons.github.com avatars.githubusercontent.com private-avatars.githubusercontent.com github-cloud.s3.amazonaws.com objects.githubusercontent.com release-assets.githubusercontent.com secured-user-images.githubusercontent.com/ user-images.githubusercontent.com/ private-user-images.githubusercontent.com opengraph.githubassets.com copilotprodattachments.blob.core.windows.net/github-production-copilot-attachments/ github-production-user-asset-6210df.s3.amazonaws.com customer-stories-feed.github.com spotlights-feed.github.com objects-origin.githubusercontent.com *.githubusercontent.com; manifest-src 'self'; media-src github.com user-images.githubusercontent.com/ secured-user-images.githubusercontent.com/ private-user-images.githubusercontent.com github-production-user-asset-6210df.s3.amazonaws.com gist.github.com; script-src github.githubassets.com; style-src 'unsafe-inline' github.githubassets.com; upgrade-insecure-requests; worker-src github.githubassets.com github.com/assets-cdn/worker/ github.com/assets/ gist.github.com/assets-cdn/worker/ server: github.com content-encoding: gzip accept-ranges: bytes set-cookie: _gh_sess=ziNLLQeqdU2ASj10w0i3kVJca2Yb%2Bxn%2F7OLM6RYUq%2B%2BVa5dLUgYnAyUI0%2Ba97Xh2UABQT%2Bfio7Bi0yVlomFJ5A8%2Fsq3BLiNHtuS7m2G0kEeaf1kVK5FuM0Trh9lq4NvWrLrvIWZ8VXte0blkEA%2FLL7r1m4%2FWu8V5SCm3mb8Ha89Q7ByYQ8R2z1NvpzcuJPMcjh07qkWpXWnrWn%2BEV2DxWzsbLUd4%2BS6TuJa5qnCszg3O48yS2iXqTY0eSE9TN97Glv1IEjM%2FnHooNODWTRdGZw%3D%3D--O4hQRysWBqem7Ntx--WatlnAm55UPLBVWM2BSk3A%3D%3D; Path=/; HttpOnly; Secure; SameSite=Lax set-cookie: _octo=GH1.1.1195349414.1753419712; Path=/; Domain=github.com; Expires=Sat, 25 Jul 2026 05:01:52 GMT; Secure; SameSite=Lax set-cookie: logged_in=no; Path=/; Domain=github.com; Expires=Sat, 25 Jul 2026 05:01:52 GMT; HttpOnly; Secure; SameSite=Lax content-length: 50499 x-github-request-id: E84A:2026F8:1F7170:2A8E3F:68830FC0 diff --git a/stdlib.swift b/stdlib.swift index a85a6bd..b6a9a20 100644 --- a/stdlib.swift +++ b/stdlib.swift @@ -1,10 +1,15 @@ -infix operator |= { +infix operator ~> { + associativity left + precedence 255 +} + +infix operator += { associativity right precedence 90 assignment } -infix operator += { +infix operator -= { associativity right precedence 90 assignment @@ -15,12 +20,6 @@ infix operator ... { precedence 135 } -infix operator -= { - associativity right - precedence 90 - assignment -} - infix operator &% { associativity left precedence 150 @@ -78,19 +77,19 @@ infix operator ^= { assignment } -infix operator ^ { - associativity left - precedence 140 -} - infix operator ?? { associativity right precedence 110 } -infix operator != { - associativity none - precedence 130 +infix operator ^ { + associativity left + precedence 140 +} + +infix operator | { + associativity left + precedence 140 } infix operator &= { @@ -120,7 +119,7 @@ infix operator * { precedence 150 } -infix operator > { +infix operator < { associativity none precedence 130 } @@ -130,10 +129,9 @@ infix operator + { precedence 140 } -infix operator %= { - associativity right - precedence 90 - assignment +infix operator >> { + associativity none + precedence 160 } infix operator - { @@ -152,14 +150,14 @@ infix operator <<= { assignment } -infix operator < { +infix operator !== { associativity none precedence 130 } -infix operator | { - associativity left - precedence 140 +infix operator ~= { + associativity none + precedence 130 } infix operator || { @@ -172,52 +170,54 @@ infix operator << { precedence 160 } +infix operator |= { + associativity right + precedence 90 + assignment +} + infix operator <= { associativity none precedence 130 } -infix operator ~> { - associativity left - precedence 255 +infix operator >= { + associativity none + precedence 130 } -infix operator >>= { +infix operator %= { associativity right precedence 90 assignment } -infix operator >> { - associativity none - precedence 160 -} - -infix operator !== { +infix operator != { associativity none precedence 130 } -infix operator >= { +infix operator > { associativity none precedence 130 } -infix operator ~= { - associativity none - precedence 130 +infix operator >>= { + associativity right + precedence 90 + assignment } -prefix operator -- { +prefix operator - { } -prefix operator ++ { +prefix operator ~ { } -prefix operator - { +prefix operator -- { } -prefix operator ~ { +prefix operator ++ { } prefix operator + { @@ -226,25 +226,23 @@ prefix operator + { prefix operator ! { } -postfix operator -- { -} - postfix operator ++ { } -prefix func !(a: T) -> Bool +postfix operator -- { +} prefix func !(a: Bool) -> Bool -func !=(lhs: _OptionalNilComparisonType, rhs: T?) -> Bool -func !=(lhs: T?, rhs: _OptionalNilComparisonType) -> Bool +/// Return the result of inverting `a`\ 's logic value +prefix func !(a: T) -> Bool -func !=(lhs: T?, rhs: T?) -> Bool +func !=(lhs: Int, rhs: Int) -> Bool +func !=(lhs: T?, rhs: T?) -> Bool -/// Returns true if the arrays do not contain the same elements. -func !=(lhs: ContiguousArray, rhs: ContiguousArray) -> Bool +func !=(lhs: T?, rhs: _OptionalNilComparisonType) -> Bool func !=(lhs: UInt, rhs: UInt) -> Bool @@ -264,9 +262,13 @@ func !=(lhs: Int8, rhs: Int8) -> Bool func !=(lhs: UInt8, rhs: UInt8) -> Bool +func !=(lhs: _OptionalNilComparisonType, rhs: T?) -> Bool + func !=(lhs: T, rhs: T) -> Bool -func !=(lhs: Int, rhs: Int) -> Bool + +/// Returns true if the arrays do not contain the same elements. +func !=(lhs: ContiguousArray, rhs: ContiguousArray) -> Bool /// Returns true if the arrays do not contain the same elements. @@ -282,76 +284,95 @@ func !==(lhs: AnyObject?, rhs: AnyObject?) -> Bool func %(lhs: UInt32, rhs: UInt32) -> UInt32 -func %(lhs: Int32, rhs: Int32) -> Int32 +func %(lhs: Int16, rhs: Int16) -> Int16 -func %(lhs: UInt64, rhs: UInt64) -> UInt64 +func %(lhs: UInt16, rhs: UInt16) -> UInt16 -func %(lhs: Int64, rhs: Int64) -> Int64 +func %(lhs: Int8, rhs: Int8) -> Int8 -func %(lhs: Int16, rhs: Int16) -> Int16 +func %(lhs: UInt8, rhs: UInt8) -> UInt8 -func %(lhs: Int, rhs: Int) -> Int -func %(lhs: Float, rhs: Float) -> Float +/// Divide `lhs` and `rhs`, returning the remainder and trapping in case of +/// arithmetic overflow (except in -Ounchecked builds). +func %(lhs: T, rhs: T) -> T + +func %(lhs: Float80, rhs: Float80) -> Float80 func %(lhs: Double, rhs: Double) -> Double -func %(lhs: Float80, rhs: Float80) -> Float80 +func %(lhs: Float, rhs: Float) -> Float -func %(lhs: T, rhs: T) -> T +func %(lhs: Int, rhs: Int) -> Int -func %(lhs: UInt16, rhs: UInt16) -> UInt16 +func %(lhs: Int32, rhs: Int32) -> Int32 -func %(lhs: Int8, rhs: Int8) -> Int8 +func %(lhs: UInt64, rhs: UInt64) -> UInt64 -func %(lhs: UInt8, rhs: UInt8) -> UInt8 +func %(lhs: Int64, rhs: Int64) -> Int64 func %(lhs: UInt, rhs: UInt) -> UInt -func %=(inout lhs: T, rhs: T) +func %=(inout lhs: Float, rhs: Float) + +func %=(inout lhs: Double, rhs: Double) func %=(inout lhs: Float80, rhs: Float80) -func %=(inout lhs: Double, rhs: Double) -func %=(inout lhs: Float, rhs: Float) +/// remainder `lhs` and `rhs` and store the result in `lhs`, trapping in +/// case of arithmetic overflow (except in -Ounchecked builds). +func %=(inout lhs: T, rhs: T) -func &(lhs: Int64, rhs: Int64) -> Int64 +func &(lhs: UInt32, rhs: UInt32) -> UInt32 + +func &(lhs: UInt16, rhs: UInt16) -> UInt16 + +func &(lhs: Int16, rhs: Int16) -> Int16 + +func &(lhs: Int32, rhs: Int32) -> Int32 func &(lhs: UInt64, rhs: UInt64) -> UInt64 +func &(lhs: Int64, rhs: Int64) -> Int64 + func &(lhs: UInt, rhs: UInt) -> UInt func &(lhs: Int, rhs: Int) -> Int -func &(a: T, b: T) -> T - func &(lhs: Bool, rhs: Bool) -> Bool -func &(lhs: Int32, rhs: Int32) -> Int32 +func &(a: T, b: T) -> T func &(lhs: UInt8, rhs: UInt8) -> UInt8 func &(lhs: Int8, rhs: Int8) -> Int8 -func &(lhs: UInt16, rhs: UInt16) -> UInt16 - -func &(lhs: Int16, rhs: Int16) -> Int16 - -func &(lhs: UInt32, rhs: UInt32) -> UInt32 +/// remainder `lhs` and `rhs`, silently discarding any overflow. func &%(lhs: T, rhs: T) -> T func &&(lhs: T, rhs: @autoclosure () -> Bool) -> Bool -func &&(lhs: T, rhs: @autoclosure () -> U) -> Bool +/// If `lhs` is `false`, return it. Otherwise, evaluate `rhs` and +/// return its `boolValue`. +@inline(__always) func &&(lhs: T, rhs: @autoclosure () -> U) -> Bool + + +/// multiply `lhs` and `rhs`, silently discarding any overflow. func &*(lhs: T, rhs: T) -> T + +/// add `lhs` and `rhs`, silently discarding any overflow. func &+(lhs: T, rhs: T) -> T + +/// subtract `lhs` and `rhs`, silently discarding any overflow. func &-(lhs: T, rhs: T) -> T + +/// divide `lhs` and `rhs`, silently discarding any overflow. func &/(lhs: T, rhs: T) -> T func &=(inout lhs: Bool, rhs: Bool) @@ -370,25 +391,13 @@ func &=(inout lhs: Int32, rhs: Int32) func &=(inout lhs: UInt64, rhs: UInt64) -func &=(inout lhs: Int64, rhs: Int64) - func &=(inout lhs: T, rhs: T) func &=(inout lhs: Int, rhs: Int) func &=(inout lhs: UInt, rhs: UInt) -func *(lhs: UInt16, rhs: UInt16) -> UInt16 - -func *(lhs: Int8, rhs: Int8) -> Int8 - -func *(lhs: UInt8, rhs: UInt8) -> UInt8 - -func *(lhs: T, rhs: T) -> T - -func *(lhs: Double, rhs: Double) -> Double - -func *(lhs: Int16, rhs: Int16) -> Int16 +func &=(inout lhs: Int64, rhs: Int64) func *(lhs: UInt32, rhs: UInt32) -> UInt32 @@ -404,8 +413,23 @@ func *(lhs: Int, rhs: Int) -> Int func *(lhs: Float, rhs: Float) -> Float +func *(lhs: Double, rhs: Double) -> Double + func *(lhs: Float80, rhs: Float80) -> Float80 + +/// Multiply `lhs` and `rhs`, returning a result and trapping in case of +/// arithmetic overflow (except in -Ounchecked builds). +func *(lhs: T, rhs: T) -> T + +func *(lhs: Int16, rhs: Int16) -> Int16 + +func *(lhs: UInt16, rhs: UInt16) -> UInt16 + +func *(lhs: Int8, rhs: Int8) -> Int8 + +func *(lhs: UInt8, rhs: UInt8) -> UInt8 + func *=(inout lhs: UInt8, rhs: UInt8) func *=(inout lhs: Int8, rhs: Int8) @@ -414,6 +438,8 @@ func *=(inout lhs: UInt16, rhs: UInt16) func *=(inout lhs: Int16, rhs: Int16) +func *=(inout lhs: UInt32, rhs: UInt32) + func *=(inout lhs: Int32, rhs: Int32) func *=(inout lhs: UInt64, rhs: UInt64) @@ -428,296 +454,333 @@ func *=(inout lhs: Float, rhs: Float) func *=(inout lhs: Double, rhs: Double) -func *=(inout lhs: Float80, rhs: Float80) +/// multiply `lhs` and `rhs` and store the result in `lhs`, trapping in +/// case of arithmetic overflow (except in -Ounchecked builds). func *=(inout lhs: T, rhs: T) -func *=(inout lhs: UInt32, rhs: UInt32) +func *=(inout lhs: Float80, rhs: Float80) -func +(lhs: Int, rhs: UnsafeMutablePointer) -> UnsafeMutablePointer +prefix func +(x: Double) -> Double -func +(lhs: UnsafeMutablePointer, rhs: Int) -> UnsafeMutablePointer +func +(lhs: Float, rhs: Float) -> Float -func +(lhs: String, rhs: String) -> String +func +(lhs: Int, rhs: UnsafePointer) -> UnsafePointer + +prefix func +(x: Float) -> Float func +(lhs: UnsafePointer, rhs: Int) -> UnsafePointer -func +(lhs: T.Stride, rhs: T) -> T +func +(lhs: Int, rhs: Int) -> Int -func +(lhs: T, rhs: T.Stride) -> T +func +(lhs: UInt, rhs: UInt) -> UInt -func +(lhs: Int, rhs: UnsafePointer) -> UnsafePointer +func +(lhs: Int64, rhs: Int64) -> Int64 -prefix func +(x: T) -> T +func +(lhs: UInt64, rhs: UInt64) -> UInt64 -func +(lhs: UInt8, rhs: UInt8) -> UInt8 +func +(lhs: Int, rhs: UnsafeMutablePointer) -> UnsafeMutablePointer -func +(lhs: EC1, rhs: EC2) -> EC1 +func +(lhs: UnsafeMutablePointer, rhs: Int) -> UnsafeMutablePointer -func +(lhs: C, rhs: S) -> C +func +(lhs: Int32, rhs: Int32) -> Int32 -func +(lhs: Int8, rhs: Int8) -> Int8 +func +(lhs: UInt32, rhs: UInt32) -> UInt32 -func +(lhs: UInt16, rhs: UInt16) -> UInt16 +func +(lhs: Int16, rhs: Int16) -> Int16 -func +(lhs: S, rhs: C) -> C +func +(lhs: UInt16, rhs: UInt16) -> UInt16 -func +(lhs: C, rhs: S) -> C +func +(lhs: Int8, rhs: Int8) -> Int8 -func +(lhs: Int16, rhs: Int16) -> Int16 +func +(lhs: UInt8, rhs: UInt8) -> UInt8 -func +(lhs: T, rhs: T) -> T +func +(lhs: Double, rhs: Double) -> Double -func +(lhs: Float80, rhs: Float80) -> Float80 +func +(lhs: String, rhs: String) -> String prefix func +(x: Float80) -> Float80 -func +(lhs: Double, rhs: Double) -> Double +func +(lhs: Float80, rhs: Float80) -> Float80 -func +(lhs: UInt32, rhs: UInt32) -> UInt32 -prefix func +(x: Double) -> Double +/// Add `lhs` and `rhs`, returning a result and trapping in case of +/// arithmetic overflow (except in -Ounchecked builds). +func +(lhs: T, rhs: T) -> T -func +(lhs: Float, rhs: Float) -> Float +prefix func +(x: T) -> T -prefix func +(x: Float) -> Float +func +(lhs: C, rhs: S) -> C -func +(lhs: Int, rhs: Int) -> Int +func +(lhs: S, rhs: C) -> C -func +(lhs: UInt, rhs: UInt) -> UInt +func +(lhs: T.Stride, rhs: T) -> T -func +(lhs: Int64, rhs: Int64) -> Int64 +func +(lhs: C, rhs: S) -> C -func +(lhs: Int32, rhs: Int32) -> Int32 +func +(lhs: EC1, rhs: EC2) -> EC1 -func +(lhs: UInt64, rhs: UInt64) -> UInt64 +func +(lhs: T, rhs: T.Stride) -> T prefix func ++(inout x: Int8) -> Int8 -prefix func ++(inout x: UInt8) -> UInt8 +prefix func ++(inout x: Int16) -> Int16 -postfix func ++(inout x: UInt8) -> UInt8 +postfix func ++(inout x: T) -> T -postfix func ++(inout x: Int8) -> Int8 +prefix func ++(inout x: T) -> T -prefix func ++(inout x: UInt16) -> UInt16 +postfix func ++(inout lhs: Float80) -> Float80 -postfix func ++(inout x: UInt16) -> UInt16 +prefix func ++(inout rhs: Float80) -> Float80 -prefix func ++(inout x: Int16) -> Int16 +postfix func ++(inout lhs: Double) -> Double -postfix func ++(inout x: Int16) -> Int16 +prefix func ++(inout rhs: Double) -> Double -prefix func ++(inout x: UInt32) -> UInt32 +postfix func ++(inout lhs: Float) -> Float -postfix func ++(inout x: UInt32) -> UInt32 +prefix func ++(inout rhs: Float) -> Float -prefix func ++(inout x: Int32) -> Int32 +postfix func ++(inout x: Int) -> Int -postfix func ++(inout x: Int32) -> Int32 +prefix func ++(inout x: Int) -> Int -prefix func ++(inout x: UInt64) -> UInt64 +postfix func ++(inout x: UInt) -> UInt -postfix func ++(inout x: UInt64) -> UInt64 +prefix func ++(inout x: UInt) -> UInt + +postfix func ++(inout x: Int64) -> Int64 prefix func ++(inout x: Int64) -> Int64 -postfix func ++(inout x: Int64) -> Int64 +postfix func ++(inout x: UInt64) -> UInt64 -prefix func ++(inout x: UInt) -> UInt +prefix func ++(inout x: UInt64) -> UInt64 -postfix func ++(inout x: UInt) -> UInt +postfix func ++(inout x: Int32) -> Int32 -prefix func ++(inout x: Int) -> Int +prefix func ++(inout x: Int32) -> Int32 -postfix func ++(inout x: Int) -> Int +postfix func ++(inout x: UInt32) -> UInt32 -prefix func ++(inout rhs: Float) -> Float +prefix func ++(inout x: UInt32) -> UInt32 -postfix func ++(inout lhs: Float) -> Float +postfix func ++(inout x: Int16) -> Int16 -prefix func ++(inout rhs: Double) -> Double +postfix func ++(inout x: UInt16) -> UInt16 -postfix func ++(inout lhs: Double) -> Double +prefix func ++(inout x: UInt16) -> UInt16 -prefix func ++(inout rhs: Float80) -> Float80 +postfix func ++(inout x: Int8) -> Int8 -postfix func ++(inout lhs: Float80) -> Float80 +prefix func ++(inout x: UInt8) -> UInt8 -prefix func ++(inout x: T) -> T +postfix func ++(inout x: UInt8) -> UInt8 -postfix func ++(inout x: T) -> T -func +=(inout lhs: Int64, rhs: Int64) +/// Extend `lhs` with the elements of `rhs` +func +=(inout lhs: ContiguousArray, rhs: S) -func +=(inout lhs: UnsafePointer, rhs: Int) + +/// Append rhs to lhs +func +=(inout lhs: _ContiguousArrayBuffer, rhs: T) + + +/// Extend `lhs` with the elements of `rhs` +func +=(inout lhs: ContiguousArray, rhs: C) func +=(inout lhs: UnsafeMutablePointer, rhs: Int) func +=(inout lhs: String, rhs: String) -func +=(inout lhs: ContiguousArray, rhs: S) - func +=(inout lhs: T, rhs: T.Stride) -func +=(inout lhs: ContiguousArray, rhs: C) +/// add `lhs` and `rhs` and store the result in `lhs`, trapping in +/// case of arithmetic overflow (except in -Ounchecked builds). func +=(inout lhs: T, rhs: T) -func +=(inout lhs: Slice, rhs: S) - -func +=(inout lhs: Slice, rhs: C) - -func +=(inout lhs: [T], rhs: S) +func +=(inout lhs: Float80, rhs: Float80) -func +=(inout lhs: [T], rhs: C) +func +=(inout lhs: Double, rhs: Double) +func +=(inout lhs: Float, rhs: Float) -/// Append the elements of rhs to lhs -func +=(inout lhs: _ContiguousArrayBuffer, rhs: C) +func +=(inout lhs: Int, rhs: Int) +func +=(inout lhs: UInt, rhs: UInt) -/// Append rhs to lhs -func +=(inout lhs: _ContiguousArrayBuffer, rhs: T) +func +=(inout lhs: Int64, rhs: Int64) -func +=(inout lhs: UInt8, rhs: UInt8) -func +=(inout lhs: Int8, rhs: Int8) +/// Extend `lhs` with the elements of `rhs` +func +=(inout lhs: Slice, rhs: S) -func +=(inout lhs: UInt16, rhs: UInt16) -func +=(inout lhs: Int16, rhs: Int16) +/// Extend `lhs` with the elements of `rhs` +func +=(inout lhs: Slice, rhs: C) -func +=(inout lhs: Float80, rhs: Float80) +func +=(inout lhs: UInt64, rhs: UInt64) -func +=(inout lhs: Double, rhs: Double) +func +=(inout lhs: Int32, rhs: Int32) func +=(inout lhs: UInt32, rhs: UInt32) -func +=(inout lhs: Int32, rhs: Int32) +func +=(inout lhs: Int16, rhs: Int16) -func +=(inout lhs: UInt64, rhs: UInt64) +func +=(inout lhs: UInt16, rhs: UInt16) -func +=(inout lhs: UInt, rhs: UInt) -func +=(inout lhs: Int, rhs: Int) +/// Extend `lhs` with the elements of `rhs` +func +=(inout lhs: [T], rhs: S) -func +=(inout lhs: Float, rhs: Float) -prefix func -(x: Float) -> Float +/// Extend `lhs` with the elements of `rhs` +func +=(inout lhs: [T], rhs: C) -func -(lhs: UInt8, rhs: UInt8) -> UInt8 -func -(lhs: Int8, rhs: Int8) -> Int8 +/// Append the elements of rhs to lhs +func +=(inout lhs: _ContiguousArrayBuffer, rhs: C) -func -(lhs: UInt16, rhs: UInt16) -> UInt16 +func +=(inout lhs: Int8, rhs: Int8) -func -(lhs: Int16, rhs: Int16) -> Int16 +func +=(inout lhs: UInt8, rhs: UInt8) -func -(lhs: UInt32, rhs: UInt32) -> UInt32 +func +=(inout lhs: UnsafePointer, rhs: Int) func -(lhs: Int32, rhs: Int32) -> Int32 func -(lhs: UInt64, rhs: UInt64) -> UInt64 +func -(lhs: UInt32, rhs: UInt32) -> UInt32 + func -(lhs: Int64, rhs: Int64) -> Int64 func -(lhs: UInt, rhs: UInt) -> UInt func -(lhs: Int, rhs: Int) -> Int -func -(lhs: Float, rhs: Float) -> Float +func -(lhs: Int16, rhs: Int16) -> Int16 -prefix func -(x: Double) -> Double +func -(lhs: UInt16, rhs: UInt16) -> UInt16 -func -(lhs: Double, rhs: Double) -> Double +func -(lhs: Int8, rhs: Int8) -> Int8 -prefix func -(x: Float80) -> Float80 +func -(lhs: UInt8, rhs: UInt8) -> UInt8 -func -(lhs: Float80, rhs: Float80) -> Float80 +func -(lhs: UnsafePointer, rhs: UnsafePointer) -> Int -func -(lhs: T, rhs: T) -> T +func -(lhs: UnsafePointer, rhs: Int) -> UnsafePointer -prefix func -(x: T) -> T +func -(lhs: UnsafeMutablePointer, rhs: UnsafeMutablePointer) -> Int -func -(lhs: T, rhs: T.Stride) -> T +func -(lhs: UnsafeMutablePointer, rhs: Int) -> UnsafeMutablePointer func -(lhs: T, rhs: T) -> T.Stride -func -(lhs: UnsafeMutablePointer, rhs: Int) -> UnsafeMutablePointer +func -(lhs: T, rhs: T.Stride) -> T -func -(lhs: UnsafeMutablePointer, rhs: UnsafeMutablePointer) -> Int +prefix func -(x: T) -> T -func -(lhs: UnsafePointer, rhs: Int) -> UnsafePointer -func -(lhs: UnsafePointer, rhs: UnsafePointer) -> Int +/// Subtract `lhs` and `rhs`, returning a result and trapping in case of +/// arithmetic overflow (except in -Ounchecked builds). +func -(lhs: T, rhs: T) -> T -postfix func --(inout x: Int32) -> Int32 +func -(lhs: Float80, rhs: Float80) -> Float80 -postfix func --(inout lhs: Float) -> Float +prefix func -(x: Float80) -> Float80 -prefix func --(inout rhs: Double) -> Double +func -(lhs: Double, rhs: Double) -> Double -prefix func --(inout rhs: Float) -> Float +prefix func -(x: Double) -> Double -prefix func --(inout x: UInt16) -> UInt16 +func -(lhs: Float, rhs: Float) -> Float -postfix func --(inout x: Int) -> Int +prefix func -(x: Float) -> Float -postfix func --(inout lhs: Double) -> Double +postfix func --(inout x: UInt) -> UInt -prefix func --(inout rhs: Float80) -> Float80 +prefix func --(inout rhs: Float) -> Float postfix func --(inout lhs: Float80) -> Float80 -prefix func --(inout x: Int16) -> Int16 - -prefix func --(inout x: Int) -> Int - -postfix func --(inout x: UInt) -> UInt - -prefix func --(inout x: Int8) -> Int8 - prefix func --(inout x: UInt) -> UInt -prefix func --(inout x: T) -> T +postfix func --(inout lhs: Float) -> Float postfix func --(inout x: Int64) -> Int64 -postfix func --(inout x: T) -> T - prefix func --(inout x: Int64) -> Int64 +prefix func --(inout rhs: Double) -> Double + postfix func --(inout x: UInt64) -> UInt64 -postfix func --(inout x: UInt16) -> UInt16 +postfix func --(inout lhs: Double) -> Double prefix func --(inout x: UInt8) -> UInt8 +prefix func --(inout rhs: Float80) -> Float80 + +prefix func --(inout x: UInt64) -> UInt64 + postfix func --(inout x: UInt8) -> UInt8 -postfix func --(inout x: Int8) -> Int8 +prefix func --(inout x: Int8) -> Int8 -postfix func --(inout x: Int16) -> Int16 +prefix func --(inout x: T) -> T + +postfix func --(inout x: Int) -> Int + +postfix func --(inout x: Int32) -> Int32 + +prefix func --(inout x: Int32) -> Int32 + +postfix func --(inout x: T) -> T prefix func --(inout x: UInt32) -> UInt32 postfix func --(inout x: UInt32) -> UInt32 -prefix func --(inout x: Int32) -> Int32 +postfix func --(inout x: Int8) -> Int8 -prefix func --(inout x: UInt64) -> UInt64 +prefix func --(inout x: UInt16) -> UInt16 -func -=(inout lhs: Int16, rhs: Int16) +postfix func --(inout x: UInt16) -> UInt16 -func -=(inout lhs: UInt32, rhs: UInt32) +prefix func --(inout x: Int16) -> Int16 -func -=(inout lhs: Int32, rhs: Int32) +postfix func --(inout x: Int16) -> Int16 + +prefix func --(inout x: Int) -> Int func -=(inout lhs: UInt64, rhs: UInt64) +func -=(inout lhs: Int64, rhs: Int64) + +func -=(inout lhs: UInt8, rhs: UInt8) + +func -=(inout lhs: Int8, rhs: Int8) + +func -=(inout lhs: UInt16, rhs: UInt16) + +func -=(inout lhs: UnsafePointer, rhs: Int) + +func -=(inout lhs: Int32, rhs: Int32) + +func -=(inout lhs: UnsafeMutablePointer, rhs: Int) + +func -=(inout lhs: UInt32, rhs: UInt32) + func -=(inout lhs: T, rhs: T.Stride) +func -=(inout lhs: Int16, rhs: Int16) + + +/// subtract `lhs` and `rhs` and store the result in `lhs`, trapping in +/// case of arithmetic overflow (except in -Ounchecked builds). func -=(inout lhs: T, rhs: T) func -=(inout lhs: Float80, rhs: Float80) @@ -726,21 +789,13 @@ func -=(inout lhs: Double, rhs: Double) func -=(inout lhs: Float, rhs: Float) -func -=(inout lhs: Int, rhs: Int) - func -=(inout lhs: UInt, rhs: UInt) -func -=(inout lhs: UInt16, rhs: UInt16) - -func -=(inout lhs: Int64, rhs: Int64) - -func -=(inout lhs: UnsafeMutablePointer, rhs: Int) - -func -=(inout lhs: UnsafePointer, rhs: Int) +func -=(inout lhs: Int, rhs: Int) -func -=(inout lhs: Int8, rhs: Int8) -func -=(inout lhs: UInt8, rhs: UInt8) +/// Returns a closed interval from `start` through `end` +func ...(start: T, end: T) -> ClosedInterval /// Forms a closed range that contains both `start` and `end`. @@ -748,16 +803,13 @@ func -=(inout lhs: UInt8, rhs: UInt8) func ...(start: Pos, end: Pos) -> Range -/// Returns a closed interval from `start` through `end` -func ...(start: T, end: T) -> ClosedInterval - - /// Forms a closed range that contains both `minimum` and `maximum`. func ...(minimum: Pos, maximum: Pos) -> Range -/// Returns a half-open interval from `start` to `end` -func ..<(start: T, end: T) -> HalfOpenInterval +/// Forms a half-open range that contains `start`, but not +/// `end`. Requires: `start <= end` +func ..<(start: Pos, end: Pos) -> Range /// Forms a half-open range that contains `minimum`, but not @@ -765,49 +817,76 @@ func ..<(start: T, end: T) -> HalfOpenInterval func ..<(minimum: Pos, maximum: Pos) -> Range -/// Forms a half-open range that contains `start`, but not -/// `end`. Requires: `start <= end` -func ..<(start: Pos, end: Pos) -> Range +/// Returns a half-open interval from `start` to `end` +func ..<(start: T, end: T) -> HalfOpenInterval -func /(lhs: Int16, rhs: Int16) -> Int16 +func /(lhs: Float, rhs: Float) -> Float -func /(lhs: UInt32, rhs: UInt32) -> UInt32 +func /(lhs: Double, rhs: Double) -> Double -func /(lhs: Int32, rhs: Int32) -> Int32 +func /(lhs: Float80, rhs: Float80) -> Float80 -func /(lhs: UInt64, rhs: UInt64) -> UInt64 + +/// Divide `lhs` and `rhs`, returning a result and trapping in case of +/// arithmetic overflow (except in -Ounchecked builds). +func /(lhs: T, rhs: T) -> T + +func /(lhs: Int, rhs: Int) -> Int func /(lhs: Int64, rhs: Int64) -> Int64 +func /(lhs: UInt64, rhs: UInt64) -> UInt64 + +func /(lhs: Int32, rhs: Int32) -> Int32 + +func /(lhs: UInt32, rhs: UInt32) -> UInt32 + +func /(lhs: Int16, rhs: Int16) -> Int16 + +func /(lhs: UInt16, rhs: UInt16) -> UInt16 + +func /(lhs: Int8, rhs: Int8) -> Int8 + +func /(lhs: UInt8, rhs: UInt8) -> UInt8 + func /(lhs: UInt, rhs: UInt) -> UInt -func /(lhs: Int, rhs: Int) -> Int +func /=(inout lhs: Float, rhs: Float) -func /(lhs: Float, rhs: Float) -> Float +func /=(inout lhs: Double, rhs: Double) -func /(lhs: Double, rhs: Double) -> Double +func /=(inout lhs: Float80, rhs: Float80) -func /(lhs: Float80, rhs: Float80) -> Float80 -func /(lhs: T, rhs: T) -> T +/// divide `lhs` and `rhs` and store the result in `lhs`, trapping in +/// case of arithmetic overflow (except in -Ounchecked builds). +func /=(inout lhs: T, rhs: T) + +func <(lhs: UnicodeScalar, rhs: UnicodeScalar) -> Bool + +func <(lhs: UInt, rhs: UInt) -> Bool + +func <(lhs: String.Index, rhs: String.Index) -> Bool + +func <(lhs: String, rhs: String) -> Bool -func /(lhs: Int8, rhs: Int8) -> Int8 -func /(lhs: UInt8, rhs: UInt8) -> UInt8 +/// Compare two Strideables +func <(x: T, y: T) -> Bool -func /(lhs: UInt16, rhs: UInt16) -> UInt16 +func <(lhs: T?, rhs: T?) -> Bool -func /=(inout lhs: Float, rhs: Float) +func <(lhs: Float80, rhs: Float80) -> Bool -func /=(inout lhs: Double, rhs: Double) +func <(lhs: Double, rhs: Double) -> Bool -func /=(inout lhs: Float80, rhs: Float80) +func <(lhs: Float, rhs: Float) -> Bool -func /=(inout lhs: T, rhs: T) +func <(lhs: Int, rhs: Int) -> Bool -func <(lhs: UInt, rhs: UInt) -> Bool +func <(lhs: String.UnicodeScalarView.Index, rhs: String.UnicodeScalarView.Index) -> Bool -func <(lhs: String.Index, rhs: String.Index) -> Bool +func <(lhs: Int64, rhs: Int64) -> Bool func <(lhs: UInt64, rhs: UInt64) -> Bool @@ -827,33 +906,13 @@ func <(lhs: DictionaryIndex, rhs: DictionaryI func <(lhs: Character, rhs: Character) -> Bool -func <(lhs: Int64, rhs: Int64) -> Bool - func <(lhs: Bit, rhs: Bit) -> Bool -func <(lhs: UnsafePointer, rhs: UnsafePointer) -> Bool - func <(lhs: UnsafeMutablePointer, rhs: UnsafeMutablePointer) -> Bool -func <(lhs: UnicodeScalar, rhs: UnicodeScalar) -> Bool - -func <(lhs: String.UnicodeScalarView.Index, rhs: String.UnicodeScalarView.Index) -> Bool - -func <(lhs: Int, rhs: Int) -> Bool - -func <(lhs: String, rhs: String) -> Bool - - -/// Compare two Strideables -func <(x: T, y: T) -> Bool - -func <(lhs: T?, rhs: T?) -> Bool - -func <(lhs: Float80, rhs: Float80) -> Bool - -func <(lhs: Double, rhs: Double) -> Bool +func <(lhs: UnsafePointer, rhs: UnsafePointer) -> Bool -func <(lhs: Float, rhs: Float) -> Bool +func <<(lhs: UInt8, rhs: UInt8) -> UInt8 func <<(lhs: Int, rhs: Int) -> Int @@ -861,39 +920,39 @@ func <<(lhs: UInt, rhs: UInt) -> UInt func <<(lhs: Int64, rhs: Int64) -> Int64 +func <<(lhs: Int8, rhs: Int8) -> Int8 + +func <<(lhs: UInt16, rhs: UInt16) -> UInt16 + +func <<(lhs: Int16, rhs: Int16) -> Int16 + func <<(lhs: UInt64, rhs: UInt64) -> UInt64 func <<(lhs: Int32, rhs: Int32) -> Int32 func <<(lhs: UInt32, rhs: UInt32) -> UInt32 -func <<(lhs: Int16, rhs: Int16) -> Int16 - -func <<(lhs: Int8, rhs: Int8) -> Int8 - -func <<(lhs: UInt16, rhs: UInt16) -> UInt16 +func <<=(inout lhs: UInt8, rhs: UInt8) -func <<(lhs: UInt8, rhs: UInt8) -> UInt8 +func <<=(inout lhs: Int8, rhs: Int8) -func <<=(inout lhs: UInt, rhs: UInt) +func <<=(inout lhs: UInt16, rhs: UInt16) -func <<=(inout lhs: Int, rhs: Int) +func <<=(inout lhs: Int16, rhs: Int16) -func <<=(inout lhs: UInt64, rhs: UInt64) +func <<=(inout lhs: UInt32, rhs: UInt32) func <<=(inout lhs: Int32, rhs: Int32) -func <<=(inout lhs: UInt32, rhs: UInt32) +func <<=(inout lhs: UInt64, rhs: UInt64) func <<=(inout lhs: Int64, rhs: Int64) -func <<=(inout lhs: Int16, rhs: Int16) - -func <<=(inout lhs: UInt16, rhs: UInt16) +func <<=(inout lhs: UInt, rhs: UInt) -func <<=(inout lhs: Int8, rhs: Int8) +func <<=(inout lhs: Int, rhs: Int) -func <<=(inout lhs: UInt8, rhs: UInt8) +func <=(lhs: UInt32, rhs: UInt32) -> Bool func <=(lhs: T, rhs: T) -> Bool @@ -909,150 +968,148 @@ func <=(lhs: UInt64, rhs: UInt64) -> Bool func <=(lhs: Int32, rhs: Int32) -> Bool -func <=(lhs: UInt32, rhs: UInt32) -> Bool - -func <=(lhs: UInt8, rhs: UInt8) -> Bool - func <=(lhs: Int16, rhs: Int16) -> Bool -func <=(lhs: Int8, rhs: Int8) -> Bool - func <=(lhs: UInt16, rhs: UInt16) -> Bool -func ==(lhs: UnsafePointer, rhs: UnsafePointer) -> Bool +func <=(lhs: Int8, rhs: Int8) -> Bool -func ==(x: T, y: T) -> Bool +func <=(lhs: UInt8, rhs: UInt8) -> Bool func ==(x: ObjectIdentifier, y: ObjectIdentifier) -> Bool -func ==(lhs: String.Index, rhs: String.Index) -> Bool +func ==(lhs: UnsafePointer, rhs: UnsafePointer) -> Bool -func ==(lhs: String.UTF8View.Index, rhs: String.UTF8View.Index) -> Bool +func ==(lhs: UInt8, rhs: UInt8) -> Bool +func ==(lhs: Bit, rhs: Bit) -> Bool -/// Two `HalfOpenInterval`\ s are equal if their `start` and `end` are -/// equal -func ==(lhs: HalfOpenInterval, rhs: HalfOpenInterval) -> Bool +func ==(lhs: Int8, rhs: Int8) -> Bool -func ==(lhs: String.UnicodeScalarView.Index, rhs: String.UnicodeScalarView.Index) -> Bool +func ==(lhs: UInt16, rhs: UInt16) -> Bool +func ==(lhs: FilterCollectionViewIndex, rhs: FilterCollectionViewIndex) -> Bool -/// Two `ClosedInterval`\ s are equal if their `start` and `end` are -/// equal -func ==(lhs: ClosedInterval, rhs: ClosedInterval) -> Bool +func ==(lhs: Int16, rhs: Int16) -> Bool -func ==(lhs: T?, rhs: T?) -> Bool +func ==(lhs: [Key : Value], rhs: [Key : Value]) -> Bool -func ==(lhs: T?, rhs: _OptionalNilComparisonType) -> Bool +func ==(lhs: DictionaryIndex, rhs: DictionaryIndex) -> Bool -func ==(lhs: UInt8, rhs: UInt8) -> Bool +func ==(lhs: UInt32, rhs: UInt32) -> Bool -func ==(lhs: Int8, rhs: Int8) -> Bool +func ==(a: T, b: T) -> Bool -func ==(lhs: Bit, rhs: Bit) -> Bool +func ==(lhs: Character, rhs: Character) -> Bool -func ==(lhs: UInt16, rhs: UInt16) -> Bool +func ==(lhs: UInt64, rhs: UInt64) -> Bool -func ==(lhs: HeapBuffer, rhs: HeapBuffer) -> Bool +func ==(lhs: Int32, rhs: Int32) -> Bool -func ==(lhs: FloatingPointClassification, rhs: FloatingPointClassification) -> Bool +func ==(lhs: Int64, rhs: Int64) -> Bool -func ==(lhs: Float80, rhs: Float80) -> Bool +func ==(lhs: CFunctionPointer, rhs: CFunctionPointer) -> Bool +func ==(lhs: UInt, rhs: UInt) -> Bool -/// Returns true if these arrays contain the same elements. -func ==(lhs: ContiguousArray, rhs: ContiguousArray) -> Bool +func ==(lhs: COpaquePointer, rhs: COpaquePointer) -> Bool -func ==(lhs: Double, rhs: Double) -> Bool +func ==(lhs: ReverseBidirectionalIndex, rhs: ReverseBidirectionalIndex) -> Bool -func ==(lhs: Float, rhs: Float) -> Bool +func ==(lhs: AutoreleasingUnsafeMutablePointer, rhs: AutoreleasingUnsafeMutablePointer) -> Bool -func ==(lhs: UnsafeMutablePointer, rhs: UnsafeMutablePointer) -> Bool +func ==(lhs: Bool, rhs: Bool) -> Bool -func ==(lhs: UnicodeScalar, rhs: UnicodeScalar) -> Bool + +/// Returns true if these arrays contain the same elements. +func ==(lhs: [T], rhs: [T]) -> Bool /// Returns true if these arrays contain the same elements. func ==(lhs: Slice, rhs: Slice) -> Bool -func ==(lhs: ReverseRandomAccessIndex, rhs: ReverseRandomAccessIndex) -> Bool + +/// Returns true if these arrays contain the same elements. +func ==(lhs: ContiguousArray, rhs: ContiguousArray) -> Bool func ==(lhs: Int, rhs: Int) -> Bool +func ==(lhs: ReverseRandomAccessIndex, rhs: ReverseRandomAccessIndex) -> Bool -/// Returns true if these arrays contain the same elements. -func ==(lhs: [T], rhs: [T]) -> Bool +func ==(x: T, y: T) -> Bool -func ==(lhs: UInt, rhs: UInt) -> Bool +func ==(lhs: String.UTF8View.Index, rhs: String.UTF8View.Index) -> Bool -func ==(lhs: Bool, rhs: Bool) -> Bool +func ==(lhs: UnsafeMutablePointer, rhs: UnsafeMutablePointer) -> Bool -func ==(lhs: AutoreleasingUnsafeMutablePointer, rhs: AutoreleasingUnsafeMutablePointer) -> Bool +func ==(lhs: String, rhs: String) -> Bool -func ==(lhs: Int64, rhs: Int64) -> Bool +func ==(lhs: UnicodeScalar, rhs: UnicodeScalar) -> Bool -func ==(lhs: UInt64, rhs: UInt64) -> Bool +func ==(lhs: Float, rhs: Float) -> Bool -func ==(lhs: Int32, rhs: Int32) -> Bool +func ==(lhs: String.Index, rhs: String.Index) -> Bool -func ==(lhs: UInt32, rhs: UInt32) -> Bool +func ==(lhs: Double, rhs: Double) -> Bool -func ==(lhs: COpaquePointer, rhs: COpaquePointer) -> Bool +func ==(lhs: Range, rhs: Range) -> Bool -func ==(lhs: Int16, rhs: Int16) -> Bool +func ==(lhs: String.UnicodeScalarView.Index, rhs: String.UnicodeScalarView.Index) -> Bool -func ==(lhs: ReverseBidirectionalIndex, rhs: ReverseBidirectionalIndex) -> Bool +func ==(lhs: Float80, rhs: Float80) -> Bool -func ==(lhs: CFunctionPointer, rhs: CFunctionPointer) -> Bool +func ==(lhs: FloatingPointClassification, rhs: FloatingPointClassification) -> Bool -func ==(lhs: Character, rhs: Character) -> Bool +func ==(lhs: HeapBuffer, rhs: HeapBuffer) -> Bool -func ==(a: T, b: T) -> Bool -func ==(lhs: String, rhs: String) -> Bool +/// Two `HalfOpenInterval`\ s are equal if their `start` and `end` are +/// equal +func ==(lhs: HalfOpenInterval, rhs: HalfOpenInterval) -> Bool -func ==(lhs: DictionaryIndex, rhs: DictionaryIndex) -> Bool -func ==(lhs: [Key : Value], rhs: [Key : Value]) -> Bool +/// Two `ClosedInterval`\ s are equal if their `start` and `end` are +/// equal +func ==(lhs: ClosedInterval, rhs: ClosedInterval) -> Bool -func ==(lhs: Range, rhs: Range) -> Bool +func ==(lhs: T?, rhs: T?) -> Bool -func ==(lhs: FilterCollectionViewIndex, rhs: FilterCollectionViewIndex) -> Bool +func ==(lhs: T?, rhs: _OptionalNilComparisonType) -> Bool func ==(lhs: _OptionalNilComparisonType, rhs: T?) -> Bool func ===(lhs: AnyObject?, rhs: AnyObject?) -> Bool -func >(lhs: UInt64, rhs: UInt64) -> Bool +func >(lhs: T?, rhs: T?) -> Bool -func >(lhs: Int64, rhs: Int64) -> Bool +func >(lhs: Int, rhs: Int) -> Bool func >(lhs: UInt, rhs: UInt) -> Bool -func >(lhs: Int, rhs: Int) -> Bool +func >(lhs: Int64, rhs: Int64) -> Bool -func >(lhs: T?, rhs: T?) -> Bool +func >(lhs: T, rhs: T) -> Bool -func >(lhs: UInt32, rhs: UInt32) -> Bool +func >(lhs: UInt64, rhs: UInt64) -> Bool + +func >(lhs: UInt8, rhs: UInt8) -> Bool func >(lhs: Int32, rhs: Int32) -> Bool -func >(lhs: Int16, rhs: Int16) -> Bool +func >(lhs: Int8, rhs: Int8) -> Bool -func >(lhs: UInt16, rhs: UInt16) -> Bool +func >(lhs: UInt32, rhs: UInt32) -> Bool -func >(lhs: Int8, rhs: Int8) -> Bool +func >(lhs: Int16, rhs: Int16) -> Bool -func >(lhs: UInt8, rhs: UInt8) -> Bool +func >(lhs: UInt16, rhs: UInt16) -> Bool -func >(lhs: T, rhs: T) -> Bool +func >=(lhs: UInt16, rhs: UInt16) -> Bool func >=(lhs: UInt8, rhs: UInt8) -> Bool func >=(lhs: Int8, rhs: Int8) -> Bool -func >=(lhs: UInt16, rhs: UInt16) -> Bool - func >=(lhs: Int16, rhs: Int16) -> Bool func >=(lhs: UInt32, rhs: UInt32) -> Bool @@ -1071,67 +1128,229 @@ func >=(lhs: T?, rhs: T?) -> Bool func >=(lhs: T, rhs: T) -> Bool -func >>(lhs: Int64, rhs: Int64) -> Int64 - -func >>(lhs: Int, rhs: Int) -> Int +func >>(lhs: UInt16, rhs: UInt16) -> UInt16 -func >>(lhs: UInt, rhs: UInt) -> UInt +func >>(lhs: UInt32, rhs: UInt32) -> UInt32 func >>(lhs: Int16, rhs: Int16) -> Int16 -func >>(lhs: UInt16, rhs: UInt16) -> UInt16 - func >>(lhs: Int8, rhs: Int8) -> Int8 func >>(lhs: UInt8, rhs: UInt8) -> UInt8 -func >>(lhs: UInt32, rhs: UInt32) -> UInt32 - func >>(lhs: Int32, rhs: Int32) -> Int32 +func >>(lhs: Int, rhs: Int) -> Int + func >>(lhs: UInt64, rhs: UInt64) -> UInt64 -func >>=(inout lhs: UInt32, rhs: UInt32) +func >>(lhs: UInt, rhs: UInt) -> UInt -func >>=(inout lhs: Int, rhs: Int) +func >>(lhs: Int64, rhs: Int64) -> Int64 -func >>=(inout lhs: UInt, rhs: UInt) +func >>=(inout lhs: Int16, rhs: Int16) -func >>=(inout lhs: Int64, rhs: Int64) +func >>=(inout lhs: UInt16, rhs: UInt16) + +func >>=(inout lhs: Int8, rhs: Int8) func >>=(inout lhs: UInt8, rhs: UInt8) +func >>=(inout lhs: UInt, rhs: UInt) + +func >>=(inout lhs: Int, rhs: Int) + func >>=(inout lhs: UInt64, rhs: UInt64) func >>=(inout lhs: Int32, rhs: Int32) -func >>=(inout lhs: Int16, rhs: Int16) +func >>=(inout lhs: UInt32, rhs: UInt32) -func >>=(inout lhs: Int8, rhs: Int8) +func >>=(inout lhs: Int64, rhs: Int64) -func >>=(inout lhs: UInt16, rhs: UInt16) +func ??(optional: T?, defaultValue: @autoclosure () -> T) -> T func ??(optional: T?, defaultValue: @autoclosure () -> T?) -> T? -func ??(optional: T?, defaultValue: @autoclosure () -> T) -> T +/// A type that supports an "absolute value" function. protocol AbsoluteValuable : SignedNumberType { - class func abs(_: Self) -> Self + + /// Returns the absolute value of `x` + class func abs(x: Self) -> Self +} + + +/// The protocol to which all types implicitly conform +typealias Any = protocol<> + + +/// The protocol to which all class types implicitly conform. +/// +/// When used as a concrete type, all known `@objc` `class` methods and +/// properties are available, as implicitly-unwrapped-optional methods +/// and properties respectively, on each instance of `AnyClass`. For +/// example: +/// +/// .. parsed-literal: +/// +/// class C { +/// @objc class var cValue: Int { return 42 } +/// } +/// +/// // If x has an @objc cValue: Int, return its value. +/// // Otherwise, return nil. +/// func getCValue(x: AnyClass) -> Int? { +/// return **x.cValue** +/// } +/// +/// See also: `AnyObject` +typealias AnyClass = AnyObject.Type + + +/// The protocol to which all classes implicitly conform. +/// +/// When used as a concrete type, all known `@objc` methods and +/// properties are available, as implicitly-unwrapped-optional methods +/// and properties respectively, on each instance of `AnyObject`. For +/// example: +/// +/// .. parsed-literal: +/// +/// class C { +/// @objc func getCValue() -> Int { return 42 } +/// } +/// +/// // If x has a method @objc getValue()->Int, call it and +/// // return the result. Otherwise, return nil. +/// func getCValue1(x: AnyObject) -> Int? { +/// if let f: ()->Int = **x.getCValue** { +/// return f() +/// } +/// return nil +/// } +/// +/// // A more idiomatic implementation using "optional chaining" +/// func getCValue2(x: AnyObject) -> Int? { +/// return **x.getCValue?()** +/// } +/// +/// // An implementation that assumes the required method is present +/// func getCValue3(x: AnyObject) -> **Int** { +/// return **x.getCValue()** // x.getCValue is implicitly unwrapped. +/// } +/// +/// See also: `AnyClass` +@objc protocol AnyObject { } -typealias Any = protocol<> - -typealias AnyClass = AnyObject.Type - -protocol AnyObject { -} +/// Conceptually_, `Array` is an efficient, tail-growable random-access +/// collection of arbitrary elements. +/// +/// Common Properties of Array Types +/// ================================ +/// +/// The information in this section applies to all three of Swift's +/// array types, `Array`, `ContiguousArray`, and `Slice`. +/// When you read the word "array" here in a normal typeface, it +/// applies to all three of them. +/// +/// Value Semantics +/// --------------- +/// +/// Each array variable, `let` binding, or stored property has an +/// independent value that includes the values of all of its elements. +/// Therefore, mutations to the array are not observable through its +/// copies:: +/// +/// var a = [1, 2, 3] +/// var b = a +/// b[0] = 4 +/// println("a=\(a), b=\(b)") // a=[1, 2, 3], b=[4, 2, 3] +/// +/// (Of course, if the array stores `class` references, the objects +/// are shared; only the values of the references are independent) +/// +/// Arrays use Copy-on-Write so that their storage and elements are +/// only copied lazily, upon mutation, when more than one array +/// instance is using the same buffer. Therefore, the first in any +/// sequence of mutating operations may cost `O(N)` time and space, +/// where `N` is the length of the array. +/// +/// Growth and Capacity +/// ------------------- +/// +/// When an array's contiguous storage fills up, new storage must be +/// allocated and elements must be moved to the new storage. `Array`, +/// `ContiguousArray`, and `Slice` share an exponential growth +/// strategy that makes `append` a constant time operation *when +/// amortized over many invocations*. In addition to a `count` +/// property, these array types have a `capacity` that reflects their +/// potential to store elements without reallocation, and when you +/// know how many elements you'll store, you can call +/// `reserveCapacity` to pre-emptively reallocate and prevent +/// intermediate reallocations. +/// +/// .. _Conceptually: +/// +/// Objective-C Bridge +/// ================== +/// +/// The main distinction between `Array` and the other array types is +/// that it interoperates seamlessly and efficiently with Objective-C. +/// +/// `Array` is considered bridged to Objective-C iff `T` is bridged +/// to Objective-C. +/// +/// When `T` is a `class` or `@objc` protocol type, `Array` may store +/// its elements in an `NSArray`. Since any arbitrary subclass of +/// `NSArray` can become an `Array`, there are no guarantees about +/// representation or efficiency in this case (see also +/// `ContiguousArray`). Since `NSArray` is immutable, it is just as +/// though the storage was shared by some copy: the first in any +/// sequence of mutating operations causes elements to be copied into +/// unique, contiguous storage which may cost `O(N)` time and space, +/// where `N` is the length of the array (or more, if the underlying +/// `NSArray` is has unusual performance characteristics). +/// +/// Bridging to Objective-C +/// ----------------------- +/// +/// Any bridged `Array` can be implicitly converted to an `NSArray`. +/// When `T` is a `class` or `@objc` protocol, bridging takes O(1) +/// time and O(1) space. Other `Array`\ s must be bridged +/// element-by-element, allocating a new object for each element, at a +/// cost of at least O(`count`) time and space. +/// +/// Bridging from Objective-C +/// ------------------------- +/// +/// An `NSArray` can be implicitly or explicitly converted to any +/// bridged `Array`. This conversion calls `copyWithZone` on the +/// `NSArray`, to ensure it won't be modified, and stores the result +/// in the `Array`. Type-checking, to ensure the `NSArray`\ 's +/// elements match or can be bridged to `T`, is deferred until the +/// first element access. struct Array : MutableCollectionType, Sliceable { + + /// The type of element stored by this `Array` typealias Element = T + + /// Always zero, which is the index of the first element when non-empty. var startIndex: Int { get } + + /// A "past-the-end" element index; the successor of the last valid + /// subscript argument. var endIndex: Int { get } subscript (index: Int) -> T + + /// Return a *generator* over the elements. + /// + /// Complexity: O(1) func generate() -> IndexingGenerator<[T]> + + /// A type that can represent a sub-range of an `Array` typealias SubSlice = Slice subscript (subRange: Range) -> Slice @@ -1141,7 +1360,9 @@ struct Array : MutableCollectionType, Sliceable { } extension Array : ArrayLiteralConvertible { - static func convertFromArrayLiteral(elements: T...) -> [T] + + /// Create an instance containing `elements`. + init(arrayLiteral elements: T...) } @@ -1150,6 +1371,8 @@ extension Array { /// Construct an empty Array init() + + /// Construct from an arbitrary sequence with elements of type `T` init(_ s: S) /// Construct a Array of `count` elements, each initialized to @@ -1171,31 +1394,48 @@ extension Array { /// The last element, or `nil` if the array is empty var last: T? { get } - /// Ensure the array has enough mutable contiguous storage to store - /// minimumCapacity elements in. Note: does not affect count. - /// Complexity: O(N) + /// Reserve enough space to store minimumCapacity elements. + /// + /// PostCondition: `capacity >= minimumCapacity` and the array has + /// mutable contiguous storage. + /// + /// Complexity: O(`count`) mutating func reserveCapacity(minimumCapacity: Int) - /// Append newElement to the Array in O(1) (amortized) + /// Append newElement to the Array + /// + /// Complexity: amortized O(1) unless `self`'s storage is shared with another live array; O(`count`) if `self` does not wrap a bridged `NSArray`; otherwise the efficiency is unspecified. mutating func append(newElement: T) - /// Append elements from `sequence` to the Array - mutating func extend(sequence: S) + /// Append the elements of `newElements` to `self`. + /// + /// Complexity: O(*length of result*) + /// + mutating func extend(newElements: S) /// Remove an element from the end of the Array in O(1). /// Requires: count > 0 mutating func removeLast() -> T - /// Insert an element at index `i` in O(N). Requires: `i` <= - /// `count` + /// Insert `newElement` at index `i`. + /// + /// Requires: `i <= count` + /// + /// Complexity: O(\ `count`\ ). mutating func insert(newElement: T, atIndex i: Int) - /// Remove the element at the given index. Worst case complexity: - /// O(N). Requires: `index` < `count` + /// Remove and return the element at index `i` + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `count`\ ). mutating func removeAtIndex(index: Int) -> T - /// Erase all the elements. If `keepCapacity` is `true`, `capacity` - /// will not change + /// Remove all elements. + /// + /// Postcondition: `capacity == 0` iff `keepCapacity` is `false`. + /// + /// Complexity: O(\ `countElements(self)`\ ). mutating func removeAll(keepCapacity: Bool = default) /// Interpose `self` between each consecutive pair of `elements`, @@ -1224,24 +1464,30 @@ extension Array { /// over the elements. func sorted(isOrderedBefore: (T, T) -> Bool) -> [T] - /// Return an Array containing the results of calling + /// Return an `Array` containing the results of calling /// `transform(x)` on each element `x` of `self` func map(transform: (T) -> U) -> [U] /// A Array containing the elements of `self` in reverse order func reverse() -> [T] - /// Return an Array containing the elements `x` of `self` for which + /// Return an `Array` containing the elements `x` of `self` for which /// `includeElement(x)` is `true` func filter(includeElement: (T) -> Bool) -> [T] } extension Array : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension Array : Printable, DebugPrintable { + + /// A textual representation of `self`. var description: String { get } + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } @@ -1249,8 +1495,22 @@ extension Array : Printable, DebugPrintable { extension Array { - /// Call body(p), where p is a pointer to the Array's contiguous storage + /// Call `body(p)`, where `p` is a pointer to the `Array`\ 's + /// contiguous storage. If no such storage exists, it is first created. + /// + /// Often, the optimizer can eliminate bounds checks within an + /// array algorithm, but when that fails, invoking the + /// same algorithm on `body`\ 's argument lets you trade safety for + /// speed. func withUnsafeBufferPointer(body: (UnsafeBufferPointer) -> R) -> R + + /// Call `body(p)`, where `p` is a pointer to the `Array`\ 's + /// mutable contiguous storage. If no such storage exists, it is first created. + /// + /// Often, the optimizer can eliminate bounds- and uniqueness-checks + /// within an array algorithm, but when that fails, invoking the + /// same algorithm on `body`\ 's argument lets you trade safety for + /// speed. mutating func withUnsafeMutableBufferPointer(body: (inout UnsafeMutableBufferPointer) -> R) -> R } @@ -1261,53 +1521,43 @@ extension Array { } extension Array { - mutating func replaceRange(subRange: Range, with newValues: C) - mutating func splice(s: S, atIndex i: Int) + + /// Replace the given `subRange` of elements with `newElements`. + /// + /// Complexity: O(\ `countElements(subRange)`\ ) if `subRange.endIndex + /// == self.endIndex` and `isEmpty(newElements)`\ , O(N) otherwise. + mutating func replaceRange(subRange: Range, with newElements: C) + + /// Insert `newElements` at index `i` + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `count + countElements(newElements)`\ ). + mutating func splice(newElements: S, atIndex i: Int) + + /// Remove the indicated `subRange` of elements + /// + /// Complexity: O(\ `count`\ ). mutating func removeRange(subRange: Range) } extension Array { - /// Construct from the given `_CocoaArrayType`. If `noCopy` is `true`, - /// either `source` must be known to be immutable, or the resulting - /// `Array` must not survive across code that could mutate `source`. - init(_fromCocoaArray source: _CocoaArrayType, noCopy: Bool = default) + /// Construct from the given `_SwiftNSArrayRequiredOverridesType`. + /// + /// If `noCopy` is `true`, either `source` must be known to be immutable, + /// or the resulting / `Array` must not survive across code that could mutate + /// `source`. + init(_fromCocoaArray source: _SwiftNSArrayRequiredOverridesType, noCopy: Bool = default) } -/// Protocol describing types that can be used as array bounds. -/// -/// Types that conform to the `ArrayBoundType` protocol can be used as -/// array bounds by providing a property (`arrayBoundValue`) that -/// produces an integral value. -protocol ArrayBoundType { - typealias ArrayBound - var arrayBoundValue: ArrayBound { get } -} - +/// Conforming types can be initialized with array literals protocol ArrayLiteralConvertible { typealias Element - class func convertFromArrayLiteral(elements: Element...) -> Self -} - - -/// A String-like type that can be constructed from string interpolation, and -/// is considered less specific than `StaticString` in overload resolution. -struct AssertString : AssertStringType, StringInterpolationConvertible, Printable, DebugPrintable { - var stringValue: String - init() - init(_ value: String) - static func convertFromUnicodeScalarLiteral(value: String) -> AssertString - static func convertFromExtendedGraphemeClusterLiteral(value: String) -> AssertString - static func convertFromStringLiteral(value: String) -> AssertString - static func convertFromStringInterpolation(strings: AssertString...) -> AssertString - static func convertFromStringInterpolationSegment(expr: T) -> AssertString - var description: String { get } - var debugDescription: String { get } -} -protocol AssertStringType : UnicodeScalarLiteralConvertible, ExtendedGraphemeClusterLiteralConvertible, StringLiteralConvertible { - var stringValue: String { get } + /// Create an instance initialized with `elements`. + init(arrayLiteral elements: Element...) } @@ -1337,7 +1587,11 @@ struct AutoreleasingUnsafeMutablePointer : Equatable, NilLiteralConvertible { /// setting values. var memory: T { get nonmutating set } subscript (i: Int) -> T { get } - static func convertFromNilLiteral() -> AutoreleasingUnsafeMutablePointer + + /// Create an instance initialized with `nil`. + init(nilLiteral: ()) + + /// Returns `nil` static func null() -> AutoreleasingUnsafeMutablePointer /// Initialize to a null pointer. @@ -1352,9 +1606,14 @@ struct AutoreleasingUnsafeMutablePointer : Equatable, NilLiteralConvertible { } extension AutoreleasingUnsafeMutablePointer : DebugPrintable { + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } + +/// An *index* that can step backwards via application of its +/// `predecessor()` method. protocol BidirectionalIndexType : ForwardIndexType, _BidirectionalIndexType { } @@ -1362,51 +1621,145 @@ protocol BidirectionalIndexType : ForwardIndexType, _BidirectionalIndexType { /// The lazy `CollectionType` returned by `reverse(c)` where `c` is a /// `CollectionType` with an `Index` conforming to `BidirectionalIndexType` struct BidirectionalReverseView : CollectionType { + + /// A type that represents a valid position in the collection. + /// + /// Valid indices consist of the position of every element and a + /// "past the end" position that's not valid for use as a subscript. typealias Index = ReverseBidirectionalIndex + + /// A type whose instances can produce the elements of this + /// sequence, in order. typealias Generator = IndexingGenerator> + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> IndexingGenerator> + + /// The position of the first element in a non-empty collection. + /// + /// Identical to `endIndex` in an empty collection. var startIndex: Index { get } + + /// The collection's "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: Index { get } - subscript (i: Index) -> T.Generator.Element { get } + subscript (position: Index) -> T.Generator.Element { get } } + +/// A `RandomAccessIndexType` that has two possible values. Used as +/// the `Index` type for `SequenceOfOne`. enum Bit : Int, RandomAccessIndexType, Reflectable { case Zero case One + + /// Returns the next consecutive value after `self`. + /// + /// Requires: `self == .Zero`. func successor() -> Bit + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: `self != .Zero`. func predecessor() -> Bit + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). func distanceTo(other: Bit) -> Int + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) func advancedBy(distance: Int) -> Bit + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension Bit : IntegerArithmeticType { + + /// Add `lhs` and `rhs`, returning a result and a `Bool` that is + /// true iff the operation caused an arithmetic overflow. static func addWithOverflow(lhs: Bit, _ rhs: Bit) -> (Bit, overflow: Bool) + + /// Subtract `lhs` and `rhs`, returning a result and a `Bool` that is + /// true iff the operation caused an arithmetic overflow. static func subtractWithOverflow(lhs: Bit, _ rhs: Bit) -> (Bit, overflow: Bool) + + /// Multiply `lhs` and `rhs`, returning a result and a `Bool` that is + /// true iff the operation caused an arithmetic overflow. static func multiplyWithOverflow(lhs: Bit, _ rhs: Bit) -> (Bit, overflow: Bool) + + /// Divide `lhs` and `rhs`, returning a result and a `Bool` that is + /// true iff the operation caused an arithmetic overflow. static func divideWithOverflow(lhs: Bit, _ rhs: Bit) -> (Bit, overflow: Bool) + + /// Divide `lhs` and `rhs`, returning the remainder and a `Bool` that is + /// true iff the operation caused an arithmetic overflow. static func remainderWithOverflow(lhs: Bit, _ rhs: Bit) -> (Bit, overflow: Bool) + + /// Represent this number using Swift's widest native signed integer + /// type. func toIntMax() -> IntMax } + +/// A set type with O(1) standard bitwise operators. +/// +/// Each instance is a subset of `~Self.allZeros` +/// +/// Axioms, where `x` is an instance of `Self`:: +/// +/// x | Self.allZeros == x +/// x ^ Self.allZeros == x +/// x & Self.allZeros == .allZeros +/// x & ~Self.allZeros == x +/// ~x == x ^ ~Self.allZeros protocol BitwiseOperationsType { - func &(_: Self, _: Self) -> Self - func |(_: Self, _: Self) -> Self - func ^(_: Self, _: Self) -> Self - prefix func ~(_: Self) -> Self - /// The identity value for "|" and "^", and the fixed point for "&". + /// Returns the intersection of bits set in `lhs` and `rhs`. /// - /// :: + /// Complexity: O(1) + func &(lhs: Self, rhs: Self) -> Self + + /// Returns the union of bits set in `lhs` and `rhs` + /// + /// Complexity: O(1) + func |(lhs: Self, rhs: Self) -> Self + + /// Returns the bits that are set in exactly one of `lhs` and `rhs` /// - /// x | allZeros == x - /// x ^ allZeros == x - /// x & allZeros == allZeros - /// x & ~allZeros == x + /// Complexity: O(1) + func ^(lhs: Self, rhs: Self) -> Self + + /// Returns `x ^ ~Self.allZeros` + /// + /// Complexity: O(1) + prefix func ~(x: Self) -> Self + + /// The empty bitset. /// + /// Also the `identity element + /// `_ for `|` and + /// `^`, and the `fixed point + /// `_ for + /// `&`. class var allZeros: Self { get } } + +/// A value type whose instances are either `true` or `false`. struct Bool { /// Default-initialize Boolean value to `false`. @@ -1414,42 +1767,73 @@ struct Bool { } extension Bool : BooleanLiteralConvertible { - static func convertFromBooleanLiteral(value: Bool) -> Bool + init(_builtinBooleanLiteral value: Builtin.Int1) + + /// Create an instance initialized to `value`. + init(booleanLiteral value: Bool) } extension Bool : BooleanType { + + /// Identical to `self`. var boolValue: Bool { get } - init(_ v: T) + + /// Construct an instance representing the same logical value as + /// `value` + init(_ value: T) } extension Bool : Printable { + + /// A textual representation of `self`. var description: String { get } } extension Bool : Equatable, Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension Bool : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } + +/// Conforming types can be initialized with the boolean literals +/// `true` and `false`. protocol BooleanLiteralConvertible { typealias BooleanLiteralType - class func convertFromBooleanLiteral(value: BooleanLiteralType) -> Self + + /// Create an instance initialized to `value`. + init(booleanLiteral value: BooleanLiteralType) } + +/// The default type for an otherwise-unconstrained boolean literal typealias BooleanLiteralType = Bool -/// Protocol describing types that can be used as logical values within -/// a condition. +/// A type that represents a boolean value. /// /// Types that conform to the `BooleanType` protocol can be used as -/// condition in various control statements (`if`, `while`, C-style -/// `for`) as well as other logical value contexts (e.g., `case` -/// statement guards). +/// the condition in control statements (`if`, `while`, C-style `for`) +/// and other logical value contexts (e.g., `case` statement guards). +/// +/// Only two types provided by Swift, `Bool` and `ObjCBool`, conform +/// to `BooleanType`. Expanding this set to include types that +/// represent more than simple boolean values is discouraged. protocol BooleanType { + + /// The value of `self`, expressed as a `Bool`. var boolValue: Bool { get } } @@ -1480,15 +1864,45 @@ typealias CDouble = Double /// The C 'float' type. typealias CFloat = Float + +/// The family of C function pointer types. +/// +/// In imported APIs, `T` is a Swift function type such as +/// `(Int)->String`. +/// +/// Though not directly useful in Swift, `CFunctionPointer` can be +/// used to safely pass a C function pointer, received from one C or +/// Objective-C API, to another C or Objective-C API. struct CFunctionPointer : Equatable, Hashable, NilLiteralConvertible { + + /// Create a `nil` instance. init() + + /// Reinterpret the bits of `value` as `CFunctionPointer`. + /// + /// .. Warning:: This is a fundamentally unsafe operation, equivalent to + /// `unsafeBitCast(value, CFunctionPointer.self)` init(_ value: COpaquePointer) + + /// Returns `nil` static func null() -> CFunctionPointer + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } - static func convertFromNilLiteral() -> CFunctionPointer + + /// Create an instance initialized with `nil`. + init(nilLiteral: ()) } extension CFunctionPointer : DebugPrintable { + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } @@ -1510,6 +1924,8 @@ typealias CLongLong = Int64 /// Opaque pointers are used to represent C pointers to types that /// cannot be represented in Swift, such as incomplete struct types. struct COpaquePointer : Equatable, Hashable, NilLiteralConvertible { + + /// Construct a `nil` instance. init() /// Construct a `COpaquePointer` from a given address in memory. @@ -1527,20 +1943,42 @@ struct COpaquePointer : Equatable, Hashable, NilLiteralConvertible { /// Convert a typed `UnsafeMutablePointer` to an opaque C pointer. init(_ value: UnsafeMutablePointer) + + /// Returns `nil` static func null() -> COpaquePointer + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } - static func convertFromNilLiteral() -> COpaquePointer + + /// Create an instance initialized with `nil`. + init(nilLiteral: ()) } extension COpaquePointer : DebugPrintable { + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } extension COpaquePointer { - init(_ from: CFunctionPointer) + + /// Reinterpret the bits of `value` as `COpaquePointer`. + /// + /// .. Warning:: This is a fundamentally unsafe operation, equivalent to + /// `unsafeBitCast(value, COpaquePointer.self)` + init(_ value: CFunctionPointer) } extension COpaquePointer : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } @@ -1572,14 +2010,40 @@ typealias CUnsignedLongLong = UInt64 /// The C 'unsigned short' type. typealias CUnsignedShort = UInt16 + +/// The corresponding Swift type to `va_list` in imported C APIs. struct CVaListPointer { } extension CVaListPointer : DebugPrintable { + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } + +/// Instances of conforming types can be encoded, and appropriately +/// passed, as elements of a C `va_list`. +/// +/// This protocol is useful in presenting C "varargs" APIs natively in +/// Swift. It only works for APIs that have a `va_list` variant, so +/// for example, it isn't much use if all you have is:: +/// +/// int f(int n, ...) +/// +/// Given a version like this, though, :: +/// +/// int f(int, va_list arguments) +/// +/// you can write:: +/// +/// func swiftF(x: Int, arguments: CVarArgType...) -> Int { +/// return withVaList(arguments) { f(x, $0) } +/// } protocol CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } @@ -1603,27 +2067,48 @@ var C_ARGV: UnsafeMutablePointer> enum Character : ExtendedGraphemeClusterLiteralConvertible, Equatable, Hashable, Comparable { case LargeRepresentation(OnHeap) case SmallRepresentation + + /// Construct a `Character` containing just the given `scalar`. init(_ scalar: UnicodeScalar) - static func convertFromUnicodeScalarLiteral(value: Character) -> Character - static func convertFromExtendedGraphemeClusterLiteral(value: Character) -> Character + init(_builtinUnicodeScalarLiteral value: Builtin.Int32) + + /// Create an instance initialized to `value`. + init(unicodeScalarLiteral value: Character) + init(_builtinExtendedGraphemeClusterLiteral start: Builtin.RawPointer, byteSize: Builtin.Word, isASCII: Builtin.Int1) + + /// Create an instance initialized to `value`. + init(extendedGraphemeClusterLiteral value: Character) + + /// Create an instance from a single-character `String`. + /// + /// Requires: `s` contains exactly one extended grapheme cluster. init(_ s: String) + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension Character : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension Character : Streamable { - func writeTo(inout target: Target) -} -protocol CharacterLiteralConvertible { - typealias CharacterLiteralType - class func convertFromCharacterLiteral(value: CharacterLiteralType) -> Self + /// Write a textual representation of `self` into `target` + func writeTo(inout target: Target) } struct ClosedInterval : IntervalType, Equatable, Printable, DebugPrintable, Reflectable { + + /// The type of the `Interval`\ 's endpoints typealias Bound = T /// Construct a copy of `x` @@ -1639,10 +2124,10 @@ struct ClosedInterval : IntervalType, Equatable, Printable, Debu /// The `Interval`\ 's upper bound. Invariant: `start` <= `end` var end: T { get } - /// The `Interval`\ 's printed representation + /// A textual representation of `self`. var description: String { get } - /// The `Interval`\ 's verbose printed representation + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } /// Returns `true` iff the `Interval` contains `x` @@ -1652,6 +2137,8 @@ struct ClosedInterval : IntervalType, Equatable, Printable, Debu /// result, even if it is empty, are always limited to the bounds of /// `self` func clamp(intervalToClamp: ClosedInterval) -> ClosedInterval + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } @@ -1662,44 +2149,114 @@ extension ClosedInterval { var isEmpty: Bool { get } } + +/// A collection containing a single element of type `T`. struct CollectionOfOne : CollectionType { + + /// A type that represents a valid position in the collection. + /// + /// Valid indices consist of the position of every element and a + /// "past the end" position that's not valid for use as a subscript. typealias Index = Bit + + /// Construct an instance containing just `element`. init(_ element: T) + + /// The position of the first element. var startIndex: Index { get } + + /// The "past the end" position; always identical to + /// `startIndex.successor()`. + /// + /// Note: `endIndex` is not a valid argument to `subscript`. var endIndex: Index { get } + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> GeneratorOfOne - subscript (i: Index) -> T { get } + subscript (position: Index) -> T { get } } extension CollectionOfOne : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } + +/// A multi-pass *sequence* with addressable positions. +/// +/// Positions are represented by an associated `Index` type. Whereas +/// an arbitrary *sequence* may be consumed as it is traversed, a +/// *collection* is multi-pass: any element may be revisited merely by +/// saving its index. +/// +/// The sequence view of the elements is identical to the collection +/// view. In other words, the following code binds the same series of +/// values to `x` as does `for x in self {}`:: +/// +/// for i in startIndex.. Self.Generator.Element { get } + subscript (position: Self.Index) -> Self.Generator.Element { get } } -/// Types implementing the `Comparable` protocol can be compared using -/// relational operators `<`, `<=`, `>=`, `>`. +/// Instances of conforming types can be compared using relational +/// operators, which define a `strict total order +/// `_. +/// +/// A type conforming to `Comparable` need only supply the `<` and +/// `==` operators; default implementations of `<=`, `>`, `>=`, and +/// `!=` are supplied by the standard library:: /// -/// When adopting `Comparable`, only the `<` operator is required to be -/// implemented. The standard library provides implementations for `<=`, -/// `>=`, `>`. +/// struct Singular : Comparable {} +/// func ==(x: Singular, y: Singular) -> Bool { return true } +/// func <(x: Singular, y: Singular) -> Bool { return false } /// -/// The `<` operator must define a total order. +/// **Axioms**, in addition to those of `Equatable`: +/// +/// - `x == y` implies `x <= y`, `x >= y`, `!(x < y)`, and `!(x > y)` +/// - `x < y` implies `x <= y` and `y > x` +/// - `x > y` implies `x >= y` and `y < x` +/// - `x <= y` implies `y >= x` +/// - `x >= y` implies `y <= x` protocol Comparable : _Comparable, Equatable { func <=(lhs: Self, rhs: Self) -> Bool func >=(lhs: Self, rhs: Self) -> Bool func >(lhs: Self, rhs: Self) -> Bool } + +/// A fast, contiguously-stored array of `T`. +/// +/// Efficiency is equivalent to that of `Array`, unless `T` is a +/// `class` or `@objc` `protocol` type, in which case using +/// `ContiguousArray` may be more efficient. Note, however, that +/// `ContiguousArray` does not bridge to Objective-C. See `Array`, +/// with which `ContiguousArray` shares most properties, for more +/// detail. struct ContiguousArray : MutableCollectionType, Sliceable { + + /// The type of element stored by this `ContiguousArray` typealias Element = T + + /// Always zero, which is the index of the first element when non-empty. var startIndex: Int { get } + + /// A "past-the-end" element index; the successor of the last valid + /// subscript argument. var endIndex: Int { get } subscript (index: Int) -> T + + /// Return a *generator* over the elements. + /// + /// Complexity: O(1) func generate() -> IndexingGenerator> + + /// A type that can represent a sub-range of a ContiguousArray typealias SubSlice = Slice subscript (subRange: Range) -> Slice @@ -1709,7 +2266,9 @@ struct ContiguousArray : MutableCollectionType, Sliceable { } extension ContiguousArray : ArrayLiteralConvertible { - static func convertFromArrayLiteral(elements: T...) -> ContiguousArray + + /// Create an instance containing `elements`. + init(arrayLiteral elements: T...) } @@ -1718,6 +2277,8 @@ extension ContiguousArray { /// Construct an empty ContiguousArray init() + + /// Construct from an arbitrary sequence with elements of type `T` init(_ s: S) /// Construct a ContiguousArray of `count` elements, each initialized to @@ -1739,31 +2300,48 @@ extension ContiguousArray { /// The last element, or `nil` if the array is empty var last: T? { get } - /// Ensure the array has enough mutable contiguous storage to store - /// minimumCapacity elements in. Note: does not affect count. - /// Complexity: O(N) + /// Reserve enough space to store minimumCapacity elements. + /// + /// PostCondition: `capacity >= minimumCapacity` and the array has + /// mutable contiguous storage. + /// + /// Complexity: O(`count`) mutating func reserveCapacity(minimumCapacity: Int) - /// Append newElement to the ContiguousArray in O(1) (amortized) + /// Append newElement to the ContiguousArray + /// + /// Complexity: amortized O(1) unless `self`'s storage is shared with another live array; O(`count`) otherwise. mutating func append(newElement: T) - /// Append elements from `sequence` to the Array - mutating func extend(sequence: S) + /// Append the elements of `newElements` to `self`. + /// + /// Complexity: O(*length of result*) + /// + mutating func extend(newElements: S) /// Remove an element from the end of the ContiguousArray in O(1). /// Requires: count > 0 mutating func removeLast() -> T - /// Insert an element at index `i` in O(N). Requires: `i` <= - /// `count` + /// Insert `newElement` at index `i`. + /// + /// Requires: `i <= count` + /// + /// Complexity: O(\ `count`\ ). mutating func insert(newElement: T, atIndex i: Int) - /// Remove the element at the given index. Worst case complexity: - /// O(N). Requires: `index` < `count` + /// Remove and return the element at index `i` + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `count`\ ). mutating func removeAtIndex(index: Int) -> T - /// Erase all the elements. If `keepCapacity` is `true`, `capacity` - /// will not change + /// Remove all elements. + /// + /// Postcondition: `capacity == 0` iff `keepCapacity` is `false`. + /// + /// Complexity: O(\ `countElements(self)`\ ). mutating func removeAll(keepCapacity: Bool = default) /// Interpose `self` between each consecutive pair of `elements`, @@ -1805,11 +2383,17 @@ extension ContiguousArray { } extension ContiguousArray : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension ContiguousArray : Printable, DebugPrintable { + + /// A textual representation of `self`. var description: String { get } + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } @@ -1817,25 +2401,63 @@ extension ContiguousArray : Printable, DebugPrintable { extension ContiguousArray { - /// Call body(p), where p is a pointer to the ContiguousArray's contiguous storage + /// Call `body(p)`, where `p` is a pointer to the `ContiguousArray`\ 's + /// contiguous storage. + /// + /// Often, the optimizer can eliminate bounds checks within an + /// array algorithm, but when that fails, invoking the + /// same algorithm on `body`\ 's argument lets you trade safety for + /// speed. func withUnsafeBufferPointer(body: (UnsafeBufferPointer) -> R) -> R + + /// Call `body(p)`, where `p` is a pointer to the `ContiguousArray`\ 's + /// mutable contiguous storage. + /// + /// Often, the optimizer can eliminate bounds- and uniqueness-checks + /// within an array algorithm, but when that fails, invoking the + /// same algorithm on `body`\ 's argument lets you trade safety for + /// speed. mutating func withUnsafeMutableBufferPointer(body: (inout UnsafeMutableBufferPointer) -> R) -> R } extension ContiguousArray { - mutating func replaceRange(subRange: Range, with newValues: C) - mutating func splice(s: S, atIndex i: Int) + + /// Replace the given `subRange` of elements with `newElements`. + /// + /// Complexity: O(\ `countElements(subRange)`\ ) if `subRange.endIndex + /// == self.endIndex` and `isEmpty(newElements)`\ , O(N) otherwise. + mutating func replaceRange(subRange: Range, with newElements: C) + + /// Insert `newElements` at index `i` + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `count + countElements(newElements)`\ ). + mutating func splice(newElements: S, atIndex i: Int) + + /// Remove the indicated `subRange` of elements + /// + /// Complexity: O(\ `count`\ ). mutating func removeRange(subRange: Range) } -/// This protocol should be adopted by types that wish to customize their -/// textual representation used for debugging purposes. This textual -/// representation is used when objects are written to an `OutputStreamType`. +/// A type with a customized textual representation for debugging +/// purposes. +/// +/// This textual representation is used when objects are written to an +/// *output stream* by `debugPrint` and `debugPrintln`, and is +/// typically more verbose than the text provided by a `Printable`\ 's +/// `description` property. protocol DebugPrintable { + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } + +/// A hash-based mapping from `Key` to `Value` instances. Also a +/// collection of key-value pairs with no defined ordering. struct Dictionary : CollectionType, DictionaryLiteralConvertible { typealias Element = (Key, Value) typealias Index = DictionaryIndex @@ -1843,14 +2465,35 @@ struct Dictionary : CollectionType, DictionaryLiteralConv /// Create a dictionary with at least the given number of /// elements worth of storage. The actual capacity will be the /// smallest power of 2 that's >= `minimumCapacity`. - init(minimumCapacity: Int = default) + init() + + /// Create a dictionary with at least the given number of + /// elements worth of storage. The actual capacity will be the + /// smallest power of 2 that's >= `minimumCapacity`. + init(minimumCapacity: Int) + + /// The position of the first element in a non-empty dictionary. + /// + /// Identical to `endIndex` in an empty dictionary + /// + /// Complexity: amortized O(1) if `self` does not wrap a bridged + /// `NSDictionary`, O(N) otherwise. var startIndex: DictionaryIndex { get } + + /// The collection's "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. + /// + /// Complexity: amortized O(1) if `self` does not wrap a bridged + /// `NSDictionary`, O(N) otherwise. var endIndex: DictionaryIndex { get } /// Returns the `Index` for the given key, or `nil` if the key is not /// present in the dictionary. func indexForKey(key: Key) -> DictionaryIndex? - subscript (i: DictionaryIndex) -> (Key, Value) { get } + subscript (position: DictionaryIndex) -> (Key, Value) { get } subscript (key: Key) -> Value? /// Update the value stored in the dictionary for the given key, or, if they @@ -1860,7 +2503,11 @@ struct Dictionary : CollectionType, DictionaryLiteralConv /// was added. mutating func updateValue(value: Value, forKey key: Key) -> Value? - /// Remove the key-value pair referenced by the given index. + /// Remove the key-value pair at index `i` + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `count`\ ). mutating func removeAtIndex(index: DictionaryIndex) /// Remove a given key and the associated value from the dictionary. @@ -1868,94 +2515,206 @@ struct Dictionary : CollectionType, DictionaryLiteralConv /// in the dictionary. mutating func removeValueForKey(key: Key) -> Value? - /// Erase all the elements. If `keepCapacity` is `true`, `capacity` - /// will not decrease. + /// Remove all elements. + /// + /// Postcondition: `capacity == 0` iff `keepCapacity` is `false`. + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `count`\ ). mutating func removeAll(keepCapacity: Bool = default) /// The number of entries in the dictionary. /// /// Complexity: O(1) var count: Int { get } + + /// Return a *generator* over the (key, value) pairs. + /// + /// Complexity: O(1) func generate() -> DictionaryGenerator - static func convertFromDictionaryLiteral(elements: (Key, Value)...) -> [Key : Value] + + /// Create an instance initialized with `elements`. + init(dictionaryLiteral elements: (Key, Value)...) + + /// True iff `count == 0` var isEmpty: Bool { get } + + /// A collection containing just the keys of `self` + /// + /// Keys appear in the same order as they occur as the `.0` member + /// of key-value pairs in `self`. Each key in the result has a + /// unique value. var keys: LazyBidirectionalCollection> { get } + + /// A collection containing just the values of `self` + /// + /// Values appear in the same order as they occur as the `.1` member + /// of key-value pairs in `self`. var values: LazyBidirectionalCollection> { get } } extension Dictionary : Printable, DebugPrintable { + + /// A textual representation of `self`. var description: String { get } + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } extension Dictionary : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } + +/// A generator over the key-value pairs of a `Dictionary` struct DictionaryGenerator : GeneratorType { + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. + /// + /// Requires: no preceding call to `self.next()` has returned `nil`. mutating func next() -> (Key, Value)? } + +/// Used to access the key-value pairs in an instance of +/// `Dictionary`. +/// +/// Remember that Dictionary has two subscripting interfaces: +/// +/// 1. Subscripting with a key, yielding an optional value:: +/// +/// v = d[k]! +/// +/// 2. Subscripting with an index, yielding a key-value pair: +/// +/// (k,v) = d[i] struct DictionaryIndex : BidirectionalIndexType, Comparable { + + /// Identical to `self.dynamicType` typealias Index = DictionaryIndex + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> DictionaryIndex + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> DictionaryIndex } + +/// Conforming types can be initialized with dictionary literals protocol DictionaryLiteralConvertible { typealias Key typealias Value - class func convertFromDictionaryLiteral(elements: (Key, Value)...) -> Self + + /// Create an instance initialized with `elements`. + init(dictionaryLiteral elements: (Key, Value)...) } struct Double { + + /// Create an instance initialized to zero. init() + + /// Create an instance initialized to `value`. init(_ value: Double) } extension Double : Printable { + + /// A textual representation of `self`. var description: String { get } } extension Double : FloatingPointType { + + /// The positive infinity. static var infinity: Double { get } + + /// A quiet NaN. static var NaN: Double { get } + + /// A quiet NaN. static var quietNaN: Double { get } + + /// `true` iff `self` is negative var isSignMinus: Bool { get } + + /// `true` iff `self` is normal (not zero, subnormal, infinity, or + /// NaN). var isNormal: Bool { get } + + /// `true` iff `self` is zero, subnormal, or normal (not infinity + /// or NaN). var isFinite: Bool { get } + + /// `true` iff `self` is +0.0 or -0.0. var isZero: Bool { get } + + /// `true` iff `self` is subnormal. var isSubnormal: Bool { get } + + /// `true` iff `self` is infinity. var isInfinite: Bool { get } + + /// `true` iff `self` is NaN. var isNaN: Bool { get } + + /// `true` iff `self` is a signaling NaN. var isSignaling: Bool { get } } extension Double { + + /// The IEEE 754 "class" of this type. var floatingPointClass: FloatingPointClassification { get } } extension Double : IntegerLiteralConvertible { - static func convertFromIntegerLiteral(value: Int64) -> Double + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: Int64) } extension Double { + init(_builtinFloatLiteral value: Builtin.FPIEEE80) } extension Double : FloatLiteralConvertible { - static func convertFromFloatLiteral(value: Double) -> Double + + /// Create an instance initialized to `value`. + init(floatLiteral value: Double) } extension Double : Comparable { } extension Double : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension Double : AbsoluteValuable { + + /// Returns the absolute value of `x` static func abs(x: Double) -> Double } @@ -1973,67 +2732,194 @@ extension Double { } extension Double { - init(_ v: Float) - init(_ v: Float80) + + /// Construct an instance that approximates `other`. + init(_ other: Float) + + /// Construct an instance that approximates `other`. + init(_ other: Float80) } extension Double : Strideable { + + /// Returns a stride `x` such that `self.advancedBy(x)` approximates + /// `other`. + /// + /// Complexity: O(1). func distanceTo(other: Double) -> Double + + /// Returns a `Self` `x` such that `self.distanceTo(x)` approximates + /// `n`. + /// + /// Complexity: O(1). func advancedBy(amount: Double) -> Double } extension Double : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension Double : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } + +/// A collection whose element type is `T` but that is always empty. struct EmptyCollection : CollectionType { + + /// A type that represents a valid position in the collection. + /// + /// Valid indices consist of the position of every element and a + /// "past the end" position that's not valid for use as a subscript. typealias Index = Int + + /// Construct an instance. init() + + /// Always zero, just like `endIndex`. var startIndex: Index { get } + + /// Always zero, just like `startIndex`. var endIndex: Index { get } + + /// Returns an empty *generator*. + /// + /// Complexity: O(1) func generate() -> EmptyGenerator - subscript (i: Index) -> T { get } + subscript (position: Index) -> T { get } } extension EmptyCollection : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } + +/// A generator that never produces an element. +/// +/// See also: `EmptyCollection`. struct EmptyGenerator : GeneratorType, SequenceType { + + /// `EmptyGenerator` is also a `SequenceType`, so it `generate`\ 's + /// a copy of itself func generate() -> EmptyGenerator + + /// Return `nil`, indicating that there are no more elements. mutating func next() -> T? } + +/// The `GeneratorType` for `EnumerateSequence`. `EnumerateGenerator` +/// wraps a `Base` `GeneratorType` and yields successive `Int` values, +/// starting at zero, along with the elements of the underlying +/// `Base`:: +/// +/// var g = EnumerateGenerator(["foo", "bar"].generate()) +/// g.next() // (0, "foo") +/// g.next() // (1, "bar") +/// g.next() // nil +/// +/// Note:: idiomatic usage is to call `enumerate` instead of +/// constructing an `EnumerateGenerator` directly. struct EnumerateGenerator : GeneratorType, SequenceType { + + /// The type of element returned by `next()`. typealias Element = (index: Int, element: Base.Element) + + /// Construct from a `Base` generator + init(_ base: Base) + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. + /// + /// Requires: no preceding call to `self.next()` has returned `nil`. mutating func next() -> Element? + + /// A type whose instances can produce the elements of this + /// sequence, in order. typealias Generator = EnumerateGenerator + + /// `EnumerateGenerator` is also a `SequenceType`, so it `generate`\ + /// 's a copy of itself func generate() -> EnumerateGenerator } -/// Types implementing the `Equatable` protocol can be compared for value -/// equality using operators `==` and `!=`. +/// The `SequenceType` returned by `enumerate()`. `EnumerateSequence` +/// is a sequence of pairs (*n*, *x*), where *n*\ s are consecutive +/// `Int`\ s starting at zero, and *x*\ s are the elements of a `Base` +/// `SequenceType`:: +/// +/// var s = EnumerateSequence(["foo", "bar"]) +/// Array(s) // [(0, "foo"), (1, "bar")] +/// +/// Note:: idiomatic usage is to call `enumerate` instead of +/// constructing an `EnumerateSequence` directly. +struct EnumerateSequence : SequenceType { + + /// Construct from a `Base` sequence + init(_ base: Base) + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) + func generate() -> EnumerateGenerator +} + + +/// Instances of conforming types can be compared for value equality +/// using operators `==` and `!=`. /// /// When adopting `Equatable`, only the `==` operator is required to be /// implemented. The standard library provides an implementation for `!=`. -/// -/// The `==` operator must define an equivalence relation. protocol Equatable { + + /// Return true if `lhs` is equal to `rhs`. + /// + /// **Equality implies substitutability**. When `x == y`, `x` and + /// `y` are interchangeable in any code that only depends on their + /// values. + /// + /// Class instance identity as distinguished by triple-equals `===` + /// is notably not part of an instance's value. Exposing other + /// non-value aspects of `Equatable` types is discouraged, and any + /// that *are* exposed should be explicitly pointed out in + /// documentation. + /// + /// **Equality is an equivalence relation** + /// + /// - `x == x` is `true` + /// - `x == y` implies `y == x` + /// - `x == y` and `y == z` implies `x == z` + /// + /// **Inequality is the inverse of equality**, i.e. `!(x == y)` iff + /// `x != y` func ==(lhs: Self, rhs: Self) -> Bool } + +/// Conforming types can be initialized with string literals +/// containing a single Unicode extended grapheme cluster. protocol ExtendedGraphemeClusterLiteralConvertible : UnicodeScalarLiteralConvertible { typealias ExtendedGraphemeClusterLiteralType - class func convertFromExtendedGraphemeClusterLiteral(value: ExtendedGraphemeClusterLiteralType) -> Self + + /// Create an instance initialized to `value`. + init(extendedGraphemeClusterLiteral value: ExtendedGraphemeClusterLiteralType) } + +/// The default type for an otherwise-unconstrained unicode extended +/// grapheme cluster literal typealias ExtendedGraphemeClusterType = String + +/// A collection type that can be efficiently appended-to. protocol ExtensibleCollectionType : _ExtensibleCollectionType { } @@ -2052,17 +2938,48 @@ protocol ExtensibleCollectionType : _ExtensibleCollectionType { /// This causes the filter predicate to be called twice for each /// element of the underlying collection, which is surprising. struct FilterCollectionView : CollectionType { + + /// A type that represents a valid position in the collection. + /// + /// Valid indices consist of the position of every element and a + /// "past the end" position that's not valid for use as a subscript. typealias Index = FilterCollectionViewIndex - init(_ base: Base, includeElement: (Base.Generator.Element) -> Bool) + + /// Construct an instance containing the elements of `base` that + /// satisfy `predicate`. + init(_ base: Base, includeElement predicate: (Base.Generator.Element) -> Bool) + + /// The position of the first element in a non-empty collection. + /// + /// Identical to `endIndex` in an empty collection. + /// + /// Complexity: O(N), where N is the ratio between unfiltered and + /// filtered collection counts. var startIndex: FilterCollectionViewIndex { get } + + /// The collection's "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. + /// + /// Complexity: O(1) var endIndex: FilterCollectionViewIndex { get } - subscript (index: FilterCollectionViewIndex) -> Base.Generator.Element { get } + subscript (position: FilterCollectionViewIndex) -> Base.Generator.Element { get } + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> FilterGenerator } /// The `Index` used for subscripting a `FilterCollectionView` struct FilterCollectionViewIndex : ForwardIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> FilterCollectionViewIndex } @@ -2070,7 +2987,17 @@ struct FilterCollectionViewIndex : ForwardIndexType { /// The `GeneratorType` used by `FilterSequenceView` and /// `FilterCollectionView` struct FilterGenerator : GeneratorType, SequenceType { + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. + /// + /// Requires: `next()` has not been applied to a copy of `self` + /// since the copy was made, and no preceding call to `self.next()` + /// has returned `nil`. mutating func next() -> Base.Element? + + /// `FilterGenerator` is also a `SequenceType`, so it `generate`\ 's + /// a copy of itself func generate() -> FilterGenerator } @@ -2078,55 +3005,107 @@ struct FilterGenerator : GeneratorType, SequenceType { /// The lazy `SequenceType` returned by `filter(c)` where `c` is a /// `SequenceType` struct FilterSequenceView : SequenceType { + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> FilterGenerator } struct Float { + + /// Create an instance initialized to zero. init() + + /// Create an instance initialized to `value`. init(_ value: Float) } extension Float : Printable { + + /// A textual representation of `self`. var description: String { get } } extension Float : FloatingPointType { + + /// The positive infinity. static var infinity: Float { get } + + /// A quiet NaN. static var NaN: Float { get } + + /// A quiet NaN. static var quietNaN: Float { get } + + /// `true` iff `self` is negative var isSignMinus: Bool { get } + + /// `true` iff `self` is normal (not zero, subnormal, infinity, or + /// NaN). var isNormal: Bool { get } + + /// `true` iff `self` is zero, subnormal, or normal (not infinity + /// or NaN). var isFinite: Bool { get } + + /// `true` iff `self` is +0.0 or -0.0. var isZero: Bool { get } + + /// `true` iff `self` is subnormal. var isSubnormal: Bool { get } + + /// `true` iff `self` is infinity. var isInfinite: Bool { get } + + /// `true` iff `self` is NaN. var isNaN: Bool { get } + + /// `true` iff `self` is a signaling NaN. var isSignaling: Bool { get } } extension Float { + + /// The IEEE 754 "class" of this type. var floatingPointClass: FloatingPointClassification { get } } extension Float : IntegerLiteralConvertible { - static func convertFromIntegerLiteral(value: Int64) -> Float + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: Int64) } extension Float { + init(_builtinFloatLiteral value: Builtin.FPIEEE80) } extension Float : FloatLiteralConvertible { - static func convertFromFloatLiteral(value: Float) -> Float + + /// Create an instance initialized to `value`. + init(floatLiteral value: Float) } extension Float : Comparable { } extension Float : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension Float : AbsoluteValuable { + + /// Returns the absolute value of `x` static func abs(x: Float) -> Float } @@ -2144,55 +3123,100 @@ extension Float { } extension Float { - init(_ v: Double) - init(_ v: Float80) + + /// Construct an instance that approximates `other`. + init(_ other: Double) + + /// Construct an instance that approximates `other`. + init(_ other: Float80) } extension Float : Strideable { + + /// Returns a stride `x` such that `self.advancedBy(x)` approximates + /// `other`. + /// + /// Complexity: O(1). func distanceTo(other: Float) -> Float + + /// Returns a `Self` `x` such that `self.distanceTo(x)` approximates + /// `n`. + /// + /// Complexity: O(1). func advancedBy(amount: Float) -> Float } extension Float : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension Float : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } + +/// A 32-bit floating point type typealias Float32 = Float + +/// A 64-bit floating point type typealias Float64 = Double struct Float80 { + + /// Create an instance initialized to zero. init() + + /// Create an instance initialized to `value`. init(_ value: Float80) } extension Float80 : Printable { + + /// A textual representation of `self`. var description: String { get } } extension Float80 : IntegerLiteralConvertible { - static func convertFromIntegerLiteral(value: Int64) -> Float80 + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: Int64) } extension Float80 { + init(_builtinFloatLiteral value: Builtin.FPIEEE80) } extension Float80 : FloatLiteralConvertible { - static func convertFromFloatLiteral(value: Float80) -> Float80 + + /// Create an instance initialized to `value`. + init(floatLiteral value: Float80) } extension Float80 : Comparable { } extension Float80 : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension Float80 : AbsoluteValuable { + + /// Returns the absolute value of `x` static func abs(x: Float80) -> Float80 } @@ -2210,22 +3234,44 @@ extension Float80 { } extension Float80 { - init(_ v: Float) - init(_ v: Double) + + /// Construct an instance that approximates `other`. + init(_ other: Float) + + /// Construct an instance that approximates `other`. + init(_ other: Double) } extension Float80 : Strideable { + + /// Returns a stride `x` such that `self.advancedBy(x)` approximates + /// `other`. + /// + /// Complexity: O(1). func distanceTo(other: Float80) -> Float80 + + /// Returns a `Self` `x` such that `self.distanceTo(x)` approximates + /// `n`. + /// + /// Complexity: O(1). func advancedBy(amount: Float80) -> Float80 } + +/// Conforming types can be initialized with floating point literals protocol FloatLiteralConvertible { typealias FloatLiteralType - class func convertFromFloatLiteral(value: FloatLiteralType) -> Self + + /// Create an instance initialized to `value`. + init(floatLiteral value: FloatLiteralType) } + +/// The default type for an otherwise-unconstrained floating point literal typealias FloatLiteralType = Double + +/// The set of possible IEEE 754 "classes" enum FloatingPointClassification { case SignalingNaN case QuietNaN @@ -2242,19 +3288,41 @@ enum FloatingPointClassification { extension FloatingPointClassification : Equatable { } + +/// A set of common requirements for Swift's floating point types. protocol FloatingPointType : Strideable { typealias _BitsType class func _fromBitPattern(bits: _BitsType) -> Self func _toBitPattern() -> _BitsType + + /// Create an instance initialized to `value`. init(_ value: UInt8) + + /// Create an instance initialized to `value`. init(_ value: Int8) + + /// Create an instance initialized to `value`. init(_ value: UInt16) + + /// Create an instance initialized to `value`. init(_ value: Int16) + + /// Create an instance initialized to `value`. init(_ value: UInt32) + + /// Create an instance initialized to `value`. init(_ value: Int32) + + /// Create an instance initialized to `value`. init(_ value: UInt64) + + /// Create an instance initialized to `value`. init(_ value: Int64) + + /// Create an instance initialized to `value`. init(_ value: UInt) + + /// Create an instance initialized to `value`. init(_ value: Int) /// The positive infinity. @@ -2265,87 +3333,155 @@ protocol FloatingPointType : Strideable { /// A quiet NaN. class var quietNaN: Self { get } + + /// @{ + /// IEEE 754-2008 Non-computational operations. + /// The IEEE 754 "class" of this type. var floatingPointClass: FloatingPointClassification { get } - /// Returns true if this number has a negative sign. + /// `true` iff `self` is negative var isSignMinus: Bool { get } - /// Returns true if this number is normal (not zero, subnormal, infinity, or + /// `true` iff `self` is normal (not zero, subnormal, infinity, or /// NaN). var isNormal: Bool { get } - /// Returns true if this number is zero, subnormal, or normal (not infinity + /// `true` iff `self` is zero, subnormal, or normal (not infinity /// or NaN). var isFinite: Bool { get } - /// Returns true if this number is +0.0 or -0.0. + /// `true` iff `self` is +0.0 or -0.0. var isZero: Bool { get } - /// Returns true if this number is subnormal. + /// `true` iff `self` is subnormal. var isSubnormal: Bool { get } - /// Returns true if this number is infinity. + /// `true` iff `self` is infinity. var isInfinite: Bool { get } - /// Returns true if this number is NaN. + /// `true` iff `self` is NaN. var isNaN: Bool { get } - /// Returns true if this number is a signaling NaN. + /// `true` iff `self` is a signaling NaN. var isSignaling: Bool { get } } + +/// Represents a discrete value in a series, where a value's +/// successor, if any, is reachable by applying the value's +/// `successor()` method. protocol ForwardIndexType : _ForwardIndexType { } + +/// A type-erased generator. +/// +/// The generator for `SequenceOf`. Forwards operations to an +/// arbitrary underlying generator with the same `Element` type, +/// hiding the specifics of the underlying generator type. +/// +/// See also: `SequenceOf`. struct GeneratorOf : GeneratorType, SequenceType { - init(_ next: () -> T?) - init(_ self_: G) + + /// Construct an instance whose `next()` method calls `nextElement`. + init(_ nextElement: () -> T?) + + /// Construct an instance whose `next()` method pulls its results + /// from `base`. + init(_ base: G) + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. + /// + /// Requires: `next()` has not been applied to a copy of `self` + /// since the copy was made, and no preceding call to `self.next()` + /// has returned `nil`. mutating func next() -> T? + + /// `GeneratorOf` is also a `SequenceType`, so it `generate`\ + /// 's a copy of itself func generate() -> GeneratorOf } + +/// A generator that produces one or fewer instances of `T`. struct GeneratorOfOne : GeneratorType, SequenceType { - init(_ elements: T?) + + /// Construct an instance that generates `element!`, or an empty + /// sequence if `element == nil`. + init(_ element: T?) + + /// `GeneratorOfOne` is also a `SequenceType`, so it `generate`\ + /// 's a copy of itself func generate() -> GeneratorOfOne + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. + /// + /// Requires: `next()` has not been applied to a copy of `self` + /// since the copy was made, and no preceding call to `self.next()` + /// has returned `nil`. mutating func next() -> T? } + +/// A sequence built around a generator of type `G`. +/// +/// Useful mostly to recover the ability to use `for`\ ...\ `in`, +/// given just a generator `g`:: +/// +/// for x in GeneratorSequence(g) { ... } struct GeneratorSequence : GeneratorType, SequenceType { + + /// Construct an instance whose generator is a copy of `base`. init(_ base: G) + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. + /// + /// Requires: `next()` has not been applied to a copy of `self` + /// since the copy was made, and no preceding call to `self.next()` + /// has returned `nil`. mutating func next() -> G.Element? + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> GeneratorSequence } -/// A `GeneratorType` is notionally a `SequenceType` that is consumed -/// when iterated. +/// Encapsulates iteration state and interface for iteration over a +/// *sequence*. /// -/// While it is safe to copy a `GeneratorType`, only one copy should be advanced -/// with `next()`. +/// **Note:** While it is safe to copy a *generator*, advancing one +/// copy may invalidate the others. /// -/// If an algorithm requires two `GeneratorType`\ s for the same -/// `SequenceType` to be advanced at the same time, and the specific -/// `SequenceType` type supports that, then those `GeneratorType` -/// objects should be obtained from `SequenceType` by two distinct -/// calls to `generate(). However in that case the algorithm should -/// probably require `CollectionType`, since `CollectionType` implies -/// multi-pass. +/// Any code that uses multiple generators (or `for`\ ...\ `in` loops) +/// over a single *sequence* should have static knowledge that the +/// specific *sequence* is multi-pass, either because its concrete +/// type is known or because it is constrained to `CollectionType`. +/// Also, the generators must be obtained by distinct calls to the +/// *sequence's* `generate()` method, rather than by copying. protocol GeneratorType { - /// The type of which `Self` is a generator. + /// The type of element generated by `self`. typealias Element - /// If all elements are exhausted, return `nil`. Otherwise, advance - /// to the next element and return it. + /// Advance to the next element and return it, or `nil` if no next + /// element exists. /// - /// Note: after `next()` on an arbitrary generator has returned - /// `nil`, subsequent calls to `next()` have unspecified behavior. - /// Specific implementations of this protocol are encouraged to - /// respond by calling `preconditionFailure("...")`. + /// Requires: `next()` has not been applied to a copy of `self` + /// since the copy was made, and no preceding call to `self.next()` + /// has returned `nil`. Specific implementations of this protocol + /// are encouraged to respond to violations of this requirement by + /// calling `preconditionFailure("...")`. mutating func next() -> Element? } struct HalfOpenInterval : IntervalType, Equatable, Printable, DebugPrintable, Reflectable { + + /// The type of the `Interval`\ 's endpoints typealias Bound = T /// Construct a copy of `x` @@ -2361,10 +3497,10 @@ struct HalfOpenInterval : IntervalType, Equatable, Printable, De /// The `Interval`\ 's upper bound. Invariant: `start` <= `end` var end: T { get } - /// The `Interval`\ 's printed representation + /// A textual representation of `self`. var description: String { get } - /// The `Interval`\ 's verbose printed representation + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } /// Returns `true` iff the `Interval` contains `x` @@ -2374,6 +3510,8 @@ struct HalfOpenInterval : IntervalType, Equatable, Printable, De /// result, even if it is empty, are always limited to the bounds of /// `self` func clamp(intervalToClamp: HalfOpenInterval) -> HalfOpenInterval + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } @@ -2383,24 +3521,31 @@ extension HalfOpenInterval { var isEmpty: Bool { get } } + +/// Instances of conforming types provide an integer `hashValue` and +/// can be used as `Dictionary` keys. protocol Hashable : Equatable { - /// Returns the hash value. The hash value is not guaranteed to be stable - /// across different invocations of the same program. Do not persist the hash - /// value across program runs. + /// The hash value. /// - /// The value of `hashValue` property must be consistent with the equality - /// comparison: if two values compare equal, they must have equal hash - /// values. + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } + +/// Management API for `HeapBufferStorage` struct HeapBuffer : Equatable { typealias Storage = HeapBufferStorage /// Create a `HeapBuffer` with `self.value = initializer` and /// `self._capacity() >= capacity`. init(_ storageClass: AnyClass, _ initializer: Value, _ capacity: Int) + + /// True if storage is non-\ `nil` var hasStorage: Bool { get } mutating func isUniquelyReferenced() -> Bool } @@ -2426,6 +3571,9 @@ struct HeapBuffer : Equatable { /// either in a derived class, or it can be in some manager object /// that owns the HeapBuffer. class HeapBufferStorage { + + /// The type used to actually manage instances of + /// `HeapBufferStorage` typealias Buffer = HeapBuffer deinit } @@ -2440,17 +3588,30 @@ class HeapBufferStorage { enum ImplicitlyUnwrappedOptional : Reflectable, NilLiteralConvertible { case None case Some(T) + + /// Construct a `nil` instance. init() + + /// Construct a non-\ `nil` instance that stores `some`. init(_ some: T) + + /// Construct an instance from an explicitly unwrapped optional + /// (`T?`). init(_ v: T?) - static func convertFromNilLiteral() -> T! - /// Haskell's fmap, which was mis-named + /// Create an instance initialized with `nil`. + init(nilLiteral: ()) + + /// If `self == nil`, returns `nil`. Otherwise, returns `f(self!)`. func map(f: (T) -> U) -> U! + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension ImplicitlyUnwrappedOptional : Printable { + + /// A textual representation of `self`. var description: String { get } } @@ -2458,18 +3619,51 @@ extension ImplicitlyUnwrappedOptional : _ObjectiveCBridgeable { } -/// A stream type that could serve for a CollectionType given that -/// it already had an Index. +/// A *generator* for an arbitrary *collection*. Provided `C` +/// conforms to the other requirements of *CollectionType*, +/// `IndexingGenerator` can be used as the result of `C`\ 's +/// `generate()` method. For example: +/// +/// .. parsed-literal:: +/// +/// struct MyCollection : CollectionType { +/// struct Index : ForwardIndexType { *implementation hidden* } +/// subscript(i: Index) -> MyElement { *implementation hidden* } +/// func generate() -> **IndexingGenerator** { +/// return IndexingGenerator(self) +/// } +/// } struct IndexingGenerator : GeneratorType, SequenceType { + + /// Create a *generator* over the given collection init(_ seq: C) + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> IndexingGenerator + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. + /// + /// Requires: no preceding call to `self.next()` has returned `nil`. mutating func next() -> C._Element? } + +/// A 64-bit signed integer value +/// type. struct Int : SignedIntegerType { var value: Builtin.Word + + /// A type that can represent the number of steps between pairs of + /// values. + typealias Distance = Int + + /// Create an instance initialized to zero. init() - init(_ v: Builtin.Word) + + /// Create an instance initialized to `value`. init(_ value: Int) /// Creates an integer from its big-endian representation, changing the @@ -2479,9 +3673,10 @@ struct Int : SignedIntegerType { /// Creates an integer from its little-endian representation, changing the /// byte order if necessary. init(littleEndian value: Int) - static func convertFromIntegerLiteral(value: Int) -> Int - typealias ArrayBound = Int - var arrayBoundValue: Int { get } + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: Int) /// Returns the big-endian representation of the integer, changing the /// byte order if necessary. @@ -2498,34 +3693,81 @@ struct Int : SignedIntegerType { } extension Int : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension Int : Printable { + + /// A textual representation of `self`. var description: String { get } } extension Int : RandomAccessIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> Int + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> Int - func distanceTo(other: Int) -> Int - func advancedBy(amount: Int) -> Int + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). + func distanceTo(other: Int) -> Distance + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) + func advancedBy(amount: Distance) -> Int } extension Int { + + /// Add `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func addWithOverflow(lhs: Int, _ rhs: Int) -> (Int, overflow: Bool) + + /// Subtract `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func subtractWithOverflow(lhs: Int, _ rhs: Int) -> (Int, overflow: Bool) + + /// Multiply `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func multiplyWithOverflow(lhs: Int, _ rhs: Int) -> (Int, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// a result and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func divideWithOverflow(lhs: Int, _ rhs: Int) -> (Int, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// the remainder and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func remainderWithOverflow(lhs: Int, _ rhs: Int) -> (Int, overflow: Bool) + + /// Represent this number using Swift's widest native signed + /// integer type. func toIntMax() -> IntMax - static func from(x: IntMax) -> Int } extension Int : SignedNumberType { @@ -2563,27 +3805,50 @@ extension Int { } extension Int : BitwiseOperationsType { + + /// The empty bitset of type Int. static var allZeros: Int { get } } extension Int { - init(_ v: Float) - init(_ v: Double) - init(_ v: Float80) + + /// Construct an instance that approximates `other`. + init(_ other: Float) + + /// Construct an instance that approximates `other`. + init(_ other: Double) + + /// Construct an instance that approximates `other`. + init(_ other: Float80) } extension Int : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension Int : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } + +/// A 16-bit signed integer value +/// type. struct Int16 : SignedIntegerType { var value: Builtin.Int16 + + /// A type that can represent the number of steps between pairs of + /// values. + typealias Distance = Int + + /// Create an instance initialized to zero. init() - init(_ v: Builtin.Int16) + + /// Create an instance initialized to `value`. init(_ value: Int16) /// Creates an integer from its big-endian representation, changing the @@ -2593,9 +3858,10 @@ struct Int16 : SignedIntegerType { /// Creates an integer from its little-endian representation, changing the /// byte order if necessary. init(littleEndian value: Int16) - static func convertFromIntegerLiteral(value: Int16) -> Int16 - typealias ArrayBound = Int16 - var arrayBoundValue: Int16 { get } + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: Int16) /// Returns the big-endian representation of the integer, changing the /// byte order if necessary. @@ -2612,34 +3878,81 @@ struct Int16 : SignedIntegerType { } extension Int16 : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension Int16 : Printable { + + /// A textual representation of `self`. var description: String { get } } extension Int16 : RandomAccessIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> Int16 + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> Int16 - func distanceTo(other: Int16) -> Int - func advancedBy(amount: Int) -> Int16 + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). + func distanceTo(other: Int16) -> Distance + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) + func advancedBy(amount: Distance) -> Int16 } extension Int16 { + + /// Add `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func addWithOverflow(lhs: Int16, _ rhs: Int16) -> (Int16, overflow: Bool) + + /// Subtract `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func subtractWithOverflow(lhs: Int16, _ rhs: Int16) -> (Int16, overflow: Bool) + + /// Multiply `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func multiplyWithOverflow(lhs: Int16, _ rhs: Int16) -> (Int16, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// a result and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func divideWithOverflow(lhs: Int16, _ rhs: Int16) -> (Int16, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// the remainder and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func remainderWithOverflow(lhs: Int16, _ rhs: Int16) -> (Int16, overflow: Bool) + + /// Represent this number using Swift's widest native signed + /// integer type. func toIntMax() -> IntMax - static func from(x: IntMax) -> Int16 } extension Int16 : SignedNumberType { @@ -2701,27 +4014,50 @@ extension Int16 { } extension Int16 : BitwiseOperationsType { + + /// The empty bitset of type Int16. static var allZeros: Int16 { get } } extension Int16 { - init(_ v: Float) - init(_ v: Double) - init(_ v: Float80) + + /// Construct an instance that approximates `other`. + init(_ other: Float) + + /// Construct an instance that approximates `other`. + init(_ other: Double) + + /// Construct an instance that approximates `other`. + init(_ other: Float80) } extension Int16 : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension Int16 : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } + +/// A 32-bit signed integer value +/// type. struct Int32 : SignedIntegerType { var value: Builtin.Int32 + + /// A type that can represent the number of steps between pairs of + /// values. + typealias Distance = Int + + /// Create an instance initialized to zero. init() - init(_ v: Builtin.Int32) + + /// Create an instance initialized to `value`. init(_ value: Int32) /// Creates an integer from its big-endian representation, changing the @@ -2731,9 +4067,10 @@ struct Int32 : SignedIntegerType { /// Creates an integer from its little-endian representation, changing the /// byte order if necessary. init(littleEndian value: Int32) - static func convertFromIntegerLiteral(value: Int32) -> Int32 - typealias ArrayBound = Int32 - var arrayBoundValue: Int32 { get } + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: Int32) /// Returns the big-endian representation of the integer, changing the /// byte order if necessary. @@ -2750,34 +4087,81 @@ struct Int32 : SignedIntegerType { } extension Int32 : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension Int32 : Printable { + + /// A textual representation of `self`. var description: String { get } } extension Int32 : RandomAccessIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> Int32 + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> Int32 - func distanceTo(other: Int32) -> Int - func advancedBy(amount: Int) -> Int32 + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). + func distanceTo(other: Int32) -> Distance + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) + func advancedBy(amount: Distance) -> Int32 } extension Int32 { + + /// Add `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func addWithOverflow(lhs: Int32, _ rhs: Int32) -> (Int32, overflow: Bool) + + /// Subtract `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func subtractWithOverflow(lhs: Int32, _ rhs: Int32) -> (Int32, overflow: Bool) + + /// Multiply `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func multiplyWithOverflow(lhs: Int32, _ rhs: Int32) -> (Int32, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// a result and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func divideWithOverflow(lhs: Int32, _ rhs: Int32) -> (Int32, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// the remainder and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func remainderWithOverflow(lhs: Int32, _ rhs: Int32) -> (Int32, overflow: Bool) + + /// Represent this number using Swift's widest native signed + /// integer type. func toIntMax() -> IntMax - static func from(x: IntMax) -> Int32 } extension Int32 : SignedNumberType { @@ -2827,27 +4211,50 @@ extension Int32 { } extension Int32 : BitwiseOperationsType { + + /// The empty bitset of type Int32. static var allZeros: Int32 { get } } extension Int32 { - init(_ v: Float) - init(_ v: Double) - init(_ v: Float80) + + /// Construct an instance that approximates `other`. + init(_ other: Float) + + /// Construct an instance that approximates `other`. + init(_ other: Double) + + /// Construct an instance that approximates `other`. + init(_ other: Float80) } extension Int32 : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension Int32 : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } + +/// A 64-bit signed integer value +/// type. struct Int64 : SignedIntegerType { var value: Builtin.Int64 + + /// A type that can represent the number of steps between pairs of + /// values. + typealias Distance = Int + + /// Create an instance initialized to zero. init() - init(_ v: Builtin.Int64) + + /// Create an instance initialized to `value`. init(_ value: Int64) /// Creates an integer from its big-endian representation, changing the @@ -2857,9 +4264,10 @@ struct Int64 : SignedIntegerType { /// Creates an integer from its little-endian representation, changing the /// byte order if necessary. init(littleEndian value: Int64) - static func convertFromIntegerLiteral(value: Int64) -> Int64 - typealias ArrayBound = Int64 - var arrayBoundValue: Int64 { get } + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: Int64) /// Returns the big-endian representation of the integer, changing the /// byte order if necessary. @@ -2876,34 +4284,81 @@ struct Int64 : SignedIntegerType { } extension Int64 : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension Int64 : Printable { + + /// A textual representation of `self`. var description: String { get } } extension Int64 : RandomAccessIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> Int64 + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> Int64 - func distanceTo(other: Int64) -> Int - func advancedBy(amount: Int) -> Int64 + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). + func distanceTo(other: Int64) -> Distance + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) + func advancedBy(amount: Distance) -> Int64 } extension Int64 { + + /// Add `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func addWithOverflow(lhs: Int64, _ rhs: Int64) -> (Int64, overflow: Bool) + + /// Subtract `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func subtractWithOverflow(lhs: Int64, _ rhs: Int64) -> (Int64, overflow: Bool) + + /// Multiply `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func multiplyWithOverflow(lhs: Int64, _ rhs: Int64) -> (Int64, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// a result and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func divideWithOverflow(lhs: Int64, _ rhs: Int64) -> (Int64, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// the remainder and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func remainderWithOverflow(lhs: Int64, _ rhs: Int64) -> (Int64, overflow: Bool) + + /// Represent this number using Swift's widest native signed + /// integer type. func toIntMax() -> IntMax - static func from(x: IntMax) -> Int64 } extension Int64 : SignedNumberType { @@ -2929,64 +4384,135 @@ extension Int64 { } extension Int64 : BitwiseOperationsType { + + /// The empty bitset of type Int64. static var allZeros: Int64 { get } } extension Int64 { - init(_ v: Float) - init(_ v: Double) - init(_ v: Float80) + + /// Construct an instance that approximates `other`. + init(_ other: Float) + + /// Construct an instance that approximates `other`. + init(_ other: Double) + + /// Construct an instance that approximates `other`. + init(_ other: Float80) } extension Int64 : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension Int64 : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } + +/// A 8-bit signed integer value +/// type. struct Int8 : SignedIntegerType { var value: Builtin.Int8 + + /// A type that can represent the number of steps between pairs of + /// values. + typealias Distance = Int + + /// Create an instance initialized to zero. init() - init(_ v: Builtin.Int8) + + /// Create an instance initialized to `value`. init(_ value: Int8) - static func convertFromIntegerLiteral(value: Int8) -> Int8 - typealias ArrayBound = Int8 - var arrayBoundValue: Int8 { get } + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: Int8) static var max: Int8 { get } static var min: Int8 { get } } extension Int8 : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension Int8 : Printable { + + /// A textual representation of `self`. var description: String { get } } extension Int8 : RandomAccessIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> Int8 + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> Int8 - func distanceTo(other: Int8) -> Int - func advancedBy(amount: Int) -> Int8 + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). + func distanceTo(other: Int8) -> Distance + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) + func advancedBy(amount: Distance) -> Int8 } extension Int8 { + + /// Add `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func addWithOverflow(lhs: Int8, _ rhs: Int8) -> (Int8, overflow: Bool) + + /// Subtract `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func subtractWithOverflow(lhs: Int8, _ rhs: Int8) -> (Int8, overflow: Bool) + + /// Multiply `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func multiplyWithOverflow(lhs: Int8, _ rhs: Int8) -> (Int8, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// a result and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func divideWithOverflow(lhs: Int8, _ rhs: Int8) -> (Int8, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// the remainder and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func remainderWithOverflow(lhs: Int8, _ rhs: Int8) -> (Int8, overflow: Bool) + + /// Represent this number using Swift's widest native signed + /// integer type. func toIntMax() -> IntMax - static func from(x: IntMax) -> Int8 } extension Int8 : SignedNumberType { @@ -3060,41 +4586,84 @@ extension Int8 { } extension Int8 : BitwiseOperationsType { + + /// The empty bitset of type Int8. static var allZeros: Int8 { get } } extension Int8 { - init(_ v: Float) - init(_ v: Double) - init(_ v: Float80) + + /// Construct an instance that approximates `other`. + init(_ other: Float) + + /// Construct an instance that approximates `other`. + init(_ other: Double) + + /// Construct an instance that approximates `other`. + init(_ other: Float80) } extension Int8 : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension Int8 : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } + +/// The largest native signed integer type typealias IntMax = Int64 + +/// The common requirements for types that support integer arithmetic. protocol IntegerArithmeticType : _IntegerArithmeticType, Comparable { + + /// Add `lhs` and `rhs`, returning a result and trapping in case of + /// arithmetic overflow (except in -Ounchecked builds). func +(lhs: Self, rhs: Self) -> Self + + /// Subtract `lhs` and `rhs`, returning a result and trapping in case of + /// arithmetic overflow (except in -Ounchecked builds). func -(lhs: Self, rhs: Self) -> Self + + /// Multiply `lhs` and `rhs`, returning a result and trapping in case of + /// arithmetic overflow (except in -Ounchecked builds). func *(lhs: Self, rhs: Self) -> Self + + /// Divide `lhs` and `rhs`, returning a result and trapping in case of + /// arithmetic overflow (except in -Ounchecked builds). func /(lhs: Self, rhs: Self) -> Self + + /// Divide `lhs` and `rhs`, returning the remainder and trapping in case of + /// arithmetic overflow (except in -Ounchecked builds). func %(lhs: Self, rhs: Self) -> Self + + /// Explicitly convert to `IntMax`, trapping on overflow (except in + /// -Ounchecked builds). func toIntMax() -> IntMax } + +/// Conforming types can be initialized with integer literals protocol IntegerLiteralConvertible { typealias IntegerLiteralType - class func convertFromIntegerLiteral(value: IntegerLiteralType) -> Self + + /// Create an instance initialized to `value`. + init(integerLiteral value: IntegerLiteralType) } + +/// The default type for an otherwise-unconstrained integer literal typealias IntegerLiteralType = Int + +/// A set of common requirements for Swift's integer types. protocol IntegerType : _IntegerType, RandomAccessIndexType { } @@ -3112,7 +4681,7 @@ protocol IntervalType { /// if it is empty, are always within the bounds of `self` func clamp(intervalToClamp: Self) -> Self - /// True iff the `Interval` is empty + /// True iff `self` is empty var isEmpty: Bool { get } /// The `Interval`\ 's lower bound. Invariant: `start` <= `end` @@ -3123,11 +4692,29 @@ protocol IntervalType { } -/// Augments `S` with lazy versions of various collection algorithms. +/// A collection that forwards its implementation to an underlying +/// collection instance while exposing lazy computations as methods. struct LazyBidirectionalCollection : CollectionType { + + /// Construct an instance with `base` as its underlying collection + /// instance. init(_ base: S) + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> S.Generator + + /// The position of the first element in a non-empty collection. + /// + /// Identical to `endIndex` in an empty collection. var startIndex: S.Index { get } + + /// The collection's "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: S.Index { get } /// True if and only if the collection is empty @@ -3138,7 +4725,7 @@ struct LazyBidirectionalCollection S.Generator.Element { get } + subscript (position: S.Index) -> S.Generator.Element { get } /// an Array, created on-demand, containing the elements of this /// lazy CollectionType. @@ -3169,11 +4756,29 @@ extension LazyBidirectionalCollection { } -/// Augments `S` with lazy versions of various collection algorithms. +/// A collection that forwards its implementation to an underlying +/// collection instance while exposing lazy computations as methods. struct LazyForwardCollection : CollectionType { + + /// Construct an instance with `base` as its underlying collection + /// instance. init(_ base: S) + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> S.Generator + + /// The position of the first element in a non-empty collection. + /// + /// Identical to `endIndex` in an empty collection. var startIndex: S.Index { get } + + /// The collection's "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: S.Index { get } /// True if and only if the collection is empty @@ -3181,7 +4786,7 @@ struct LazyForwardCollection S.Generator.Element { get } + subscript (position: S.Index) -> S.Generator.Element { get } /// an Array, created on-demand, containing the elements of this /// lazy CollectionType. @@ -3204,11 +4809,29 @@ extension LazyForwardCollection { } -/// Augments `S` with lazy versions of various collection algorithms. +/// A collection that forwards its implementation to an underlying +/// collection instance while exposing lazy computations as methods. struct LazyRandomAccessCollection : CollectionType { + + /// Construct an instance with `base` as its underlying collection + /// instance. init(_ base: S) + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> S.Generator + + /// The position of the first element in a non-empty collection. + /// + /// Identical to `endIndex` in an empty collection. var startIndex: S.Index { get } + + /// The collection's "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: S.Index { get } /// True if and only if the collection is empty @@ -3219,7 +4842,7 @@ struct LazyRandomAccessCollection S.Generator.Element { get } + subscript (position: S.Index) -> S.Generator.Element { get } /// an Array, created on-demand, containing the elements of this /// lazy CollectionType. @@ -3250,9 +4873,17 @@ extension LazyRandomAccessCollection { } -/// Augments `S` with lazy versions of various sequence algorithms. +/// A sequence that forwards its implementation to an underlying +/// sequence instance while exposing lazy computations as methods. struct LazySequence : SequenceType { + + /// Construct an instance with `base` as its underlying sequence + /// instance. init(_ base: S) + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> S.Generator /// an Array, created on-demand, containing the elements of this @@ -3281,9 +4912,23 @@ extension LazySequence { /// These elements are computed lazily, each time they're read, by /// calling the transform function on a base element. struct MapCollectionView : CollectionType { + + /// The position of the first element in a non-empty collection. + /// + /// Identical to `endIndex` in an empty collection. var startIndex: Base.Index { get } + + /// The collection's "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: Base.Index { get } - subscript (index: Base.Index) -> T { get } + subscript (position: Base.Index) -> T { get } + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> MapSequenceGenerator } @@ -3292,7 +4937,17 @@ struct MapCollectionView : CollectionType { /// Produces each element by passing the output of the `Base` /// `GeneratorType` through a transform function returning `T` struct MapSequenceGenerator : GeneratorType, SequenceType { + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. + /// + /// Requires: `next()` has not been applied to a copy of `self` + /// since the copy was made, and no preceding call to `self.next()` + /// has returned `nil`. mutating func next() -> T? + + /// `MapSequenceGenerator` is also a `SequenceType`, so it + /// `generate`\ 's a copy of itself func generate() -> MapSequenceGenerator } @@ -3302,6 +4957,10 @@ struct MapSequenceGenerator : GeneratorType, SequenceTy /// These elements are computed lazily, each time they're read, by /// calling the transform function on a base element. struct MapSequenceView : SequenceType { + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> MapSequenceGenerator } @@ -3322,47 +4981,71 @@ enum MirrorDisposition { } -/// A protocol that provides a reflection interface to an underlying value. +/// The type returned by `reflect(x)`; supplies an API for runtime +/// reflection on `x` protocol MirrorType { - /// Copy the value out as an Any. + /// The instance being reflected var value: Any { get } - /// Get the type of the value. + /// Identical to `value.dynamicType` var valueType: Any.Type { get } - /// Get the unique identifier for this value, if it has one. - /// Always returns Some value for class instances, and always returns None - /// for value types. + /// A unique identifier for `value` if it is a class instance; `nil` + /// otherwise. var objectIdentifier: ObjectIdentifier? { get } - /// Get the number of logical children this value has. + /// The count of `value`\ 's logical children var count: Int { get } subscript (i: Int) -> (String, MirrorType) { get } - /// Get a string description of this value. + /// A string description of `value`. var summary: String { get } - /// Get a rich representation of this value for the IDE, if it has one. + /// A rich representation of `value` for an IDE, or `nil` if none is supplied. var quickLookObject: QuickLookObject? { get } - /// Get the disposition of the value. + /// How `value` should be presented in an IDE. var disposition: MirrorDisposition { get } } + +/// A *collection* that supports subscript assignment. +/// +/// For any instance `a` of a type conforming to +/// `MutableCollectionType`, :: +/// +/// a[i] = x +/// let y = a[i] +/// +/// is equivalent to :: +/// +/// a[i] = x +/// let y = x +/// protocol MutableCollectionType : CollectionType { - subscript (i: Self.Index) -> Self.Generator.Element { get set } + subscript (position: Self.Index) -> Self.Generator.Element { get set } } + +/// A *collection* with mutable slices. +/// +/// For example, +/// +/// .. parsed-literal: +/// +/// x[i..) -> Self.SubSlice { get set } } -/// Conforming to this protocol allows a type to be usable with the 'nil' -/// literal. +/// Conforming types can be initialized with `nil`. protocol NilLiteralConvertible { - class func convertFromNilLiteral() -> Self + + /// Create an instance initialized with `nil`. + init(nilLiteral: ()) } @@ -3372,8 +5055,22 @@ protocol NilLiteralConvertible { /// In Swift, only class instances have unique identities. There is no notion /// of identity for structs, enums, or tuples. struct ObjectIdentifier : Hashable { + + /// Convert to a `UInt` that captures the full value of `self`. + /// + /// Axiom: `a.uintValue() == b.uintValue()` iff `a == b` func uintValue() -> UInt + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } + + /// Construct an instance that uniquely identifies `x`. init(_ x: AnyObject) } @@ -3383,41 +5080,81 @@ struct OnHeap { enum Optional : Reflectable, NilLiteralConvertible { case None case Some(T) + + /// Construct a `nil` instance. init() + + /// Construct a non-\ `nil` instance that stores `some`. init(_ some: T) - /// Haskell's fmap, which was mis-named + /// If `self == nil`, returns `nil`. Otherwise, returns `f(self!)`. func map(f: (T) -> U) -> U? + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType - static func convertFromNilLiteral() -> T? + + /// Create an instance initialized with `nil`. + init(nilLiteral: ()) } extension Optional : DebugPrintable { + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } -/// Models an object into into which we can stream text. +/// A target of text streaming operations. protocol OutputStreamType { + + /// Append the given `string` to this stream. mutating func write(string: String) } + +/// A *generator* that adapts a *collection* `C` and any *sequence* of +/// its `Index` type to present the collection's elements in a +/// permuted order. struct PermutationGenerator : GeneratorType, SequenceType { + + /// The type of element returned by `next()`. typealias Element = C.Generator.Element + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. + /// + /// Requires: no preceding call to `self.next()` has returned `nil`. mutating func next() -> Element? + + /// A type whose instances can produce the elements of this + /// sequence, in order. typealias Generator = PermutationGenerator + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> PermutationGenerator - init(elements seq: C, indices: Indices) + + /// Construct a *generator* over a permutation of `elements` given + /// by `indices`. + /// + /// Requires: `elements[i]` is valid for every `i` in `indices`. + init(elements: C, indices: Indices) } -/// This protocol should be adopted by types that wish to customize their -/// textual representation. This textual representation is used when objects -/// are written to an `OutputStreamType`. +/// A type with a customized textual representation. +/// +/// This textual representation is used when objects are written to an +/// *output stream*, for example, by `print` and `println`. protocol Printable { + + /// A textual representation of `self`. var description: String { get } } + +/// An instance that exposes API for interaction with processes let Process: _Process @@ -3450,6 +5187,9 @@ enum QuickLookObject { case URL(String) } + +/// An *index* that can be offset by an arbitrary number of positions, +/// and can measure the distance to any reachable value, in O(1). protocol RandomAccessIndexType : BidirectionalIndexType, _RandomAccessIndexType { } @@ -3457,33 +5197,111 @@ protocol RandomAccessIndexType : BidirectionalIndexType, _RandomAccessIndexType /// The lazy `CollectionType` returned by `reverse(c)` where `c` is a /// `CollectionType` with an `Index` conforming to `RandomAccessIndexType` struct RandomAccessReverseView : CollectionType { + + /// A type that represents a valid position in the collection. + /// + /// Valid indices consist of the position of every element and a + /// "past the end" position that's not valid for use as a subscript. typealias Index = ReverseRandomAccessIndex + + /// A type whose instances can produce the elements of this + /// sequence, in order. typealias Generator = IndexingGenerator> + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> IndexingGenerator> + + /// The position of the first element in a non-empty collection. + /// + /// Identical to `endIndex` in an empty collection. var startIndex: Index { get } + + /// The collection's "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: Index { get } - subscript (i: Index) -> T.Generator.Element { get } + subscript (position: Index) -> T.Generator.Element { get } } + +/// A collection of consecutive discrete index values. +/// +/// :param: `T` is both the element type and the index type of the +/// collection. +/// +/// Like other collections, a range containing one element has an +/// `endIndex` that is the successor of its `startIndex`; and an empty +/// range has `startIndex == endIndex`. +/// +/// Axiom: for any `Range` `r`, `r[i] == i`. +/// +/// Therefore, if `T` has a maximal value, it can serve as an +/// `endIndex`, but can never be contained in a `Range`. +/// +/// It also follows from the axiom above that `(-99..<100)[0] == 0`. +/// To prevent confusion (because some expect the result to be `-99`), +/// in a context where `T` is known to be an integer type, +/// subscripting with `T` is a compile-time error:: +/// +/// // error: could not find an overload for 'subscript'... +/// println( Range(start:-99, end:100)[0] ) +/// +/// However, subscripting that range still works in a generic context:: +/// +/// func brackets(x: Range, i: T) -> T { +/// return x[i] // Just forward to subscript +/// } +/// println(brackets(Range(start:-99, end:100), 0)) // prints 0 struct Range : Equatable, CollectionType, Printable, DebugPrintable { /// Construct a copy of `x` init(_ x: Range) + + /// Construct a range with `startIndex == start` and `endIndex == + /// end`. init(start: T, end: T) + + /// `true` iff the range is empty, i.e. `startIndex == endIndex` var isEmpty: Bool { get } + + /// A type that represents a valid position in the collection. + /// + /// Valid indices consist of the position of every element and a + /// "past the end" position that's not valid for use as a subscript. typealias Index = T typealias Slice = Range - subscript (i: T) -> T { get } + subscript (position: T) -> T { get } subscript (_: T._DisabledRangeIndex) -> T { get } + + /// A type whose instances can produce the elements of this + /// sequence, in order. typealias Generator = RangeGenerator + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> RangeGenerator + + /// The range's lower bound + /// + /// Identical to `endIndex` in an empty range. var startIndex: T + + /// The range's upper bound + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: T - /// The `Range`\ 's printed representation + /// A textual representation of `self`. var description: String { get } - /// The `Range`\ 's verbose printed representation + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } @@ -3495,29 +5313,112 @@ extension Range { } extension Range : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } + +/// A generator over the elements of `Range` struct RangeGenerator : GeneratorType, SequenceType { + + /// The type of element returned by `next()`. typealias Element = T + + /// Construct an instance that traverses the elements of `bounds` init(_ bounds: Range) + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. mutating func next() -> T? + + /// A type whose instances can produce the elements of this + /// sequence, in order. typealias Generator = RangeGenerator + + /// `RangeGenerator` is also a `SequenceType`, so it + /// `generate`\ 's a copy of itself func generate() -> RangeGenerator + + /// The lower bound of the remaining range. var startIndex: T + + /// The upper bound of the remaining range; not included in the + /// generated sequence. var endIndex: T } + +/// A *collection* that supports replacement of an arbitrary subRange +/// of elements with the elements of another collection. protocol RangeReplaceableCollectionType : ExtensibleCollectionType { - /// Replace the given `subRange` of elements with `newValues`. - /// Complexity: O(\ `countElements(subRange)`\ ) if `subRange.endIndex - /// == self.endIndex` and `isEmpty(newValues)`\ , O(N) otherwise. - mutating func replaceRange(subRange: Range, with newValues: C) + /// Replace the given `subRange` of elements with `newElements`. + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `countElements(subRange)`\ ) if + /// `subRange.endIndex == self.endIndex` and `isEmpty(newElements)`\ , + /// O(\ `countElements(self)`\ + \`countElements(newElements)`\ ) otherwise. + mutating func replaceRange(subRange: Range, with newElements: C) + + /// Insert `newElement` at index `i`. + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `countElements(self)`\ ). + /// + /// Can be implemented as:: + /// + /// Swift.insert(&self, newElement, atIndex: i) mutating func insert(newElement: Self.Generator.Element, atIndex i: Self.Index) - mutating func splice(newValues: S, atIndex i: Self.Index) + + /// Insert `newElements` at index `i` + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `countElements(self) + countElements(newElements)`\ ). + /// + /// Can be implemented as:: + /// + /// Swift.splice(&self, newElements, atIndex: i) + mutating func splice(newElements: S, atIndex i: Self.Index) + + /// Remove the element at index `i` + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `countElements(self)`\ ). + /// + /// Can be implemented as:: + /// + /// Swift.removeAtIndex(&self, i) mutating func removeAtIndex(i: Self.Index) -> Self.Generator.Element + + /// Remove the indicated `subRange` of elements + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `countElements(self)`\ ). + /// + /// Can be implemented as:: + /// + /// Swift.removeRange(&self, subRange) mutating func removeRange(subRange: Range) + + /// Remove all elements + /// + /// Invalidates all indices with respect to `self`. + /// + /// :param: `keepCapacity`, if `true`, is a non-binding request to + /// avoid releasing storage, which can be a useful optimization + /// when `self` is going to be grown again. + /// + /// Complexity: O(\ `countElements(self)`\ ). + /// + /// Can be implemented as:: + /// + /// Swift.removeAll(&self, keepCapacity: keepCapacity) mutating func removeAll(#keepCapacity: Bool) } @@ -3528,31 +5429,74 @@ protocol RangeReplaceableCollectionType : ExtensibleCollectionType { struct RawByte { } + +/// Protocol for `NS_OPTIONS` imported from Objective-C protocol RawOptionSetType : _RawOptionSetType, BitwiseOperationsType, NilLiteralConvertible { } + +/// A type that can be converted to an associated "raw" type, then +/// converted back to produce an instance equivalent to the original. protocol RawRepresentable { + + /// The "raw" type that can be used to represent all values of `Self`. + /// + /// Every distinct value of `self` has a corresponding unique + /// value of `RawValue`, but `RawValue` may have representations + /// that do not correspond to an value of `Self`. typealias RawValue + + /// Convert from a value of `RawValue`, yielding `nil` iff + /// `rawValue` does not correspond to a value of `Self`. init?(rawValue: RawValue) + + /// The corresponding value of the "raw" type. + /// + /// `Self(rawValue: self.rawValue)!` is equivalent to `self`. var rawValue: RawValue { get } } -/// A protocol that produces a reflection interface for a value. +/// Customizes the result of `reflect(x)`, where `x` is a conforming +/// type. protocol Reflectable { - /// Get the mirror that reflects this object. + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } + +/// A collection whose elements are all identical `T`\ s. struct Repeat : CollectionType { + + /// A type that represents a valid position in the collection. + /// + /// Valid indices consist of the position of every element and a + /// "past the end" position that's not valid for use as a subscript. typealias Index = Int + + /// Construct an instance that contains `count` elements having the + /// value `repeatedValue`. init(count: Int, repeatedValue: T) + + /// Always zero, which is the index of the first element in a + /// non-empty instance. var startIndex: Index { get } + + /// Always equal to `count`, which is one greater than the index of + /// the last element in a non-empty instance. var endIndex: Index { get } + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> IndexingGenerator> - subscript (i: Int) -> T { get } + subscript (position: Int) -> T { get } + + /// The number of elements in this collection. var count: Int + + /// The value of every element in this collection. let repeatedValue: T } @@ -3560,7 +5504,15 @@ struct Repeat : CollectionType { /// A wrapper for a `BidirectionalIndexType` that reverses its /// direction of traversal struct ReverseBidirectionalIndex : BidirectionalIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> ReverseBidirectionalIndex + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> ReverseBidirectionalIndex } @@ -3568,47 +5520,169 @@ struct ReverseBidirectionalIndex : BidirectionalInde /// A wrapper for a `RandomAccessIndexType` that reverses its /// direction of traversal struct ReverseRandomAccessIndex : RandomAccessIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> ReverseRandomAccessIndex + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> ReverseRandomAccessIndex + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). func distanceTo(other: ReverseRandomAccessIndex) -> I.Distance + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) func advancedBy(amount: I.Distance) -> ReverseRandomAccessIndex } + +/// A type-erased sequence. +/// +/// Forwards operations to an arbitrary underlying sequence with the +/// same `Element` type, hiding the specifics of the underlying +/// sequence type. +/// +/// See also: `GeneratorOf`. struct SequenceOf : SequenceType { - init(_ generate: () -> G) - init(_ self_: S) + + /// Construct an instance whose `generate()` method forwards to + /// `makeUnderlyingGenerator` + init(_ makeUnderlyingGenerator: () -> G) + + /// Construct an instance whose `generate()` method forwards to + /// that of `base`. + init(_ base: S) + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> GeneratorOf } + +/// A type that can be iterated with a `for`\ ...\ `in` loop. +/// +/// `SequenceType` makes no requirement on conforming types regarding +/// whether they will be destructively "consumed" by iteration. To +/// ensure non-destructive iteration, constrain your *sequence* to +/// `CollectionType`. protocol SequenceType : _Sequence_Type { + + /// A type that provides the *sequence*\ 's iteration interface and + /// encapsulates its iteration state. typealias Generator : GeneratorType + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> Generator } + +/// A set of common requirements for Swift's signed integer types. protocol SignedIntegerType : _SignedIntegerType, IntegerType { } + +/// Instances of conforming types can be subtracted, arithmetically +/// negated, and initialized from `0`. +/// +/// Axioms: +/// +/// - `x - 0 == x` +/// - `-x == 0 - x` +/// - `-(-x) == x` protocol SignedNumberType : _SignedNumberType { + + /// Return the result of negating `x`. prefix func -(x: Self) -> Self } + +/// A type-erased sink. +/// +/// Forwards operations to an arbitrary underlying sink with the same +/// `Element` type, hiding the specifics of the underlying sink type. struct SinkOf : SinkType { - init(_ put: (T) -> ()) + + /// Construct an instance whose `put(x)` calls `putElement(x)` + init(_ putElement: (T) -> ()) + + /// Construct an instance whose `put(x)` calls `base.put(x)` init(_ base: S) + + /// Write `x` to this sink. func put(x: T) } + +/// Instances of conforming types are effectively functions with the +/// signature `(Element) -> Void`. +/// +/// Useful mainly when the optimizer's ability to specialize generics +/// outstrips its ability to specialize ordinary closures. For +/// example, you may find that instead of:: +/// +/// func f(g: (X)->Void) { ... g(a) ...} +/// +/// the following generates better code:: +/// +/// func f(g: T) { ... g.put(a) ...} protocol SinkType { + + /// The type of element to be written to this sink. typealias Element + + /// Write `x` to this sink. mutating func put(x: Element) } + +/// The `Array`-like type that represents a sub-sequence of any +/// `Array`, `ContiguousArray`, or other `Slice`. +/// +/// `Slice` always uses contiguous storage and does not bridge to +/// Objective-C. +/// +/// .. Warning:: Long-term storage of `Slice` instances is discouraged +/// +/// Because a `Slice` presents a *view* onto the storage of some +/// larger array even after the original array's lifetime ends, +/// storing the slice may prolong the lifetime of elements that are +/// no longer accessible, which can manifest as apparent memory and +/// object leakage. To prevent this effect, use `Slice` only for +/// transient computation. struct Slice : MutableCollectionType, Sliceable { + + /// The type of element stored by this `Slice` typealias Element = T + + /// Always zero, which is the index of the first element when non-empty. var startIndex: Int { get } + + /// A "past-the-end" element index; the successor of the last valid + /// subscript argument. var endIndex: Int { get } subscript (index: Int) -> T + + /// Return a *generator* over the elements. + /// + /// Complexity: O(1) func generate() -> IndexingGenerator> + + /// A type that can represent a sub-range of a `Slice` typealias SubSlice = Slice subscript (subRange: Range) -> Slice @@ -3618,7 +5692,9 @@ struct Slice : MutableCollectionType, Sliceable { } extension Slice : ArrayLiteralConvertible { - static func convertFromArrayLiteral(elements: T...) -> Slice + + /// Create an instance containing `elements`. + init(arrayLiteral elements: T...) } @@ -3627,6 +5703,8 @@ extension Slice { /// Construct an empty Slice init() + + /// Construct from an arbitrary sequence with elements of type `T` init(_ s: S) /// Construct a Slice of `count` elements, each initialized to @@ -3648,31 +5726,48 @@ extension Slice { /// The last element, or `nil` if the array is empty var last: T? { get } - /// Ensure the array has enough mutable contiguous storage to store - /// minimumCapacity elements in. Note: does not affect count. - /// Complexity: O(N) + /// Reserve enough space to store minimumCapacity elements. + /// + /// PostCondition: `capacity >= minimumCapacity` and the array has + /// mutable contiguous storage. + /// + /// Complexity: O(`count`) mutating func reserveCapacity(minimumCapacity: Int) - /// Append newElement to the Slice in O(1) (amortized) + /// Append newElement to the Slice + /// + /// Complexity: amortized O(1) unless `self`'s storage is shared with another live array; O(`count`) otherwise. mutating func append(newElement: T) - /// Append elements from `sequence` to the Array - mutating func extend(sequence: S) + /// Append the elements of `newElements` to `self`. + /// + /// Complexity: O(*length of result*) + /// + mutating func extend(newElements: S) /// Remove an element from the end of the Slice in O(1). /// Requires: count > 0 mutating func removeLast() -> T - /// Insert an element at index `i` in O(N). Requires: `i` <= - /// `count` + /// Insert `newElement` at index `i`. + /// + /// Requires: `i <= count` + /// + /// Complexity: O(\ `count`\ ). mutating func insert(newElement: T, atIndex i: Int) - /// Remove the element at the given index. Worst case complexity: - /// O(N). Requires: `index` < `count` + /// Remove and return the element at index `i` + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `count`\ ). mutating func removeAtIndex(index: Int) -> T - /// Erase all the elements. If `keepCapacity` is `true`, `capacity` - /// will not change + /// Remove all elements. + /// + /// Postcondition: `capacity == 0` iff `keepCapacity` is `false`. + /// + /// Complexity: O(\ `countElements(self)`\ ). mutating func removeAll(keepCapacity: Bool = default) /// Interpose `self` between each consecutive pair of `elements`, @@ -3701,24 +5796,30 @@ extension Slice { /// over the elements. func sorted(isOrderedBefore: (T, T) -> Bool) -> Slice - /// Return a Slice containing the results of calling + /// Return a `Slice` containing the results of calling /// `transform(x)` on each element `x` of `self` func map(transform: (T) -> U) -> Slice /// A Slice containing the elements of `self` in reverse order func reverse() -> Slice - /// Return a Slice containing the elements `x` of `self` for which + /// Return a `Slice` containing the elements `x` of `self` for which /// `includeElement(x)` is `true` func filter(includeElement: (T) -> Bool) -> Slice } extension Slice : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension Slice : Printable, DebugPrintable { + + /// A textual representation of `self`. var description: String { get } + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } @@ -3726,138 +5827,413 @@ extension Slice : Printable, DebugPrintable { extension Slice { - /// Call body(p), where p is a pointer to the Slice's contiguous storage + /// Call `body(p)`, where `p` is a pointer to the `Slice`\ 's + /// contiguous storage. + /// + /// Often, the optimizer can eliminate bounds checks within an + /// array algorithm, but when that fails, invoking the + /// same algorithm on `body`\ 's argument lets you trade safety for + /// speed. func withUnsafeBufferPointer(body: (UnsafeBufferPointer) -> R) -> R + + /// Call `body(p)`, where `p` is a pointer to the `Slice`\ 's + /// mutable contiguous storage. + /// + /// Often, the optimizer can eliminate bounds- and uniqueness-checks + /// within an array algorithm, but when that fails, invoking the + /// same algorithm on `body`\ 's argument lets you trade safety for + /// speed. mutating func withUnsafeMutableBufferPointer(body: (inout UnsafeMutableBufferPointer) -> R) -> R } extension Slice { - mutating func replaceRange(subRange: Range, with newValues: C) - mutating func splice(s: S, atIndex i: Int) + + /// Replace the given `subRange` of elements with `newElements`. + /// + /// Complexity: O(\ `countElements(subRange)`\ ) if `subRange.endIndex + /// == self.endIndex` and `isEmpty(newElements)`\ , O(N) otherwise. + mutating func replaceRange(subRange: Range, with newElements: C) + + /// Insert `newElements` at index `i` + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `count + countElements(newElements)`\ ). + mutating func splice(newElements: S, atIndex i: Int) + + /// Remove the indicated `subRange` of elements + /// + /// Complexity: O(\ `count`\ ). mutating func removeRange(subRange: Range) } + +/// A *collection* from which a sub-range of elements (a "slice") +/// can be efficiently extracted. protocol Sliceable : _Sliceable { + + /// The *collection* type that represents a sub-range of elements. + /// + /// Though it can't currently be enforced by the type system, the + /// `SubSlice` type in a concrete implementation of `Sliceable` + /// should also be `Sliceable`. typealias SubSlice : _Sliceable subscript (bounds: Range) -> SubSlice { get } } -/// An extremely simple string designed to represent something -/// "statically knowable". -struct StaticString : StaticStringType, Printable, DebugPrintable { +/// An simple string designed to represent text that is "knowable at +/// compile-time". +/// +/// Logically speaking, each instance looks something like this:: +/// +/// enum StaticString { +/// case ASCII(start: UnsafePointer, length: Int) +/// case UTF8(start: UnsafePointer, length: Int) +/// case Scalar(UnicodeScalar) +/// } +struct StaticString : UnicodeScalarLiteralConvertible, ExtendedGraphemeClusterLiteralConvertible, StringLiteralConvertible, Printable, DebugPrintable { + + /// A pointer to the beginning of UTF-8 code units + /// + /// Requires: `self` stores a pointer to either ASCII or UTF-8 code + /// units. var utf8Start: UnsafePointer { get } + + /// The stored Unicode scalar value + /// + /// Requires: `self` stores a single Unicode scalar value. var unicodeScalar: UnicodeScalar { get } + + /// If `self` stores a pointer to ASCII or UTF-8 code units, the + /// length in bytes of that data. + /// + /// If `self` stores a single Unicode scalar value, the value of + /// `byteSize` is unspecified. var byteSize: Word { get } + + /// `true` iff `self` stores a pointer to ASCII or UTF-8 code units var hasPointerRepresentation: Bool { get } + + /// `true` if `self` stores a pointer to ASCII code units. + /// + /// If `self` stores a single Unicode scalar value, the value of + /// `isASCII` is unspecified. var isASCII: Bool { get } + + /// Invoke `body` with a buffer containing the UTF-8 code units of + /// `self`. + /// + /// This method works regardless of what `self` stores. func withUTF8Buffer(body: (UnsafeBufferPointer) -> R) -> R + + /// Return a `String` representing the same sequence of Unicode + /// scalar values as `self` does. var stringValue: String { get } + + /// Create an empty instance. init() - static func convertFromUnicodeScalarLiteral(value: StaticString) -> StaticString - static func convertFromExtendedGraphemeClusterLiteral(value: StaticString) -> StaticString - static func convertFromStringLiteral(value: StaticString) -> StaticString - var description: String { get } - var debugDescription: String { get } -} + init(_builtinUnicodeScalarLiteral value: Builtin.Int32) + /// Create an instance initialized to `value`. + init(unicodeScalarLiteral value: StaticString) + init(_builtinExtendedGraphemeClusterLiteral start: Builtin.RawPointer, byteSize: Builtin.Word, isASCII: Builtin.Int1) -/// `StaticStringType` refines `AssertStringType` to make it more specific for -/// overload resolution. -protocol StaticStringType : AssertStringType { + /// Create an instance initialized to `value`. + init(extendedGraphemeClusterLiteral value: StaticString) + init(_builtinStringLiteral start: Builtin.RawPointer, byteSize: Builtin.Word, isASCII: Builtin.Int1) + + /// Create an instance initialized to `value`. + init(stringLiteral value: StaticString) + + /// A textual representation of `self`. + var description: String { get } + + /// A textual representation of `self`, suitable for debugging. + var debugDescription: String { get } } -/// Models an object that can be written to an `OutputStreamType` in a single, -/// immediately obvious, way. +/// A source of text streaming operations. `Streamable` instances can +/// be written to any *output stream*. /// /// For example: `String`, `Character`, `UnicodeScalar`. protocol Streamable { + + /// Write a textual representation of `self` into `target` func writeTo(inout target: Target) } /// A `SequenceType` of values formed by striding over a closed interval struct StrideThrough : SequenceType { + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> StrideThroughGenerator } extension StrideThrough : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } /// A GeneratorType for StrideThrough struct StrideThroughGenerator : GeneratorType { + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. mutating func next() -> T? } /// A `SequenceType` of values formed by striding over a half-open interval struct StrideTo : SequenceType { + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> StrideToGenerator } extension StrideTo : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } /// A GeneratorType for StrideTo struct StrideToGenerator : GeneratorType { + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. mutating func next() -> T? } -/// A protocol for types that can be stride()d over. +/// Conforming types are notionally continuous, one-dimensional +/// values that can be offset and measured. +/// +/// See also: `stride(from: to: by:)` and `stride(from: through: by:)` protocol Strideable : Comparable, _Strideable { } + +/// An arbitrary Unicode string value. +/// +/// Unicode-Correct +/// =============== +/// +/// Swift strings are designed to be Unicode-correct. In particular, +/// the APIs make it easy to write code that works correctly, and does +/// not surprise end-users, regardless of where you venture in the +/// Unicode character space. For example, +/// +/// * The `==` operator checks for Unicode canonical equivalence, +/// so two different representations of the same string will always +/// compare equal. +/// +/// * String elements are `Characters` (Unicode extended grapheme +/// clusters), a unit of text that is meaningful to most humans. +/// +/// Locale-Insensitive +/// ================== +/// +/// The fundamental operations on Swift strings are not sensitive to +/// locale settings. That's because, for example, the validity of a +/// `Dictionary` in a running program depends on a given +/// string comparison having a single, stable result. Therefore, +/// Swift always uses the default, un-tailored Unicode algorithms +/// for basic string operations. +/// +/// Importing `Foundation` endows swift strings with the full power of +/// the `NSString` API, which allows you to choose more complex +/// locale-sensitive operations explicitly. +/// +/// Value Semantics +/// =============== +/// +/// Each string variable, `let` binding, or stored property has an +/// independent value, so mutations to the string are not observable +/// through its copies:: +/// +/// var a = "foo" +/// var b = a +/// b[b.endIndex.predecessor()] = "x" +/// println("a=\(a), b=\(b)") // a=foo, b=fox +/// +/// Strings use Copy-on-Write so that their data is only copied +/// lazily, upon mutation, when more than one string instance is using +/// the same buffer. Therefore, the first in any sequence of mutating +/// operations may cost `O(N)` time and space, where `N` is the length +/// of the string's (unspecified) underlying representation,. +/// +/// Growth and Capacity +/// =================== +/// +/// When a string's contiguous storage fills up, new storage must be +/// allocated and characters must be moved to the new storage. +/// `String` uses an exponential growth strategy that makes `append` a +/// constant time operation *when amortized over many invocations*. +/// +/// Objective-C Bridge +/// ================== +/// +/// `String` is bridged to Objective-C as `NSString`, and a `String` +/// that originated in Objective-C may store its characters in an +/// `NSString`. Since any arbitrary subclass of `NSSString` can +/// become a `String`, there are no guarantees about representation or +/// efficiency in this case. Since `NSString` is immutable, it is +/// just as though the storage was shared by some copy: the first in +/// any sequence of mutating operations causes elements to be copied +/// into unique, contiguous storage which may cost `O(N)` time and +/// space, where `N` is the length of the string representation (or +/// more, if the underlying `NSString` is has unusual performance +/// characteristics). struct String { init() } extension String : CollectionType { + + /// A character position in a `String` struct Index : BidirectionalIndexType, Comparable, Reflectable { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> String.Index + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> String.Index + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } + + /// The position of the first `Character` if the `String` is + /// non-empty; identical to `endIndex` otherwise. var startIndex: String.Index { get } + + /// The `String`\ 's "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: String.Index { get } subscript (i: String.Index) -> Character { get } + + /// Return a *generator* over the `Characters` in this `String`. + /// + /// Complexity: O(1) func generate() -> IndexingGenerator } extension String { + + /// A collection of UTF-8 code units that encodes a `String` value. struct UTF8View : CollectionType, Reflectable { + + /// A position in a `String.UTF8View` struct Index : ForwardIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> String.UTF8View.Index } + + /// The position of the first code unit if the `String` is + /// non-empty; identical to `endIndex` otherwise. var startIndex: String.UTF8View.Index { get } + + /// The "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: String.UTF8View.Index { get } - subscript (i: String.UTF8View.Index) -> CodeUnit { get } + subscript (position: String.UTF8View.Index) -> CodeUnit { get } + + /// Return a *generator* over the code points that comprise this + /// *sequence*. + /// + /// Complexity: O(1) func generate() -> IndexingGenerator + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } + + /// A UTF-8 encoding of `self`. var utf8: String.UTF8View { get } + + /// A contiguously-stored nul-terminated UTF-8 representation of + /// `self`. + /// + /// To access the underlying memory, invoke + /// `withUnsafeBufferPointer` on the `ContiguousArray`. var nulTerminatedUTF8: ContiguousArray { get } } extension String { + + /// A collection of Unicode scalar values that + /// encode a `String` . struct UnicodeScalarView : Sliceable, SequenceType, Reflectable { + + /// A position in a `String.UnicodeScalarView` struct Index : BidirectionalIndexType, Comparable { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> String.UnicodeScalarView.Index + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> String.UnicodeScalarView.Index } + + /// The position of the first `UnicodeScalar` if the `String` is + /// non-empty; identical to `endIndex` otherwise. var startIndex: String.UnicodeScalarView.Index { get } + + /// The "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: String.UnicodeScalarView.Index { get } - subscript (i: String.UnicodeScalarView.Index) -> UnicodeScalar { get } + subscript (position: String.UnicodeScalarView.Index) -> UnicodeScalar { get } subscript (r: Range) -> String.UnicodeScalarView { get } + + /// A type whose instances can produce the elements of this + /// sequence, in order. struct Generator : GeneratorType { + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. + /// + /// Requires: no preceding call to `self.next()` has returned + /// `nil`. mutating func next() -> UnicodeScalar? } + + /// Return a *generator* over the `UnicodeScalar`\ s that comprise + /// this *sequence*. + /// + /// Complexity: O(1) func generate() -> String.UnicodeScalarView.Generator + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } } @@ -3881,6 +6257,8 @@ extension String { } extension String { + + /// Construct an instance containing just the given `Character`. init(_ c: Character) } @@ -3893,44 +6271,60 @@ extension String { } extension String : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension String : OutputStreamType { - mutating func write(string: String) + mutating func write(other: String) } extension String : Streamable { + + /// Write a textual representation of `self` into `target` func writeTo(inout target: Target) } extension String { + init(_builtinUnicodeScalarLiteral value: Builtin.Int32) } extension String : UnicodeScalarLiteralConvertible { - static func convertFromUnicodeScalarLiteral(value: String) -> String + + /// Create an instance initialized to `value`. + init(unicodeScalarLiteral value: String) } extension String { + init(_builtinExtendedGraphemeClusterLiteral start: Builtin.RawPointer, byteSize: Builtin.Word, isASCII: Builtin.Int1) } extension String : ExtendedGraphemeClusterLiteralConvertible { - static func convertFromExtendedGraphemeClusterLiteral(value: String) -> String + + /// Create an instance initialized to `value`. + init(extendedGraphemeClusterLiteral value: String) } extension String { + init(_builtinUTF16StringLiteral start: Builtin.RawPointer, numberOfCodeUnits: Builtin.Word) } extension String { + init(_builtinStringLiteral start: Builtin.RawPointer, byteSize: Builtin.Word, isASCII: Builtin.Int1) } extension String : StringLiteralConvertible { - static func convertFromStringLiteral(value: String) -> String + + /// Create an instance initialized to `value`. + init(stringLiteral value: String) } extension String : DebugPrintable { + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } @@ -3943,16 +6337,34 @@ extension String : Comparable { } extension String { - mutating func extend(rhs: String) + + /// Append the elements of `other` to `self`. + mutating func extend(other: String) + + /// Append `x` to `self`. + /// + /// Complexity: amortized O(1). mutating func append(x: UnicodeScalar) } extension String : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension String : StringInterpolationConvertible { + + /// Create an instance by concatenating the elements of `strings` static func convertFromStringInterpolation(strings: String...) -> String + + /// Create an instance containing `expr`\ 's `print` representation static func convertFromStringInterpolationSegment(expr: T) -> String } @@ -3967,29 +6379,77 @@ extension String : Sliceable { extension String : ExtensibleCollectionType { - /// Reserve enough space to store `n` ASCII characters in O(N). + /// Reserve enough space to store `n` ASCII characters. /// - /// If current capacity is sufficient, has no effect. + /// Complexity: O(`n`) mutating func reserveCapacity(n: Int) + + /// Append `c` to `self`. + /// + /// Complexity: amortized O(1). mutating func append(c: Character) - mutating func extend(seq: S) - init(seq: S) + + /// Append the elements of `newElements` to `self`. + mutating func extend(newElements: S) + + /// Create an instance containing `characters`. + init(_ characters: S) } extension String { + + /// Interpose `self` between every pair of consecutive `elements`, + /// then concatenate the result. For example:: + /// + /// "-|-".join(["foo", "bar", "baz"]) // "foo-|-bar-|-baz" func join(elements: S) -> String } extension String : RangeReplaceableCollectionType { - /// Replace the given `subRange` of elements with `newValues`. - /// Complexity: O(\ `countElements(subRange)`\ ) if `subRange.endIndex - /// == self.endIndex` and `isEmpty(newValues)`\ , O(N) otherwise. - mutating func replaceRange(subRange: Range, with newValues: C) - mutating func insert(newElement: Character, atIndex i: String.Index) - mutating func splice(newValues: S, atIndex i: String.Index) + /// Replace the given `subRange` of elements with `newElements`. + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `countElements(subRange)`\ ) if `subRange.endIndex + /// == self.endIndex` and `isEmpty(newElements)`\ , O(N) otherwise. + mutating func replaceRange(subRange: Range, with newElements: C) + + /// Insert `newElement` at index `i`. + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `countElements(self)`\ ). + mutating func insert(newElement: Character, atIndex i: String.Index) + + /// Insert `newElements` at index `i` + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `countElements(self) + countElements(newElements)`\ ). + mutating func splice(newElements: S, atIndex i: String.Index) + + /// Remove and return the element at index `i` + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `countElements(self)`\ ). mutating func removeAtIndex(i: String.Index) -> Character + + /// Remove the indicated `subRange` of characters + /// + /// Invalidates all indices with respect to `self`. + /// + /// Complexity: O(\ `countElements(self)`\ ). mutating func removeRange(subRange: Range) + + /// Remove all characters. + /// + /// Invalidates all indices with respect to `self`. + /// + /// :param: `keepCapacity`, if `true`, prevents the release of + //// allocated storage, which can be a useful optimization + /// when `self` is going to be grown again. mutating func removeAll(keepCapacity: Bool = default) } @@ -4015,22 +6475,48 @@ extension String : StringInterpolationConvertible { } extension String { + + /// Construct an instance that is the concatenation of `sz` copies + /// of `repeatedValue` init(count sz: Int, repeatedValue c: Character) + + /// Construct an instance that is the concatenation of `sz` copies + /// of `Character(repeatedValue)` init(count: Int, repeatedValue c: UnicodeScalar) + + /// `true` iff `self` contains no characters. var isEmpty: Bool { get } } extension String { + + /// Return `true` iff `self` begins with `prefix` func hasPrefix(prefix: String) -> Bool + + /// Return `true` iff `self` ends with `suffix` func hasSuffix(suffix: String) -> Bool } extension String { + + /// Create an instance representing `v` in base 10. init(_ v: T) + + /// Create an instance representing `v` in base 10. init(_ v: T) + + /// Create an instance representing `v` in the given `radix` (base). + /// + /// Numerals greater than 9 are represented as roman letters, + /// starting with `a` if `uppercase` is `false` or `A` otherwise. init(_ v: T, radix: Int, uppercase: Bool = default) + + /// Create an instance representing `v` in the given `radix` (base). + /// + /// Numerals greater than 9 are represented as roman letters, + /// starting with `a` if `uppercase` is `false` or `A` otherwise. init(_ v: T, radix: Int, uppercase: Bool = default) } @@ -4045,15 +6531,38 @@ extension String { extension String { + + /// A collection of UTF-16 code units that encodes a `String` value. struct UTF16View : Sliceable, Reflectable { + + /// The position of the first code unit if the `String` is + /// non-empty; identical to `endIndex` otherwise. var startIndex: Int { get } + + /// The "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: Int { get } + + /// A type whose instances can produce the elements of this + /// sequence, in order. typealias Generator + + /// Return a *generator* over the code points that comprise this + /// *sequence*. + /// + /// Complexity: O(1) func generate() -> Generator - subscript (i: Int) -> UInt16 { get } + subscript (position: Int) -> UInt16 { get } subscript (subRange: Range) -> String.UTF16View { get } + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } + + /// A UTF-16 encoding of `self`. var utf16: String.UTF16View { get } } @@ -4064,31 +6573,54 @@ extension String { extension String { + + /// Construct an instance given a collection of Unicode scalar + /// values. init(_ view: String.UnicodeScalarView) + + /// The value of `self` as a collection of Unicode scalar values. var unicodeScalars: String.UnicodeScalarView } -protocol StringElementType { - class func toUTF16CodeUnit(_: Self) -> CodeUnit - class func fromUTF16CodeUnit(utf16: CodeUnit) -> Self -} +/// Conforming types can be initialized with string interpolations +/// containing `\(`\ ...\ `)` clauses. protocol StringInterpolationConvertible { + + /// Create an instance by concatenating the elements of `strings` class func convertFromStringInterpolation(strings: Self...) -> Self + + /// Create an instance containing `expr`\ 's `print` representation class func convertFromStringInterpolationSegment(expr: T) -> Self } + +/// Conforming types can be initialized with arbitrary string literals protocol StringLiteralConvertible : ExtendedGraphemeClusterLiteralConvertible { typealias StringLiteralType - class func convertFromStringLiteral(value: StringLiteralType) -> Self + + /// Create an instance initialized to `value`. + init(stringLiteral value: StringLiteralType) } + +/// The default type for an otherwise-unconstrained string literal typealias StringLiteralType = String + +/// A 64-bit unsigned integer value +/// type. struct UInt : UnsignedIntegerType { var value: Builtin.Word + + /// A type that can represent the number of steps between pairs of + /// values. + typealias Distance = Int + + /// Create an instance initialized to zero. init() - init(_ v: Builtin.Word) + + /// Create an instance initialized to `value`. init(_ value: UInt) /// Creates an integer from its big-endian representation, changing the @@ -4098,9 +6630,10 @@ struct UInt : UnsignedIntegerType { /// Creates an integer from its little-endian representation, changing the /// byte order if necessary. init(littleEndian value: UInt) - static func convertFromIntegerLiteral(value: UInt) -> UInt - typealias ArrayBound = UInt - var arrayBoundValue: UInt { get } + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: UInt) /// Returns the big-endian representation of the integer, changing the /// byte order if necessary. @@ -4117,35 +6650,84 @@ struct UInt : UnsignedIntegerType { } extension UInt : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension UInt : Printable { + + /// A textual representation of `self`. var description: String { get } } extension UInt : RandomAccessIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> UInt + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> UInt - func distanceTo(other: UInt) -> Int - func advancedBy(amount: Int) -> UInt + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). + func distanceTo(other: UInt) -> Distance + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) + func advancedBy(amount: Distance) -> UInt } extension UInt { + + /// Add `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func addWithOverflow(lhs: UInt, _ rhs: UInt) -> (UInt, overflow: Bool) + + /// Subtract `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func subtractWithOverflow(lhs: UInt, _ rhs: UInt) -> (UInt, overflow: Bool) + + /// Multiply `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func multiplyWithOverflow(lhs: UInt, _ rhs: UInt) -> (UInt, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// a result and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func divideWithOverflow(lhs: UInt, _ rhs: UInt) -> (UInt, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// the remainder and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func remainderWithOverflow(lhs: UInt, _ rhs: UInt) -> (UInt, overflow: Bool) + + /// Represent this number using Swift's widest native unsigned + /// integer type. func toUIntMax() -> UIntMax + + /// Explicitly convert to `IntMax`, trapping on overflow (except in -Ounchecked builds). func toIntMax() -> IntMax - static func from(x: UIntMax) -> UInt } extension UInt { @@ -4180,27 +6762,50 @@ extension UInt { } extension UInt : BitwiseOperationsType { + + /// The empty bitset of type UInt. static var allZeros: UInt { get } } extension UInt { - init(_ v: Float) - init(_ v: Double) - init(_ v: Float80) + + /// Construct an instance that approximates `other`. + init(_ other: Float) + + /// Construct an instance that approximates `other`. + init(_ other: Double) + + /// Construct an instance that approximates `other`. + init(_ other: Float80) } extension UInt : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension UInt : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } + +/// A 16-bit unsigned integer value +/// type. struct UInt16 : UnsignedIntegerType { var value: Builtin.Int16 + + /// A type that can represent the number of steps between pairs of + /// values. + typealias Distance = Int + + /// Create an instance initialized to zero. init() - init(_ v: Builtin.Int16) + + /// Create an instance initialized to `value`. init(_ value: UInt16) /// Creates an integer from its big-endian representation, changing the @@ -4210,9 +6815,10 @@ struct UInt16 : UnsignedIntegerType { /// Creates an integer from its little-endian representation, changing the /// byte order if necessary. init(littleEndian value: UInt16) - static func convertFromIntegerLiteral(value: UInt16) -> UInt16 - typealias ArrayBound = UInt16 - var arrayBoundValue: UInt16 { get } + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: UInt16) /// Returns the big-endian representation of the integer, changing the /// byte order if necessary. @@ -4229,35 +6835,84 @@ struct UInt16 : UnsignedIntegerType { } extension UInt16 : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension UInt16 : Printable { + + /// A textual representation of `self`. var description: String { get } } extension UInt16 : RandomAccessIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> UInt16 + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> UInt16 - func distanceTo(other: UInt16) -> Int - func advancedBy(amount: Int) -> UInt16 + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). + func distanceTo(other: UInt16) -> Distance + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) + func advancedBy(amount: Distance) -> UInt16 } extension UInt16 { + + /// Add `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func addWithOverflow(lhs: UInt16, _ rhs: UInt16) -> (UInt16, overflow: Bool) + + /// Subtract `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func subtractWithOverflow(lhs: UInt16, _ rhs: UInt16) -> (UInt16, overflow: Bool) + + /// Multiply `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func multiplyWithOverflow(lhs: UInt16, _ rhs: UInt16) -> (UInt16, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// a result and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func divideWithOverflow(lhs: UInt16, _ rhs: UInt16) -> (UInt16, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// the remainder and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func remainderWithOverflow(lhs: UInt16, _ rhs: UInt16) -> (UInt16, overflow: Bool) + + /// Represent this number using Swift's widest native unsigned + /// integer type. func toUIntMax() -> UIntMax + + /// Explicitly convert to `IntMax`. func toIntMax() -> IntMax - static func from(x: UIntMax) -> UInt16 } extension UInt16 { @@ -4316,32 +6971,53 @@ extension UInt16 { } extension UInt16 : BitwiseOperationsType { + + /// The empty bitset of type UInt16. static var allZeros: UInt16 { get } } extension UInt16 { - init(_ v: Float) - init(_ v: Double) - init(_ v: Float80) + + /// Construct an instance that approximates `other`. + init(_ other: Float) + + /// Construct an instance that approximates `other`. + init(_ other: Double) + + /// Construct an instance that approximates `other`. + init(_ other: Float80) } extension UInt16 : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } -extension UInt16 : StringElementType { - static func toUTF16CodeUnit(x: CodeUnit) -> CodeUnit - static func fromUTF16CodeUnit(utf16: CodeUnit) -> CodeUnit +extension UInt16 { } extension UInt16 : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } + +/// A 32-bit unsigned integer value +/// type. struct UInt32 : UnsignedIntegerType { var value: Builtin.Int32 + + /// A type that can represent the number of steps between pairs of + /// values. + typealias Distance = Int + + /// Create an instance initialized to zero. init() - init(_ v: Builtin.Int32) + + /// Create an instance initialized to `value`. init(_ value: UInt32) /// Creates an integer from its big-endian representation, changing the @@ -4351,9 +7027,10 @@ struct UInt32 : UnsignedIntegerType { /// Creates an integer from its little-endian representation, changing the /// byte order if necessary. init(littleEndian value: UInt32) - static func convertFromIntegerLiteral(value: UInt32) -> UInt32 - typealias ArrayBound = UInt32 - var arrayBoundValue: UInt32 { get } + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: UInt32) /// Returns the big-endian representation of the integer, changing the /// byte order if necessary. @@ -4370,35 +7047,84 @@ struct UInt32 : UnsignedIntegerType { } extension UInt32 : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension UInt32 : Printable { + + /// A textual representation of `self`. var description: String { get } } extension UInt32 : RandomAccessIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> UInt32 + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> UInt32 - func distanceTo(other: UInt32) -> Int - func advancedBy(amount: Int) -> UInt32 + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). + func distanceTo(other: UInt32) -> Distance + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) + func advancedBy(amount: Distance) -> UInt32 } extension UInt32 { + + /// Add `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func addWithOverflow(lhs: UInt32, _ rhs: UInt32) -> (UInt32, overflow: Bool) + + /// Subtract `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func subtractWithOverflow(lhs: UInt32, _ rhs: UInt32) -> (UInt32, overflow: Bool) + + /// Multiply `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func multiplyWithOverflow(lhs: UInt32, _ rhs: UInt32) -> (UInt32, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// a result and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func divideWithOverflow(lhs: UInt32, _ rhs: UInt32) -> (UInt32, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// the remainder and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func remainderWithOverflow(lhs: UInt32, _ rhs: UInt32) -> (UInt32, overflow: Bool) + + /// Represent this number using Swift's widest native unsigned + /// integer type. func toUIntMax() -> UIntMax + + /// Explicitly convert to `IntMax`. func toIntMax() -> IntMax - static func from(x: UIntMax) -> UInt32 } extension UInt32 { @@ -4445,31 +7171,58 @@ extension UInt32 { } extension UInt32 : BitwiseOperationsType { + + /// The empty bitset of type UInt32. static var allZeros: UInt32 { get } } extension UInt32 { - init(_ v: Float) - init(_ v: Double) - init(_ v: Float80) + + /// Construct an instance that approximates `other`. + init(_ other: Float) + + /// Construct an instance that approximates `other`. + init(_ other: Double) + + /// Construct an instance that approximates `other`. + init(_ other: Float80) } extension UInt32 : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension UInt32 { + + /// Construct with value `v.value`. + /// + /// Requires: `v.value` can be represented as UInt32. init(_ v: UnicodeScalar) } extension UInt32 : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } + +/// A 64-bit unsigned integer value +/// type. struct UInt64 : UnsignedIntegerType { var value: Builtin.Int64 + + /// A type that can represent the number of steps between pairs of + /// values. + typealias Distance = Int + + /// Create an instance initialized to zero. init() - init(_ v: Builtin.Int64) + + /// Create an instance initialized to `value`. init(_ value: UInt64) /// Creates an integer from its big-endian representation, changing the @@ -4479,9 +7232,10 @@ struct UInt64 : UnsignedIntegerType { /// Creates an integer from its little-endian representation, changing the /// byte order if necessary. init(littleEndian value: UInt64) - static func convertFromIntegerLiteral(value: UInt64) -> UInt64 - typealias ArrayBound = UInt64 - var arrayBoundValue: UInt64 { get } + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: UInt64) /// Returns the big-endian representation of the integer, changing the /// byte order if necessary. @@ -4498,35 +7252,84 @@ struct UInt64 : UnsignedIntegerType { } extension UInt64 : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension UInt64 : Printable { + + /// A textual representation of `self`. var description: String { get } } extension UInt64 : RandomAccessIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> UInt64 + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> UInt64 - func distanceTo(other: UInt64) -> Int - func advancedBy(amount: Int) -> UInt64 + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). + func distanceTo(other: UInt64) -> Distance + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) + func advancedBy(amount: Distance) -> UInt64 } extension UInt64 { + + /// Add `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func addWithOverflow(lhs: UInt64, _ rhs: UInt64) -> (UInt64, overflow: Bool) + + /// Subtract `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func subtractWithOverflow(lhs: UInt64, _ rhs: UInt64) -> (UInt64, overflow: Bool) + + /// Multiply `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func multiplyWithOverflow(lhs: UInt64, _ rhs: UInt64) -> (UInt64, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// a result and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func divideWithOverflow(lhs: UInt64, _ rhs: UInt64) -> (UInt64, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// the remainder and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func remainderWithOverflow(lhs: UInt64, _ rhs: UInt64) -> (UInt64, overflow: Bool) + + /// Represent this number using Swift's widest native unsigned + /// integer type. func toUIntMax() -> UIntMax + + /// Explicitly convert to `IntMax`, trapping on overflow (except in -Ounchecked builds). func toIntMax() -> IntMax - static func from(x: UIntMax) -> UInt64 } extension UInt64 { @@ -4549,69 +7352,146 @@ extension UInt64 { } extension UInt64 : BitwiseOperationsType { + + /// The empty bitset of type UInt64. static var allZeros: UInt64 { get } } extension UInt64 { - init(_ v: Float) - init(_ v: Double) - init(_ v: Float80) + + /// Construct an instance that approximates `other`. + init(_ other: Float) + + /// Construct an instance that approximates `other`. + init(_ other: Double) + + /// Construct an instance that approximates `other`. + init(_ other: Float80) } extension UInt64 : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension UInt64 { + + /// Construct with value `v.value`. + /// + /// Requires: `v.value` can be represented as UInt64. init(_ v: UnicodeScalar) } extension UInt64 : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } + +/// A 8-bit unsigned integer value +/// type. struct UInt8 : UnsignedIntegerType { var value: Builtin.Int8 + + /// A type that can represent the number of steps between pairs of + /// values. + typealias Distance = Int + + /// Create an instance initialized to zero. init() - init(_ v: Builtin.Int8) + + /// Create an instance initialized to `value`. init(_ value: UInt8) - static func convertFromIntegerLiteral(value: UInt8) -> UInt8 - typealias ArrayBound = UInt8 - var arrayBoundValue: UInt8 { get } + init(_builtinIntegerLiteral value: Builtin.Int2048) + + /// Create an instance initialized to `value`. + init(integerLiteral value: UInt8) static var max: UInt8 { get } static var min: UInt8 { get } } extension UInt8 : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension UInt8 : Printable { + + /// A textual representation of `self`. var description: String { get } } extension UInt8 : RandomAccessIndexType { + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> UInt8 + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> UInt8 - func distanceTo(other: UInt8) -> Int - func advancedBy(amount: Int) -> UInt8 + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). + func distanceTo(other: UInt8) -> Distance + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) + func advancedBy(amount: Distance) -> UInt8 } extension UInt8 { + + /// Add `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func addWithOverflow(lhs: UInt8, _ rhs: UInt8) -> (UInt8, overflow: Bool) + + /// Subtract `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func subtractWithOverflow(lhs: UInt8, _ rhs: UInt8) -> (UInt8, overflow: Bool) + + /// Multiply `lhs` and `rhs`, returning a result and a + /// `Bool` that is true iff the operation caused an arithmetic + /// overflow. static func multiplyWithOverflow(lhs: UInt8, _ rhs: UInt8) -> (UInt8, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// a result and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func divideWithOverflow(lhs: UInt8, _ rhs: UInt8) -> (UInt8, overflow: Bool) - /// Operations that return an overflow bit in addition to a partial result, - /// helpful for checking for overflow when you want to handle it. + /// Divide `lhs` and `rhs`, returning + /// the remainder and a `Bool` + /// that is true iff the operation caused an arithmetic overflow. static func remainderWithOverflow(lhs: UInt8, _ rhs: UInt8) -> (UInt8, overflow: Bool) + + /// Represent this number using Swift's widest native unsigned + /// integer type. func toUIntMax() -> UIntMax + + /// Explicitly convert to `IntMax`. func toIntMax() -> IntMax - static func from(x: UIntMax) -> UInt8 } extension UInt8 { @@ -4682,46 +7562,95 @@ extension UInt8 { } extension UInt8 : BitwiseOperationsType { + + /// The empty bitset of type UInt8. static var allZeros: UInt8 { get } } extension UInt8 { - init(_ v: Float) - init(_ v: Double) - init(_ v: Float80) + + /// Construct an instance that approximates `other`. + init(_ other: Float) + + /// Construct an instance that approximates `other`. + init(_ other: Double) + + /// Construct an instance that approximates `other`. + init(_ other: Float80) } extension UInt8 : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } -extension UInt8 : StringElementType { - static func toUTF16CodeUnit(x: CodeUnit) -> CodeUnit - static func fromUTF16CodeUnit(utf16: CodeUnit) -> CodeUnit +extension UInt8 { } extension UInt8 { + + /// Construct with value `v.value`. + /// + /// Requires: `v.value` can be represented as UInt8. init(_ v: UnicodeScalar) } extension UInt8 : CVarArgType { + + /// Transform `self` into a series of machine words that can be + /// appropriately interpreted by C varargs func encode() -> [Word] } + +/// The largest native unsigned integer type typealias UIntMax = UInt64 + +/// A codec for UTF-16. struct UTF16 : UnicodeCodecType { + + /// A type that can hold code unit values for this + /// encoding. typealias CodeUnit = UInt16 init() + + /// Start or continue decoding a UTF sequence. + /// + /// In order to decode a code unit sequence completely, this function should + /// be called repeatedly until it returns `UnicodeDecodingResult.EmptyInput`. + /// Checking that the generator was exhausted is not sufficient. The decoder + /// can have an internal buffer that is pre-filled with data from the input + /// generator. + /// + /// Because of buffering, it is impossible to find the corresponing position + /// in the generator for a given returned `UnicodeScalar` or an error. + /// + /// :param: `next`: a *generator* of code units to be decoded. mutating func decode(inout input: G) -> UnicodeDecodingResult + + /// Encode a `UnicodeScalar` as a series of `CodeUnit`\ s by `put`\ + /// 'ing each `CodeUnit` to `output`. static func encode(input: UnicodeScalar, inout output: S) } extension UTF16 { + + /// Return the number of code units required to encode `x`. static func width(x: UnicodeScalar) -> Int + + /// Return the high surrogate code unit of a surrogate pair + /// representing `x`. + /// + /// Requires: `width(x) == 2` static func leadSurrogate(x: UnicodeScalar) -> CodeUnit + + /// Return the low surrogate code unit of a surrogate pair + /// representing `x`. + /// + /// Requires: `width(x) == 2` static func trailSurrogate(x: UnicodeScalar) -> CodeUnit - static func copy(source: UnsafeMutablePointer, destination: UnsafeMutablePointer, count: Int) /// Returns the number of UTF-16 code units required for the given code unit /// sequence when transcoded to UTF-16, and a bit describing if the sequence @@ -4733,23 +7662,76 @@ extension UTF16 { static func measure(_: Encoding.Type, input: Input, repairIllFormedSequences: Bool) -> (Int, Bool)? } + +/// A codec for UTF-32. struct UTF32 : UnicodeCodecType { + + /// A type that can hold code unit values for this + /// encoding. typealias CodeUnit = UInt32 init() + + /// Start or continue decoding a UTF sequence. + /// + /// In order to decode a code unit sequence completely, this function should + /// be called repeatedly until it returns `UnicodeDecodingResult.EmptyInput`. + /// Checking that the generator was exhausted is not sufficient. The decoder + /// can have an internal buffer that is pre-filled with data from the input + /// generator. + /// + /// Because of buffering, it is impossible to find the corresponing position + /// in the generator for a given returned `UnicodeScalar` or an error. + /// + /// :param: `next`: a *generator* of code units to be decoded. mutating func decode(inout input: G) -> UnicodeDecodingResult + + /// Encode a `UnicodeScalar` as a series of `CodeUnit`\ s by `put`\ + /// 'ing each `CodeUnit` to `output`. static func encode(input: UnicodeScalar, inout output: S) } + +/// A codec for UTF-8. struct UTF8 : UnicodeCodecType { + + /// A type that can hold code unit values for this + /// encoding. typealias CodeUnit = UInt8 init() + + /// Start or continue decoding a UTF sequence. + /// + /// In order to decode a code unit sequence completely, this function should + /// be called repeatedly until it returns `UnicodeDecodingResult.EmptyInput`. + /// Checking that the generator was exhausted is not sufficient. The decoder + /// can have an internal buffer that is pre-filled with data from the input + /// generator. + /// + /// Because of buffering, it is impossible to find the corresponing position + /// in the generator for a given returned `UnicodeScalar` or an error. + /// + /// :param: `next`: a *generator* of code units to be decoded. mutating func decode(inout next: G) -> UnicodeDecodingResult + + /// Encode a `UnicodeScalar` as a series of `CodeUnit`\ s by `put`\ + /// 'ing each `CodeUnit` to `output`. static func encode(input: UnicodeScalar, inout output: S) } + +/// An unsigned integer type that occupies one machine word typealias UWord = UInt + +/// A Unicode encoding scheme. +/// +/// Consists of an underlying `CodeUnit` type and functions to +/// translate between sequences of these code units and Unicode +/// scalar values. protocol UnicodeCodecType { + + /// A type that can hold code unit values for this + /// encoding. typealias CodeUnit init() @@ -4763,25 +7745,64 @@ protocol UnicodeCodecType { /// /// Because of buffering, it is impossible to find the corresponing position /// in the generator for a given returned `UnicodeScalar` or an error. + /// + /// :param: `next`: a *generator* of code units to be decoded. mutating func decode(inout next: G) -> UnicodeDecodingResult + + /// Encode a `UnicodeScalar` as a series of `CodeUnit`\ s by `put`\ + /// 'ing each `CodeUnit` to `output`. class func encode(input: UnicodeScalar, inout output: S) } + +/// The result of one Unicode decoding step +/// +/// A unicode scalar value, an indication that no more unicode scalars +/// are available, or an indication of a decoding error. enum UnicodeDecodingResult { case Result(UnicodeScalar) case EmptyInput case Error + + /// Return true if `self` indicates no more unicode scalars are + /// available. func isEmptyInput() -> Bool } + +/// A Unicode scalar value. struct UnicodeScalar : UnicodeScalarLiteralConvertible { + + /// A numeric representation of `self`. var value: UInt32 { get } - static func convertFromUnicodeScalarLiteral(value: UnicodeScalar) -> UnicodeScalar + init(_builtinUnicodeScalarLiteral value: Builtin.Int32) + + /// Create an instance initialized to `value`. + init(unicodeScalarLiteral value: UnicodeScalar) + + /// Creates an instance of the NUL scalar value. init() + + /// Create an instance with numeric value `v`. + /// + /// Requires: `v` is a valid Unicode scalar value. init(_ v: UInt32) + + /// Create an instance with numeric value `v`. + /// + /// Requires: `v` is a valid Unicode scalar value. init(_ v: UInt16) + + /// Create an instance with numeric value `v`. init(_ v: UInt8) + + /// Create a duplicate of `v`. init(_ v: UnicodeScalar) + + /// Return a String representation of `self` . + /// + /// :param: `asASCII`, if `true`, forces most values into a numeric + /// representation. func escape(#asASCII: Bool) -> String /// Returns true if this is an ASCII character (code point 0 to 127 @@ -4790,23 +7811,43 @@ struct UnicodeScalar : UnicodeScalarLiteralConvertible { } extension UnicodeScalar : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } extension UnicodeScalar : Streamable { + + /// Write a textual representation of `self` into `target` func writeTo(inout target: Target) } extension UnicodeScalar : Printable, DebugPrintable { + + /// A textual representation of `self`. var description: String { get } + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } extension UnicodeScalar : Hashable { + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } } extension UnicodeScalar { + + /// Construct with value `v`. + /// + /// Requires: `v` is a valid unicode scalar value. init(_ v: Int) } @@ -4816,11 +7857,18 @@ extension UnicodeScalar : Comparable { extension UnicodeScalar { } + +/// Conforming types can be initialized with string literals +/// containing a single Unicode scalar value. protocol UnicodeScalarLiteralConvertible { typealias UnicodeScalarLiteralType - class func convertFromUnicodeScalarLiteral(value: UnicodeScalarLiteralType) -> Self + + /// Create an instance initialized to `value`. + init(unicodeScalarLiteral value: UnicodeScalarLiteralType) } + +/// The default type for an otherwise-unconstrained unicode scalar literal typealias UnicodeScalarType = String @@ -4900,7 +7948,16 @@ struct Unmanaged { /// contiguously in memory, presenting a `Collection` interface to the /// underlying elements. struct UnsafeBufferPointer : CollectionType { + + /// Always zero, which is the index of the first element in a + /// non-empty buffer. var startIndex: Int { get } + + /// The "past the end" position; always identical to `count`. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: Int { get } subscript (i: Int) -> T { get } @@ -4908,7 +7965,9 @@ struct UnsafeBufferPointer : CollectionType { /// `T` instances beginning at `start`. init(start: UnsafePointer, count: Int) - /// Return a generator over the buffer's elements + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> UnsafeBufferPointerGenerator /// A pointer to the first element of the buffer @@ -4919,6 +7978,8 @@ struct UnsafeBufferPointer : CollectionType { } extension UnsafeBufferPointer : DebugPrintable { + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } @@ -4926,7 +7987,13 @@ extension UnsafeBufferPointer : DebugPrintable { /// A generator for the elements in the buffer referenced by /// `UnsafeBufferPointer` or `UnsafeMutableBufferPointer` struct UnsafeBufferPointerGenerator : GeneratorType, SequenceType { + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. mutating func next() -> T? + + /// `UnsafeBufferPointerGenerator` is also a `SequenceType`, so it + /// `generate`\ 's a copy of itself func generate() -> UnsafeBufferPointerGenerator } @@ -4935,7 +8002,16 @@ struct UnsafeBufferPointerGenerator : GeneratorType, SequenceType { /// contiguously in memory, presenting a `Collection` interface to the /// underlying elements. struct UnsafeMutableBufferPointer : MutableCollectionType { + + /// Always zero, which is the index of the first element in a + /// non-empty buffer. var startIndex: Int { get } + + /// The "past the end" position; always identical to `count`. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: Int { get } subscript (i: Int) -> T { get nonmutating set } @@ -4943,7 +8019,9 @@ struct UnsafeMutableBufferPointer : MutableCollectionType { /// `T` instances beginning at `start`. init(start: UnsafeMutablePointer, count: Int) - /// Return a generator over the buffer's elements + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> UnsafeBufferPointerGenerator /// A pointer to the first element of the buffer @@ -4954,6 +8032,8 @@ struct UnsafeMutableBufferPointer : MutableCollectionType { } extension UnsafeMutableBufferPointer : DebugPrintable { + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } @@ -5002,7 +8082,11 @@ struct UnsafeMutablePointer : RandomAccessIndexType, Hashable, NilLiteralConv /// /// This is a fundamentally unsafe conversion. init(_ from: UnsafePointer) - static func convertFromNilLiteral() -> UnsafeMutablePointer + + /// Create an instance initialized with `nil`. + init(nilLiteral: ()) + + /// Return a `nil` instance. static func null() -> UnsafeMutablePointer /// Allocate memory for `num` objects of type `T`. @@ -5099,18 +8183,51 @@ struct UnsafeMutablePointer : RandomAccessIndexType, Hashable, NilLiteralConv /// be initialized before being used again. func destroy(count: Int) subscript (i: Int) -> T { get nonmutating set } + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> UnsafeMutablePointer + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> UnsafeMutablePointer + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). func distanceTo(x: UnsafeMutablePointer) -> Int + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) func advancedBy(n: Int) -> UnsafeMutablePointer } extension UnsafeMutablePointer : DebugPrintable { + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } extension UnsafeMutablePointer : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } @@ -5163,52 +8280,140 @@ struct UnsafePointer : RandomAccessIndexType, Hashable, NilLiteralConvertible /// /// This is a fundamentally unsafe conversion. init(_ from: UnsafePointer) - static func convertFromNilLiteral() -> UnsafePointer + + /// Create an instance initialized with `nil`. + init(nilLiteral: ()) + + /// Return a `nil` instance. static func null() -> UnsafePointer /// Access the underlying raw memory, getting and /// setting values. var memory: T { get } subscript (i: Int) -> T { get } + + /// The hash value. + /// + /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue` + /// + /// **Note:** the hash value is not guaranteed to be stable across + /// different invocations of the same program. Do not persist the + /// hash value across program runs. var hashValue: Int { get } + + /// Returns the next consecutive value after `self`. + /// + /// Requires: the next value is representable. func successor() -> UnsafePointer + + /// Returns the previous consecutive value before `self`. + /// + /// Requires: the previous value is representable. func predecessor() -> UnsafePointer + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). func distanceTo(x: UnsafePointer) -> Int + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) func advancedBy(n: Int) -> UnsafePointer } extension UnsafePointer : DebugPrintable { + + /// A textual representation of `self`, suitable for debugging. var debugDescription: String { get } } extension UnsafePointer : Reflectable { + + /// Returns a mirror that reflects `self`. func getMirror() -> MirrorType } + +/// A set of common requirements for Swift's unsigned integer types. protocol UnsignedIntegerType : _UnsignedIntegerType, IntegerType { } + +/// An object that can manage the lifetime of storage backing a +/// `CVaListPointer` final class VaListBuilder { } + +/// The empty tuple type. +/// +/// This is the default return type of functions for which no explicit +/// return type is specified. typealias Void = () + +/// A signed integer type that occupies one machine word typealias Word = Int + +/// A sequence of pairs built out of two underlying sequences, where +/// the elements of the `i`\ th pair are the `i`\ th elements of each +/// underlying sequence. struct Zip2 : SequenceType { typealias Stream1 = S0.Generator typealias Stream2 = S1.Generator + + /// A type whose instances can produce the elements of this + /// sequence, in order. typealias Generator = ZipGenerator2 + + /// Construct an instance that makes pairs of elements from `s0` and + /// `s1`. init(_ s0: S0, _ s1: S1) + + /// Return a *generator* over the elements of this *sequence*. + /// + /// Complexity: O(1) func generate() -> Generator } + +/// A generator for the `Zip2` sequence struct ZipGenerator2 : GeneratorType { + + /// The type of element returned by `next()`. typealias Element = (E0.Element, E1.Element) + + /// Construct around a pair of underlying generators. init(_ e0: E0, _ e1: E1) + + /// Advance to the next element and return it, or `nil` if no next + /// element exists. + /// + /// Requires: `next()` has not been applied to a copy of `self` + /// since the copy was made, and no preceding call to `self.next()` + /// has returned `nil`. mutating func next() -> Element? } +func ^(a: T, b: T) -> T + +func ^(lhs: Bool, rhs: Bool) -> Bool + +func ^(lhs: UInt8, rhs: UInt8) -> UInt8 + +func ^(lhs: Int8, rhs: Int8) -> Int8 + +func ^(lhs: UInt16, rhs: UInt16) -> UInt16 + +func ^(lhs: Int16, rhs: Int16) -> Int16 + func ^(lhs: Int, rhs: Int) -> Int func ^(lhs: UInt, rhs: UInt) -> UInt @@ -5221,41 +8426,29 @@ func ^(lhs: Int32, rhs: Int32) -> Int32 func ^(lhs: UInt32, rhs: UInt32) -> UInt32 -func ^(lhs: Int16, rhs: Int16) -> Int16 - -func ^(lhs: UInt16, rhs: UInt16) -> UInt16 - -func ^(lhs: Int8, rhs: Int8) -> Int8 - -func ^(lhs: UInt8, rhs: UInt8) -> UInt8 +func ^=(inout lhs: Int, rhs: Int) -func ^(a: T, b: T) -> T +func ^=(inout lhs: Int32, rhs: Int32) -func ^(lhs: Bool, rhs: Bool) -> Bool +func ^=(inout lhs: UInt32, rhs: UInt32) -func ^=(inout lhs: UInt, rhs: UInt) +func ^=(inout lhs: Int16, rhs: Int16) func ^=(inout lhs: Int8, rhs: Int8) -func ^=(inout lhs: T, rhs: T) +func ^=(inout lhs: UInt8, rhs: UInt8) -func ^=(inout lhs: Int, rhs: Int) +func ^=(inout lhs: UInt16, rhs: UInt16) func ^=(inout lhs: Bool, rhs: Bool) -func ^=(inout lhs: Int64, rhs: Int64) - func ^=(inout lhs: UInt64, rhs: UInt64) -func ^=(inout lhs: Int32, rhs: Int32) - -func ^=(inout lhs: UInt32, rhs: UInt32) - -func ^=(inout lhs: Int16, rhs: Int16) +func ^=(inout lhs: T, rhs: T) -func ^=(inout lhs: UInt8, rhs: UInt8) +func ^=(inout lhs: Int64, rhs: Int64) -func ^=(inout lhs: UInt16, rhs: UInt16) +func ^=(inout lhs: UInt, rhs: UInt) /// The underlying buffer for an ArrayType conforms to _ArrayBufferType @@ -5278,7 +8471,7 @@ protocol _ArrayBufferType : MutableCollectionType { /// Convert to an NSArray. /// Precondition: _isBridgedToObjectiveC(Element.self) /// O(1) if the element type is bridged verbatim, O(N) otherwise - func _asCocoaArray() -> _CocoaArrayType + func _asCocoaArray() -> _SwiftNSArrayRequiredOverridesType subscript (index: Int) -> Element { get nonmutating set } /// If this buffer is backed by a uniquely-referenced mutable @@ -5342,82 +8535,183 @@ protocol _ArrayBufferType : MutableCollectionType { var identity: Word { get } } + +/// This protocol is an implementation detail of `BidirectionalIndexType`; do +/// not use it directly. +/// +/// Its requirements are inherited by `BidirectionalIndexType` and thus must +/// be satisfied by types conforming to that protocol. protocol _BidirectionalIndexType : _ForwardIndexType { - /// Return the previous consecutive value in a discrete sequence + /// Return the previous consecutive value in a discrete sequence. + /// + /// If `self` has a well-defined successor, + /// `self.successor().predecessor() == self`. If `self` has a + /// well-defined predecessor, `self.predecessor().successor() == + /// self`. + /// + /// Requires: `self` has a well-defined predecessor. func predecessor() -> Self } -/// A subset of the NSArray interface with call-compatible selectors -/// (e.g. _SwiftNSRange is layout-compatible with NSRange in -/// getObjects:range: below). Array is backed by one of these, and -/// when _isBridgedToObjectiveC(T.self), it can be used directly as an -/// NSArray. It is safe to convert between NSArray and _CocoaArrayType via -/// unsafeBitCast. -@unsafe_no_objc_tagged_pointer protocol _CocoaArrayType { - func objectAtIndex(index: Int) -> AnyObject - func getObjects(_: UnsafeMutablePointer, range: _SwiftNSRange) - func countByEnumeratingWithState(state: UnsafeMutablePointer<_SwiftNSFastEnumerationState>, objects buffer: UnsafeMutablePointer, count len: Int) -> Int - func copyWithZone(_: COpaquePointer) -> _CocoaArrayType - var count: Int { get } -} - - /// Effectively a proxy for NSString that doesn't mention it by /// name. NSString's conformance to this protocol is declared in /// Foundation. -protocol _CocoaStringType { +@objc protocol _CocoaStringType { } + +/// This protocol is an implementation detail of `CollectionType`; do +/// not use it directly. +/// +/// Its requirements are inherited by `CollectionType` and thus must +/// be satisfied by types conforming to that protocol. protocol _CollectionType : _SequenceType { + + /// A type that represents a valid position in the collection. + /// + /// Valid indices consist of the position of every element and a + /// "past the end" position that's not valid for use as a subscript. typealias Index : ForwardIndexType + + /// The position of the first element in a non-empty collection. + /// + /// Identical to `endIndex` in an empty collection. var startIndex: Index { get } + + /// The collection's "past the end" position. + /// + /// `endIndex` is not a valid argument to `subscript`, and is always + /// reachable from `startIndex` by zero or more applications of + /// `successor()`. var endIndex: Index { get } typealias _Element - subscript (i: Index) -> _Element { get } + subscript (_i: Index) -> _Element { get } } + +/// This protocol is an implementation detail of `Comparable`; do +/// not use it directly. +/// +/// Its requirements are inherited by `Comparable` and thus must +/// be satisfied by types conforming to that protocol. protocol _Comparable { + + /// A `strict total order + /// `_ + /// over instances of `Self` func <(lhs: Self, rhs: Self) -> Bool } + +/// This protocol is an implementation detail of `ExtensibleCollectionType`; do +/// not use it directly. +/// +/// Its requirements are inherited by `ExtensibleCollectionType` and thus must +/// be satisfied by types conforming to that protocol. protocol _ExtensibleCollectionType : CollectionType { - /// Create an empty collection + /// Create an empty instance init() /// A non-binding request to ensure `n` elements of available storage. /// /// This works as an optimization to avoid multiple reallocations of - /// linear data structures like Array. Concrete implementations of - /// `ExtensibleCollectionType` may reserve more than `n`, exactly `n`, less - /// than `n` elements of storage, or even ignore the request completely. + /// linear data structures like `Array`. Conforming types may + /// reserve more than `n`, exactly `n`, less than `n` elements of + /// storage, or even ignore the request completely. mutating func reserveCapacity(n: Self.Index.Distance) - mutating func append(_: Self.Generator.Element) - mutating func extend(seq: S) + + /// Append `x` to `self`. + /// + /// Applying `successor()` to the index of the new element yields + /// `self.endIndex`. + /// + /// Complexity: amortized O(1). + mutating func append(x: Self.Generator.Element) + + /// Append the elements of `newElements` to `self`. + /// + /// Complexity: O(*length of result*) + /// + /// A possible implementation:: + /// + /// reserveCapacity(countElements(self) + underestimateCount(newElements)) + /// for x in newElements { + /// newElements.append(x) + /// } + mutating func extend(newElements: S) } + +/// This protocol is an implementation detail of `ForwardIndexType`; do +/// not use it directly. +/// +/// Its requirements are inherited by `ForwardIndexType` and thus must +/// be satisfied by types conforming to that protocol. protocol _ForwardIndexType : _Incrementable { + + /// A type that can represent the number of steps between pairs of + /// `Self` values where one value is reachable from the other. + /// + /// Reachability is defined by the ability to produce one value from + /// the other via zero or more applications of `successor`. typealias Distance : _SignedIntegerType = Int typealias _DisabledRangeIndex = _DisabledRangeIndex_ } + +/// This protocol is an implementation detail of `ForwardIndexType`; do +/// not use it directly. +/// +/// Its requirements are inherited by `ForwardIndexType` and thus must +/// be satisfied by types conforming to that protocol. protocol _Incrementable : Equatable { - /// Return the next consecutive value in a discrete sequence + /// Return the next consecutive value in a discrete sequence of + /// `Self` values + /// + /// Requires: `self` has a well-defined successor. func successor() -> Self } + +/// This protocol is an implementation detail of `IntegerArithmeticType`; do +/// not use it directly. +/// +/// Its requirements are inherited by `IntegerArithmeticType` and thus must +/// be satisfied by types conforming to that protocol. protocol _IntegerArithmeticType { + + /// Add `lhs` and `rhs`, returning a result and a `Bool` that is + /// true iff the operation caused an arithmetic overflow. class func addWithOverflow(lhs: Self, _ rhs: Self) -> (Self, overflow: Bool) + + /// Subtract `lhs` and `rhs`, returning a result and a `Bool` that is + /// true iff the operation caused an arithmetic overflow. class func subtractWithOverflow(lhs: Self, _ rhs: Self) -> (Self, overflow: Bool) + + /// Multiply `lhs` and `rhs`, returning a result and a `Bool` that is + /// true iff the operation caused an arithmetic overflow. class func multiplyWithOverflow(lhs: Self, _ rhs: Self) -> (Self, overflow: Bool) + + /// Divide `lhs` and `rhs`, returning a result and a `Bool` that is + /// true iff the operation caused an arithmetic overflow. class func divideWithOverflow(lhs: Self, _ rhs: Self) -> (Self, overflow: Bool) + + /// Divide `lhs` and `rhs`, returning the remainder and a `Bool` that is + /// true iff the operation caused an arithmetic overflow. class func remainderWithOverflow(lhs: Self, _ rhs: Self) -> (Self, overflow: Bool) } -protocol _IntegerType : IntegerLiteralConvertible, Printable, ArrayBoundType, Hashable, IntegerArithmeticType, BitwiseOperationsType, _Incrementable { + +/// This protocol is an implementation detail of `IntegerType`; do +/// not use it directly. +/// +/// Its requirements are inherited by `IntegerType` and thus must +/// be satisfied by types conforming to that protocol. +protocol _IntegerType : IntegerLiteralConvertible, Printable, Hashable, IntegerArithmeticType, BitwiseOperationsType, _Incrementable { } @@ -5472,61 +8766,152 @@ protocol _ObjectiveCBridgeable { class func _conditionallyBridgeFromObjectiveC(source: _ObjectiveCType, inout result: Self?) -> Bool } -protocol _PrintableNSObjectType { - var description: String! { get } - var debugDescription: String! { get } -} +/// This protocol is an implementation detail of `RandomAccessIndexType`; do +/// not use it directly. +/// +/// Its requirements are inherited by `RandomAccessIndexType` and thus must +/// be satisfied by types conforming to that protocol. protocol _RandomAccessIndexType : _BidirectionalIndexType, Strideable { - func distanceTo(_: Self) -> Self.Distance - func advancedBy(_: Self.Distance) -> Self + + /// Return the minimum number of applications of `successor` or + /// `predecessor` required to reach `other` from `self`. + /// + /// Complexity: O(1). + /// + /// Axioms:: + /// + /// x.distanceTo(x.successor())) == 1 + /// x.distanceTo(x.predecessor())) == -1 + /// x.advancedBy(x.distanceTo(y)) == y + func distanceTo(other: Self) -> Self.Distance + + /// Return `self` offset by `n` steps. + /// + /// :returns: If `n > 0`, the result of applying `successor` to + /// `self` `n` times. If `n < 0`, the result of applying + /// `predecessor` to `self` `-n` times. Otherwise, `self`. + /// + /// Complexity: O(1) + /// + /// Axioms:: + /// + /// x.advancedBy(0) == x + /// x.advancedBy(1) == x.successor() + /// x.advancedBy(-1) == x.predecessor() + /// x.distanceTo(x.advancedBy(m)) == m + func advancedBy(n: Self.Distance) -> Self } + +/// This protocol is an implementation detail of `RawOptionSetType`; do +/// not use it directly. +/// +/// Its requirements are inherited by `RawOptionSetType` and thus must +/// be satisfied by types conforming to that protocol. protocol _RawOptionSetType : RawRepresentable, Equatable { typealias RawValue : BitwiseOperationsType, Equatable init(rawValue: RawValue) } -/// The `for...in` loop operates on `SequenceType`\ s. It is -/// unspecified whether `for...in` consumes the sequence on which it -/// operates. +/// This protocol is an implementation detail of `SequenceType`; do +/// not use it directly. +/// +/// Its requirements are inherited by `SequenceType` and thus must +/// be satisfied by types conforming to that protocol. protocol _SequenceType { } + +/// This protocol is an implementation detail of `SequenceType`; do +/// not use it directly. +/// +/// Its requirements are inherited by `SequenceType` and thus must +/// be satisfied by types conforming to that protocol. protocol _Sequence_Type : _SequenceType { /// A type whose instances can produce the elements of this /// sequence, in order. typealias Generator : GeneratorType - /// Return a generator over the elements of this sequence. The - /// generator's next element is the first element of the sequence. + /// Return a *generator* over the elements of this *sequence*. The + /// *generator*\ 's next element is the first element of the + /// sequence. + /// + /// Complexity: O(1) func generate() -> Generator } + +/// This protocol is an implementation detail of `SignedIntegerType`; +/// do not use it directly. +/// +/// Its requirements are inherited by `SignedIntegerType` and thus +/// must be satisfied by types conforming to that protocol. protocol _SignedIntegerType : _IntegerType, SignedNumberType { + + /// Represent this number using Swift's widest native signed integer + /// type. func toIntMax() -> IntMax - class func from(_: IntMax) -> Self + + /// Convert from Swift's widest signed integer type, trapping on + /// overflow. + init(_: IntMax) } + +/// This protocol is an implementation detail of `SignedNumberType`; do +/// not use it directly. +/// +/// Its requirements are inherited by `SignedNumberType` and thus must +/// be satisfied by types conforming to that protocol. protocol _SignedNumberType : Comparable, IntegerLiteralConvertible { + + /// Return the difference between `lhs` and `rhs`. func -(lhs: Self, rhs: Self) -> Self } + +/// This protocol is an implementation detail of `Sliceable`; do +/// not use it directly. +/// +/// Its requirements are inherited by `Sliceable` and thus must +/// be satisfied by types conforming to that protocol. protocol _Sliceable : CollectionType { } -/// Base protocol for Strideable; allows the definition of < to be -/// inferred for Comparable conformance +/// This protocol is an implementation detail of `Strideable`; do +/// not use it directly. +/// +/// Its requirements are inherited by `Strideable` and thus must +/// be satisfied by types conforming to that protocol. protocol _Strideable { + + /// A type that can represent the distance between two values of `Self` typealias Stride : SignedNumberType - func distanceTo(_: Self) -> Stride - func advancedBy(_: Stride) -> Self + + /// Returns a stride `x` such that `self.advancedBy(x)` approximates + /// `other`. + /// + /// Complexity: O(1). + /// + /// See also: `RandomAccessIndexType`\ 's `distanceTo`, which provides a + /// stronger semantic guarantee. + func distanceTo(other: Self) -> Stride + + /// Returns a `Self` `x` such that `self.distanceTo(x)` approximates + /// `n`. + /// + /// Complexity: O(1). + /// + /// See also: `RandomAccessIndexType`\ 's `advancedBy`, which + /// provides a stronger semantic guarantee. + func advancedBy(n: Stride) -> Self } -protocol _SwiftNSArrayRequiredOverridesType : _SwiftNSCopyingType, _SwiftNSFastEnumerationType { +@unsafe_no_objc_tagged_pointer @objc protocol _SwiftNSArrayRequiredOverridesType : _SwiftNSCopyingType, _SwiftNSFastEnumerationType { func objectAtIndex(index: Int) -> AnyObject func getObjects(_: UnsafeMutablePointer, range: _SwiftNSRange) func countByEnumeratingWithState(state: UnsafeMutablePointer<_SwiftNSFastEnumerationState>, objects: UnsafeMutablePointer, count: Int) -> Int @@ -5534,15 +8919,15 @@ protocol _SwiftNSArrayRequiredOverridesType : _SwiftNSCopyingType, _SwiftNSFastE var count: Int { get } } -@unsafe_no_objc_tagged_pointer protocol _SwiftNSArrayType : _SwiftNSArrayRequiredOverridesType { +@unsafe_no_objc_tagged_pointer @objc protocol _SwiftNSArrayType : _SwiftNSArrayRequiredOverridesType { func indexOfObject(anObject: AnyObject) -> Int } -protocol _SwiftNSCopyingType { +@objc protocol _SwiftNSCopyingType { func copyWithZone(zone: _SwiftNSZone) -> AnyObject } -protocol _SwiftNSDictionaryRequiredOverridesType : _SwiftNSCopyingType, _SwiftNSFastEnumerationType { +@objc protocol _SwiftNSDictionaryRequiredOverridesType : _SwiftNSCopyingType, _SwiftNSFastEnumerationType { init(objects: UnsafePointer, forKeys: UnsafePointer, count: Int) var count: Int { get } func objectForKey(aKey: AnyObject?) -> AnyObject? @@ -5551,32 +8936,49 @@ protocol _SwiftNSDictionaryRequiredOverridesType : _SwiftNSCopyingType, _SwiftNS func countByEnumeratingWithState(state: UnsafeMutablePointer<_SwiftNSFastEnumerationState>, objects: UnsafeMutablePointer, count: Int) -> Int } -@unsafe_no_objc_tagged_pointer protocol _SwiftNSDictionaryType : _SwiftNSDictionaryRequiredOverridesType { +@unsafe_no_objc_tagged_pointer @objc protocol _SwiftNSDictionaryType : _SwiftNSDictionaryRequiredOverridesType { func getObjects(objects: UnsafeMutablePointer, andKeys keys: UnsafeMutablePointer) } -protocol _SwiftNSEnumeratorType { +@objc protocol _SwiftNSEnumeratorType { init() func nextObject() -> AnyObject? } -protocol _SwiftNSFastEnumerationType { +@objc protocol _SwiftNSFastEnumerationType { func countByEnumeratingWithState(state: UnsafeMutablePointer<_SwiftNSFastEnumerationState>, objects: UnsafeMutablePointer, count: Int) -> Int } -protocol _SwiftNSStringRequiredOverridesType : _SwiftNSCopyingType, _SwiftNSFastEnumerationType { +@objc protocol _SwiftNSStringRequiredOverridesType : _SwiftNSCopyingType, _SwiftNSFastEnumerationType { func length() -> Int func characterAtIndex(index: Int) -> UInt16 } -protocol _SwiftNSStringType : _SwiftNSStringRequiredOverridesType { +@objc protocol _SwiftNSStringType : _SwiftNSStringRequiredOverridesType { } + +/// This protocol is an implementation detail of `SignedIntegerType`; +/// do not use it directly. +/// +/// Its requirements are inherited by `SignedIntegerType` and thus +/// must be satisfied by types conforming to that protocol. protocol _UnsignedIntegerType : _IntegerType { + + /// Represent this number using Swift's widest native unsigned + /// integer type. func toUIntMax() -> UIntMax - class func from(_: UIntMax) -> Self + + /// Convert from Swift's widest unsigned integer type, trapping on + /// overflow. + init(_: UIntMax) } + +/// Return the absolute value of `x`. +/// +/// Concrete instances of `SignedNumberType` can specialize this +/// function by conforming to `AbsoluteValuable`. func abs(x: T) -> T @@ -5595,47 +8997,20 @@ func advance(start: T, n: T.Distance) -> T /// `BidirectionalIndexType`, requires that `n` is non-negative. func advance(start: T, n: T.Distance, end: T) -> T -func alignof(_: T.Type) -> Int - -func alignofValue(_: T) -> Int - - -/// Traditional C-style assert with an optional message. -/// -/// When assertions are enabled and `condition` is false, stop program -/// execution in a debuggable state after printing a message. When -/// assertions are disabled in release and fast builds, `condition` is not even -/// evaluated. -/// -/// When assertions are turned off, the optimizer can assume that the -/// `condition` is true. -func assert(condition: @autoclosure () -> Bool, _ message: StaticString = default, file: StaticString = default, line: UWord = default) - - -/// Traditional C-style assert with an optional message. -/// -/// When assertions are enabled and `condition` is false, stop program -/// execution in a debuggable state after printing a message. When -/// assertions are disabled in release and fast builds, `condition` is not even -/// evaluated. -/// -/// When assertions are turned off, the optimizer can assume that the -/// `condition` is true. -func assert(condition: @autoclosure () -> Bool, message: @autoclosure () -> Str, file: StaticString = default, line: UWord = default) +/// Returns the minimum memory alignment of `T`. +func alignof(_: T.Type) -> Int -/// Traditional C-style assert with an optional message. -/// -/// When assertions are enabled and `condition` is false, stop program -/// execution in a debuggable state after printing a message. When -/// assertions are disabled in release and fast builds, `condition` is not even -/// evaluated. -/// -/// When assertions are turned off, the optimizer can assume that the -/// `condition` is true. -func assert(condition: @autoclosure () -> T, message: @autoclosure () -> Str, file: StaticString = default, line: UWord = default) + +/// Returns the minimum memory alignment of `T`. +func alignofValue(_: T) -> Int +/// User code assertions. +/// +/// User code assertions and fatal errors are only enabled in debug mode. In +/// release or fast mode these checks are disabled. This means they may have no +/// effect on program semantics, depending on the assert configuration. /// Traditional C-style assert with an optional message. /// /// When assertions are enabled and `condition` is false, stop program @@ -5645,17 +9020,12 @@ func assert(condition: @autoclosure () /// /// When assertions are turned off, the optimizer can assume that the /// `condition` is true. -func assert(condition: @autoclosure () -> T, message: @autoclosure () -> Str, file: StaticString = default, line: UWord = default) - - -/// A fatal error occurred and program execution should stop in debug mode. In -/// optimized builds this is a noop. -@noreturn func assertionFailure(message: StaticString, file: StaticString = default, line: UWord = default) +func assert(condition: @autoclosure () -> Bool, _ message: @autoclosure () -> String = default, file: StaticString = default, line: UWord = default) /// A fatal error occurred and program execution should stop in debug mode. In /// optimized builds this is a noop. -@noreturn func assertionFailure(message: Str, file: StaticString = default, line: UWord = default) +@noreturn func assertionFailure(_ message: @autoclosure () -> String = default, file: StaticString = default, line: UWord = default) /// Return `true` iff `x` is in `seq`. @@ -5665,20 +9035,63 @@ func contains(seq: S, x: /// Return `true` iff an element in `seq` satisfies `predicate`. func contains(seq: S, predicate: (S.Generator.Element) -> L) -> Bool + +/// Equivalent to countElements(r) func count(r: Range) -> I.Distance -/// Return the number of elements in x. O(1) if T.Index is -/// RandomAccessIndexType; O(N) otherwise. +/// Return the number of elements in x. +/// +/// O(1) if T.Index is RandomAccessIndexType; O(N) otherwise. func countElements(x: T) -> T.Index.Distance -func debugPrint(object: T, inout target: TargetStream) -func debugPrint(object: T) +/// Write to `target` the textual representation of `x` most suitable +/// for debugging. +/// +/// * If `T` conforms to `DebugPrintable`, write `x.debugDescription` +/// * Otherwise, if `T` conforms to `Printable`, write `x.description` +/// * Otherwise, if `T` conforms to `Stramable`, write `x` +/// * Otherwise, fall back to a default textual representation. +/// +/// See also: `debugPrintln(x, &target)` +func debugPrint(x: T, inout target: TargetStream) + + +/// Write to the console the textual representation of `x` most suitable +/// for debugging. +/// +/// * If `T` conforms to `DebugPrintable`, write `x.debugDescription` +/// * Otherwise, if `T` conforms to `Printable`, write `x.description` +/// * Otherwise, if `T` conforms to `Stramable`, write `x` +/// * Otherwise, fall back to a default textual representation. +/// +/// See also: `debugPrintln(x)` +func debugPrint(x: T) + + +/// Write to `target` the textual representation of `x` most suitable +/// for debugging, followed by a newline. +/// +/// * If `T` conforms to `DebugPrintable`, write `x.debugDescription` +/// * Otherwise, if `T` conforms to `Printable`, write `x.description` +/// * Otherwise, if `T` conforms to `Stramable`, write `x` +/// * Otherwise, fall back to a default textual representation. +/// +/// See also: `debugPrint(x, &target)` +func debugPrintln(x: T, inout target: TargetStream) -func debugPrintln(object: T) -func debugPrintln(object: T, inout target: TargetStream) +/// Write to the console the textual representation of `x` most suitable +/// for debugging, followed by a newline. +/// +/// * If `T` conforms to `DebugPrintable`, write `x.debugDescription` +/// * Otherwise, if `T` conforms to `Printable`, write `x.description` +/// * Otherwise, if `T` conforms to `Stramable`, write `x` +/// * Otherwise, fall back to a default textual representation. +/// +/// See also: `debugPrint(x)` +func debugPrintln(x: T) /// Measure the distance between `start` and `end`. @@ -5693,11 +9106,13 @@ func distance(start: T, end: T) -> T.Distance /// Return a slice containing all but the first element of `s`. +/// /// Requires: `s` is non-empty. func dropFirst(s: Seq) -> Seq.SubSlice /// Return a slice containing all but the last element of `s`. +/// /// Requires: `s` is non-empty. func dropLast(s: S) -> S.SubSlice @@ -5709,51 +9124,81 @@ func dump(x: T, name: String? = default, indent: Int = default, maxDepth: Int /// Dump an object's contents using its mirror to the specified output stream. func dump(x: T, inout targetStream: TargetStream, name: String? = default, indent: Int = default, maxDepth: Int = default, maxItems: Int = default) -> T -func enumerate(seq: Seq) -> EnumerateGenerator + +/// Return a lazy `SequenceType` containing pairs (*n*, *x*), where +/// *n*\ s are consecutive `Int`\ s starting at zero, and *x*\ s are +/// the elements of `base`:: +/// +/// > for (n, c) in enumerate("Swift") { println("\(n): '\(c)'" )} +/// 0: 'S' +/// 1: 'w' +/// 2: 'i' +/// 3: 'f' +/// 4: 't' +func enumerate(base: Seq) -> EnumerateSequence + + +/// Return `true` iff `a1` and `a2` contain the same elements in the +/// same order. +func equal(a1: S1, a2: S2) -> Bool /// Return true iff `a1` and `a2` contain equivalent elements, using /// `isEquivalent` as the equivalence test. Requires: `isEquivalent` /// is an `equivalence relation -/// `__ +/// `_ func equal(a1: S1, a2: S2, isEquivalent: (S1.Generator.Element, S1.Generator.Element) -> Bool) -> Bool -/// Return true iff `a1` and `a2` contain the same elements. -func equal(a1: S1, a2: S2) -> Bool - - -/// Append elements from `newValues` to `x`. Complexity: +/// Append elements from `newElements` to `x`. Complexity: /// O(N) -func extend(inout x: C, newValues: S) - - -/// A fatal error occurred and program execution should stop in debug, -/// optimized and unchecked modes. -@noreturn func fatalError(message: Str, file: StaticString = default, line: UWord = default) +func extend(inout x: C, newElements: S) /// A fatal error occurred and program execution should stop in debug, /// optimized and unchecked modes. -@noreturn func fatalError(message: StaticString, file: StaticString = default, line: UWord = default) +@noreturn func fatalError(_ message: @autoclosure () -> String = default, file: StaticString = default, line: UWord = default) /// Return an `Array` containing the elements of `source`, /// in order, that satisfy the predicate `includeElement`. func filter(source: S, includeElement: (S.Generator.Element) -> Bool) -> [S.Generator.Element] + +/// Returns the first index where `value` appears in `domain` or `nil` if +/// `value` is not found. +/// +/// Complexity: O(\ `countElements(domain)`\ ) func find(domain: C, value: C.Generator.Element) -> C.Index? /// Returns the first element of `x`, or `nil` if `x` is empty. func first(x: C) -> C.Generator.Element? + +/// Returns a `CVaListPointer` built from `args` that's backed by +/// autoreleased storage. +/// +/// .. Warning:: This function is best avoided in favor of +/// `withVaList`, but occasionally (i.e. in a `class` initializer) you +/// may find that the language rules don't allow you to use +/// `withVaList` as intended. func getVaList(args: [CVarArgType]) -> CVaListPointer -func indices(seq: Seq) -> Range + +/// Return the range of `x` 's valid index values. +/// +/// The result's `endIndex` is the same as that of `x`. Because +/// `Range` is half-open, iterating the values of the result produces +/// all valid subscript arguments for `x`, omitting its `endIndex`. +func indices(x: C) -> Range -/// Insert an element at index `i` in O(N). +/// Insert `newElement` into `x` at index `i`. +/// +/// Invalidates all indices with respect to `x`. +/// +/// Complexity: O(\ `countElements(x)`\ ). func insert(inout x: C, newElement: C.Generator.Element, atIndex i: C.Index) @@ -5777,19 +9222,24 @@ func last(x: C) -> C. /// Augment `s` with lazy methods such as `map`, `filter`, etc. -func lazy(s: S) -> LazySequence +func lazy(s: S) -> LazyForwardCollection /// Augment `s` with lazy methods such as `map`, `filter`, etc. -func lazy(s: S) -> LazyRandomAccessCollection +func lazy(s: S) -> LazyBidirectionalCollection /// Augment `s` with lazy methods such as `map`, `filter`, etc. -func lazy(s: S) -> LazyBidirectionalCollection +func lazy(s: S) -> LazyRandomAccessCollection /// Augment `s` with lazy methods such as `map`, `filter`, etc. -func lazy(s: S) -> LazyForwardCollection +func lazy(s: S) -> LazySequence + + +/// Return true iff `a1` precedes `a2` in a lexicographical ("dictionary") +/// ordering, using `less` as the comparison between elements. +func lexicographicalCompare(a1: S1, a2: S2, less: (S1.Generator.Element, S1.Generator.Element) -> Bool) -> Bool /// Return true iff a1 precedes a2 in a lexicographical ("dictionary") @@ -5797,23 +9247,18 @@ func lazy(s: S) -> LazyForw func lexicographicalCompare(a1: S1, a2: S2) -> Bool -/// Return true iff `a1` precedes `a2` in a lexicographical ("dictionary") -/// ordering, using `less` as the comparison between elements. -func lexicographicalCompare(a1: S1, a2: S2, less: (S1.Generator.Element, S1.Generator.Element) -> Bool) -> Bool +/// Haskell's fmap for Optionals. +func map(x: T?, f: (T) -> U) -> U? /// Return an `Array` containing the results of mapping `transform` /// over `source`. -func map(source: S, transform: (S.Generator.Element) -> T) -> [T] +func map(source: C, transform: (C.Generator.Element) -> T) -> [T] /// Return an `Array` containing the results of mapping `transform` /// over `source`. -func map(source: C, transform: (C.Generator.Element) -> T) -> [T] - - -/// Haskell's fmap for Optionals. -func map(x: T?, f: (T) -> U) -> U? +func map(source: S, transform: (S.Generator.Element) -> T) -> [T] /// Return the greatest argument passed @@ -5829,24 +9274,60 @@ func max(x: T, y: T) -> T func maxElement(elements: R) -> R.Generator.Element -/// Return the least argument passed -func min(x: T, y: T, z: T, rest: T...) -> T - - /// Return the lesser of `x` and `y` func min(x: T, y: T) -> T +/// Return the least argument passed +func min(x: T, y: T, z: T, rest: T...) -> T + + /// Returns the minimum element in `elements`. Requires: /// `elements` is non-empty. O(countElements(elements)) func minElement(elements: R) -> R.Generator.Element + +/// Convert `x` to type `U`, trapping on overflow in -Onone and -O +/// builds. +/// +/// Typically used to do conversion to any contextually-deduced +/// integer type:: +/// +/// func f(x: Int32) {} +/// func g(x: UInt64) { f(numericCast(x)) } func numericCast(x: T) -> U + +/// Convert `x` to type `U`, trapping on overflow in -Onone and -O +/// builds. +/// +/// Typically used to do conversion to any contextually-deduced +/// integer type:: +/// +/// func f(x: UInt32) {} +/// func g(x: Int64) { f(numericCast(x)) } func numericCast(x: T) -> U + +/// Convert `x` to type `U`, trapping on overflow in -Onone and -O +/// builds. +/// +/// Typically used to do conversion to any contextually-deduced +/// integer type:: +/// +/// func f(x: UInt32) {} +/// func g(x: UInt64) { f(numericCast(x)) } func numericCast(x: T) -> U + +/// Convert `x` to type `U`, trapping on overflow in -Onone and -O +/// builds. +/// +/// Typically used to do conversion to any contextually-deduced +/// integer type:: +/// +/// func f(x: Int32) {} +/// func g(x: Int64) { f(numericCast(x)) } func numericCast(x: T) -> U @@ -5860,11 +9341,10 @@ func overlaps(l /// elements[`\ *j*\ `]) && !less(elements[`\ *j*\ `], elements[`\ /// *p*\ `])`. Only returns `range.endIndex` when `elements` is /// empty. -/// Requires: The less-than operator ('func <') defined in the Comparable -/// conformance is a `strict weak ordering +/// Requires: `isOrderedBefore` is a `strict weak ordering /// `__ /// over `elements`. -func partition(inout elements: C, range: Range) -> C.Index +func partition(inout elements: C, range: Range, isOrderedBefore: (C.Generator.Element, C.Generator.Element) -> Bool) -> C.Index /// Re-order the given `range` of `elements` and return a pivot index @@ -5873,34 +9353,11 @@ func partition`__ /// over `elements`. -func partition(inout elements: C, range: Range, isOrderedBefore: (C.Generator.Element, C.Generator.Element) -> Bool) -> C.Index - - -/// Ensure that the `condition` is true. -/// -/// If the `condition` is false, in debug and release modes the program stops. -/// -/// In unchecked mode the optimizer can assume that the `condition` is true. -func precondition(condition: @autoclosure () -> Bool, _ message: StaticString = default, file: StaticString = default, line: UWord = default) - - -/// Ensure that the `condition` is true. -/// -/// If the `condition` is false, in debug and release modes the program stops. -/// -/// In unchecked mode the optimizer can assume that the `condition` is true. -func precondition(condition: @autoclosure () -> Bool, message: @autoclosure () -> Str, file: StaticString = default, line: UWord = default) - - -/// Ensure that the `condition` is true. -/// -/// If the `condition` is false, in debug and release modes the program stops. -/// -/// In unchecked mode the optimizer can assume that the `condition` is true. -func precondition(condition: @autoclosure () -> T, message: @autoclosure () -> Str, file: StaticString = default, line: UWord = default) +func partition(inout elements: C, range: Range) -> C.Index /// Ensure that the `condition` is true. @@ -5908,23 +9365,22 @@ func precondition(condition: @autoclosu /// If the `condition` is false, in debug and release modes the program stops. /// /// In unchecked mode the optimizer can assume that the `condition` is true. -func precondition(condition: @autoclosure () -> T, message: @autoclosure () -> Str, file: StaticString = default, line: UWord = default) - - -/// A fatal error occurred and program execution should stop in debug mode and -/// in optimized mode. In unchecked builds this is a noop, but the -/// optimizer can still assume that the call is unreachable. -@noreturn func preconditionFailure(message: StaticString, file: StaticString = default, line: UWord = default) +func precondition(condition: @autoclosure () -> Bool, _ message: @autoclosure () -> String = default, file: StaticString = default, line: UWord = default) /// A fatal error occurred and program execution should stop in debug mode and /// in optimized mode. In unchecked builds this is a noop, but the /// optimizer can still assume that the call is unreachable. -@noreturn func preconditionFailure(message: Str, file: StaticString = default, line: UWord = default) +@noreturn func preconditionFailure(_ message: @autoclosure () -> String = default, file: StaticString = default, line: UWord = default) /// Return a slice, up to `maxLength` in length, containing the -/// initial elements of `s`. O(1)+K when `S.Index` conforms to +/// initial elements of `s`. +/// +/// If `maxLength` exceeds `countElements(s)`, the result contains all +/// the elements of `s`. +/// +/// Complexity: O(1)+K when `S.Index` conforms to /// `RandomAccessIndexType` and O(N)+K otherwise, where K is the cost /// of slicing `s`. func prefix(s: S, maxLength: Int) -> S.SubSlice @@ -5992,13 +9448,23 @@ func reduce(sequence: S, initial: U, combine: (U, S.Generat func reflect(x: T) -> MirrorType -/// Erase all the elements of `x`. `keepCapacity` is a non-binding -/// request to maintain allocated memory. Complexity: O(N) +/// Remove all elements from `x` +/// +/// Invalidates all indices with respect to `x`. +/// +/// :param: `keepCapacity`, if `true`, is a non-binding request to +/// avoid releasing storage, which can be a useful optimization +/// when `x` is going to be grown again. +/// +/// Complexity: O(\ `countElements(x)`\ ). func removeAll(inout x: C, keepCapacity: Bool = default) -/// Remove and return the element at the given index. Worst case complexity: -/// O(N). Requires: `index` < `count` +/// Remove from `x` and return the element at index `i` +/// +/// Invalidates all indices with respect to `x`. +/// +/// Complexity: O(\ `countElements(x)`\ ). func removeAtIndex(inout x: C, index: C.Index) -> C.Generator.Element @@ -6007,7 +9473,11 @@ func removeAtIndex(inout x: C, index: C.Inde func removeLast(inout x: C) -> C.Generator.Element -/// Remove the elements in the given subrange. Complexity: O(N) +/// Remove from `x` the indicated `subRange` of elements +/// +/// Invalidates all indices with respect to `x`. +/// +/// Complexity: O(\ `countElements(x)`\ ). func removeRange(inout x: C, subRange: Range) @@ -6015,62 +9485,83 @@ func removeRange(inout x: C, subRange: Range /// order. func reverse(source: C) -> [C.Generator.Element] -func sizeof(_: T.Type) -> Int -func sizeofValue(_: T) -> Int +/// Returns the contiguous memory footprint of `T`. +/// +/// Does not include any dynamically-allocated or "remote" storage. +/// In particular, `sizeof(X.self)`, when `X` is a class type, is the +/// same regardless of how many stored properties `X` has. +func sizeof(_: T.Type) -> Int -func sort(inout array: [T]) +/// Returns the contiguous memory footprint of `T`. +/// +/// Does not include any dynamically-allocated or "remote" storage. +/// In particular, `sizeof(a)`, when `a` is a class instance, is the +/// same regardless of how many stored properties `a` has. +func sizeofValue(_: T) -> Int -/// Sort `collection` in-placeaccording to 'isOrderedBefore'. -/// Requires: `isOrderedBefore` is a `strict weak ordering -/// `__ -/// over `elements`. -func sort(inout collection: C, isOrderedBefore: (C.Generator.Element, C.Generator.Element) -> Bool) +func sort(inout array: ContiguousArray) -func sort(inout array: [T], isOrderedBefore: (T, T) -> Bool) +func sort(inout array: [T]) /// Sort `collection` in-place. -/// Requires: The less-than operator ('func <') defined in the Comparable +/// +/// The sorting algorithm is not stable (can change the relative order of +/// elements that compare equal). +/// +/// Requires: The less-than operator (`func <`) defined in the `Comparable` /// conformance is a `strict weak ordering /// `__ /// over `elements`. func sort(inout collection: C) +func sort(inout array: ContiguousArray, isOrderedBefore: (T, T) -> Bool) -/// Return an `Array` containing the sorted elements of `source`according to 'isOrderedBefore'. -/// Requires: `isOrderedBefore` is a `strict weak ordering -/// `__ -/// over `elements`. -func sorted(source: C, isOrderedBefore: (C.Generator.Element, C.Generator.Element) -> Bool) -> [C.Generator.Element] +func sort(inout array: [T], isOrderedBefore: (T, T) -> Bool) -/// Return an `Array` containing the sorted elements of `source`. -/// Requires: The less-than operator ('func <') defined in the Comparable -/// conformance is a `strict weak ordering +/// Sort `collection` in-place according to `isOrderedBefore`. +/// +/// The sorting algorithm is not stable (can change the relative order of +/// elements for which `isOrderedBefore` does not establish an order). +/// +/// Requires: `isOrderedBefore` is a `strict weak ordering /// `__ /// over `elements`. -func sorted(source: C) -> [C.Generator.Element] +func sort(inout collection: C, isOrderedBefore: (C.Generator.Element, C.Generator.Element) -> Bool) -/// Return an `Array` containing the sorted elements of `source`. -/// Requires: The less-than operator ('func <') defined in the Comparable +/// Return an `Array` containing the sorted elements of `source`{according}. +/// +/// The sorting algorithm is not stable (can change the relative order of +/// elements that compare equal). +/// +/// Requires: The less-than operator (`func <`) defined in the `Comparable` /// conformance is a `strict weak ordering /// `__ /// over `elements`. -func sorted(source: C) -> C +func sorted(source: C) -> [C.Generator.Element] -/// Return an `Array` containing the sorted elements of `source`according to 'isOrderedBefore'. +/// Return an `Array` containing the sorted elements of `source`{according}. +/// +/// The sorting algorithm is not stable (can change the relative order of +/// elements for which `isOrderedBefore` does not establish an order). +/// /// Requires: `isOrderedBefore` is a `strict weak ordering /// `__ /// over `elements`. -func sorted(source: C, isOrderedBefore: (C.Generator.Element, C.Generator.Element) -> Bool) -> C +func sorted(source: C, isOrderedBefore: (C.Generator.Element, C.Generator.Element) -> Bool) -> [C.Generator.Element] -/// Insert the elements of `newValues` at index `i` -func splice(inout x: C, newValues: S, atIndex i: C.Index) +/// Insert `newElements` into `x` at index `i` +/// +/// Invalidates all indices with respect to `x`. +/// +/// Complexity: O(\ `countElements(x) + countElements(newElements)`\ ). +func splice(inout x: C, newElements: S, atIndex i: C.Index) /// Return the result of slicing `elements` into sub-sequences that @@ -6085,27 +9576,49 @@ func splice(elements: S, isSeparator: (S.Generator.Element) -> R, maxSplit: Int = default, allowEmptySlices: Bool = default) -> [S.SubSlice] -/// Return true iff the the initial elements of `s` are equal to `prefix`. -func startsWith(s: S0, prefix: S1) -> Bool - - /// Return true iff `s` begins with elements equivalent to those of /// `prefix`, using `isEquivalent` as the equivalence test. Requires: /// `isEquivalent` is an `equivalence relation -/// `__ +/// `_ func startsWith(s: S0, prefix: S1, isEquivalent: (S0.Generator.Element, S0.Generator.Element) -> Bool) -> Bool + +/// Return true iff the the initial elements of `s` are equal to `prefix`. +func startsWith(s: S0, prefix: S1) -> Bool + + +/// Return the sequence of values (`start`, `start + stride`, `start + +/// stride + stride`, ... *last*) where *last* is the last value in +/// the progression less than or equal to `end`. +/// +/// .. Note:: There is no guarantee that `end` is an element of the +/// sequence. func stride(from start: T, through end: T, by stride: T.Stride) -> StrideThrough + +/// Return the sequence of values (`start`, `start + stride`, `start + +/// stride + stride`, ... *last*) where *last* is the last value in +/// the progression that is less than `end`. func stride(from start: T, to end: T, by stride: T.Stride) -> StrideTo + +/// Returns the least possible interval between distinct instances of +/// `T` in memory. The result is always positive. func strideof(_: T.Type) -> Int + +/// Returns the least possible interval between distinct instances of +/// `T` in memory. The result is always positive. func strideofValue(_: T) -> Int /// Return a slice, up to `maxLength` in length, containing the -/// final elements of `s`. O(1)+K when `S.Index` conforms to +/// final elements of `s`. +/// +/// If `maxLength` exceeds `countElements(s)`, the result contains all +/// the elements of `s`. +/// +/// Complexity: O(1)+K when `S.Index` conforms to /// `RandomAccessIndexType` and O(N)+K otherwise, where K is the cost /// of slicing `s`. func suffix(s: S, maxLength: Int) -> S.SubSlice @@ -6122,6 +9635,13 @@ func toDebugString(x: T) -> String /// Returns the result of `print`\ 'ing `x` into a `String` func toString(x: T) -> String + +/// Translate `input`, in the given `InputEncoding`, into `output`, in +/// the given `OutputEncoding`. +/// +/// :param: `stopOnError` causes encoding to stop when an encoding +/// error is detected in `input`, if `true`. Otherwise, U+FFFD +/// replacement characters are inserted for each detected error. func transcode(inputEncoding: InputEncoding.Type, outputEncoding: OutputEncoding.Type, input: Input, output: Output, #stopOnError: Bool) -> (Bool) @@ -6137,13 +9657,26 @@ func underestimateCount(x: T) -> Int func unsafeAddressOf(object: AnyObject) -> UnsafePointer -/// A brutal bit-cast of something to anything of the same size +/// Returns the the bits of `x`, interpreted as having type `U`. +/// +/// .. Caution:: Breaks the guarantees of Swift's type system; use +/// with extreme care. There's almost always a better way to do +/// anything. +/// func unsafeBitCast(x: T, _: U.Type) -> U -/// Evaluate `f(x)` and return its result, ensuring that `x` is not -/// destroyed before f returns. -func withExtendedLifetime(x: T, f: (T) -> Result) -> Result +/// Returns: `x as T` +/// +/// Requires: `x is T`. In particular, in -O builds, no test is +/// performed to ensure that `x` actually has dynamic type `T`. +/// +/// .. Danger:: trades safety for performance. Use `unsafeDowncast` +/// only when `x as T` has proven to be a performance problem and you +/// are confident that, always, `x is T`. It is better than an +/// `unsafeBitCast` because it's more restrictive, and because +/// checking is still performed in debug builds. +func unsafeDowncast(x: AnyObject) -> T /// Evaluate `f()` and return its result, ensuring that `x` is not @@ -6151,6 +9684,11 @@ func withExtendedLifetime(x: T, f: (T) -> Result) -> Result func withExtendedLifetime(x: T, f: () -> Result) -> Result +/// Evaluate `f(x)` and return its result, ensuring that `x` is not +/// destroyed before f returns. +func withExtendedLifetime(x: T, f: (T) -> Result) -> Result + + /// Invokes `body` with an `UnsafeMutablePointer` to `arg` and returns the /// result. Useful for calling Objective-C APIs that take "in/out" /// parameters (and default-constructible "out" parameters) by pointer @@ -6180,41 +9718,37 @@ func withUnsafePointers(inout arg0: A0, inout arg1: A1, body: (U /// and `arg2`. func withUnsafePointers(inout arg0: A0, inout arg1: A1, inout arg2: A2, body: (UnsafePointer, UnsafePointer, UnsafePointer) -> Result) -> Result -func withVaList(args: [CVarArgType], f: (CVaListPointer) -> R) -> R +/// Invoke `f` with a C `va_list` argument derived from `builder`. func withVaList(builder: VaListBuilder, f: (CVaListPointer) -> R) -> R -func |(a: T, b: T) -> T - -func |(lhs: Bool, rhs: Bool) -> Bool - -func |(lhs: Int64, rhs: Int64) -> Int64 -func |(lhs: UInt8, rhs: UInt8) -> UInt8 +/// Invoke `f` with a C `va_list` argument derived from `args`. +func withVaList(args: [CVarArgType], f: (CVaListPointer) -> R) -> R -func |(lhs: Int8, rhs: Int8) -> Int8 +func |(lhs: Int, rhs: Int) -> Int -func |(lhs: UInt16, rhs: UInt16) -> UInt16 +func |(lhs: UInt, rhs: UInt) -> UInt -func |(lhs: Int16, rhs: Int16) -> Int16 +func |(lhs: Int64, rhs: Int64) -> Int64 -func |(lhs: UInt32, rhs: UInt32) -> UInt32 +func |(lhs: UInt64, rhs: UInt64) -> UInt64 func |(lhs: Int32, rhs: Int32) -> Int32 -func |(lhs: UInt64, rhs: UInt64) -> UInt64 +func |(lhs: UInt32, rhs: UInt32) -> UInt32 -func |(lhs: UInt, rhs: UInt) -> UInt +func |(lhs: Int16, rhs: Int16) -> Int16 -func |(lhs: Int, rhs: Int) -> Int +func |(lhs: UInt16, rhs: UInt16) -> UInt16 -func |=(inout lhs: Bool, rhs: Bool) +func |(lhs: Int8, rhs: Int8) -> Int8 -func |=(inout lhs: UInt8, rhs: UInt8) +func |(lhs: UInt8, rhs: UInt8) -> UInt8 -func |=(inout lhs: Int8, rhs: Int8) +func |(a: T, b: T) -> T -func |=(inout lhs: UInt16, rhs: UInt16) +func |(lhs: Bool, rhs: Bool) -> Bool func |=(inout lhs: Int16, rhs: Int16) @@ -6232,21 +9766,32 @@ func |=(inout lhs: Int, rhs: Int) func |=(inout lhs: T, rhs: T) -func ||(lhs: T, rhs: @autoclosure () -> U) -> Bool +func |=(inout lhs: UInt16, rhs: UInt16) + +func |=(inout lhs: Bool, rhs: Bool) -func ||(lhs: T, rhs: @autoclosure () -> Bool) -> Bool +func |=(inout lhs: UInt8, rhs: UInt8) -prefix func ~(rhs: Int) -> Int +func |=(inout lhs: Int8, rhs: Int8) -prefix func ~(rhs: UInt) -> UInt -prefix func ~(rhs: Int64) -> Int64 +/// If `lhs` is `true`, return it. Otherwise, evaluate `rhs` and +/// return its `boolValue`. +@inline(__always) func ||(lhs: T, rhs: @autoclosure () -> U) -> Bool -prefix func ~(rhs: UInt64) -> UInt64 +func ||(lhs: T, rhs: @autoclosure () -> Bool) -> Bool + +prefix func ~(rhs: UInt32) -> UInt32 + +prefix func ~(rhs: Int64) -> Int64 prefix func ~(rhs: Int32) -> Int32 -prefix func ~(rhs: UInt32) -> UInt32 +prefix func ~(rhs: UInt) -> UInt + +prefix func ~(rhs: UInt64) -> UInt64 + +prefix func ~(rhs: Int) -> Int prefix func ~(rhs: Int16) -> Int16 @@ -6254,17 +9799,17 @@ prefix func ~(rhs: UInt16) -> UInt16 prefix func ~(rhs: Int8) -> Int8 -prefix func ~(a: Bool) -> Bool - -prefix func ~(a: T) -> T - prefix func ~(rhs: UInt8) -> UInt8 -func ~=(a: T, b: T) -> Bool +prefix func ~(a: T) -> T -func ~=(lhs: _OptionalNilComparisonType, rhs: T?) -> Bool +prefix func ~(a: Bool) -> Bool /// Returns `true` iff `pattern` contains `value` func ~=(pattern: I, value: I.Bound) -> Bool +func ~=(a: T, b: T) -> Bool + +func ~=(lhs: _OptionalNilComparisonType, rhs: T?) -> Bool +