Skip to content

[stdlib] Various documentation fixes #5723

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 16, 2016
Merged

[stdlib] Various documentation fixes #5723

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
bd6025f
[stdlib] Various documentation fixes
natecook1000 Aug 12, 2016
7ca1c4b
[stdlib] Fix incorrect operator name
natecook1000 Nov 11, 2016
9b2128e
[stdlib] Add missing trivial type info to withUnsafeBytes
natecook1000 Nov 11, 2016
20ce99a
[stdlib] Fix example in String.CharacterView discussion
natecook1000 Nov 14, 2016
534bea8
[stdlib] Update revisions with feedback
natecook1000 Nov 15, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 114 additions & 67 deletions stdlib/public/core/Arrays.swift.gyb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ public struct _DependenceToken {}
%{
if True:
contiguousCaveat = (
' If no such storage exists, it is first created.' if Self == 'Array'
' If no such storage exists, it is created.' if Self == 'Array'
else '')

if Self == 'ContiguousArray':
Expand Down Expand Up @@ -397,7 +397,7 @@ if True:
/// Bridging Between Array and NSArray
/// ==================================
///
/// When you need to access APIs that expect data in an `NSArray` instance
/// When you need to access APIs that require data in an `NSArray` instance
/// instead of `Array`, use the type-cast operator (`as`) to bridge your
/// instance. For bridging to be possible, the `Element` type of your array
/// must be a class, an `@objc` protocol (a protocol imported from Objective-C
Expand All @@ -406,9 +406,9 @@ if True:
///
/// The following example shows how you can bridge an `Array` instance to
/// `NSArray` to use the `write(to:atomically:)` method. In this example, the
/// `colors` array can be bridged to `NSArray` because its `String` elements
/// bridge to `NSString`. The compiler prevents bridging the `moreColors`
/// array, on the other hand, because its `Element` type is
/// `colors` array can be bridged to `NSArray` because the `colors` array's
/// `String` elements bridge to `NSString`. The compiler prevents bridging the
/// `moreColors` array, on the other hand, because its `Element` type is
/// `Optional<String>`, which does *not* bridge to a Foundation type.
///
/// let colors = ["periwinkle", "rose", "moss"]
Expand All @@ -425,14 +425,23 @@ if True:
/// array's elements are already instances of a class or an `@objc` protocol;
/// otherwise, it takes O(*n*) time and space.
///
/// Bridging from `NSArray` to `Array` first calls the `copy(with:)`
/// When the destination array's element type is a class or an `@objc`
/// protocol, bridging from `NSArray` to `Array` first calls the `copy(with:)`
/// (`- copyWithZone:` in Objective-C) method on the array to get an immutable
/// copy and then performs additional Swift bookkeeping work that takes O(1)
/// time. For instances of `NSArray` that are already immutable, `copy(with:)`
/// usually returns the same array in O(1) time; otherwise, the copying
/// performance is unspecified. The instances of `NSArray` and `Array` share
/// storage using the same copy-on-write optimization that is used when two
/// instances of `Array` share storage.
/// performance is unspecified. If `copy(with:)` returns the same array, the
/// instances of `NSArray` and `Array` share storage using the same
/// copy-on-write optimization that is used when two instances of `Array`
/// share storage.
///
/// When the destination array's element type is a nonclass type that bridges
/// to a Foundation type, bridging from `NSArray` to `Array` performs a
/// bridging copy of the elements to contiguous storage in O(*n*) time. For
/// example, bridging from `NSArray` to `Array<Int>` performs such a copy. No
/// further bridging is required when accessing elements of the `Array`
/// instance.
///
/// - Note: The `ContiguousArray` and `ArraySlice` types are not bridged;
/// instances of those types always have a contiguous block of memory as
Expand Down Expand Up @@ -1135,24 +1144,31 @@ extension ${Self} : RangeReplaceableCollection, _ArrayProtocol {
return _getCount()
}

/// The total number of elements that the array can contain using its current
/// storage.
/// The total number of elements that the array can contain without
/// allocating new storage.
///
/// If the array grows larger than its capacity, it discards its current
/// storage and allocates a larger one.
/// Every array reserves a specific amount of memory to hold its contents.
/// When you add elements to an array and that array begins to exceed its
/// reserved capacity, the array allocates a larger region of memory and
/// copies its elements into the new storage. The new storage is a multiple
/// of the old storage's size. This exponential growth strategy means that
/// appending an element happens in constant time, averaging the performance
/// of many append operations. Append operations that trigger reallocation
/// have a performance cost, but they occur less and less often as the array
/// grows larger.
///
/// The following example creates an array of integers from an array literal,
/// then appends the elements of another collection. Before appending, the
/// array allocates new storage that is large enough store the resulting
/// elements.
///
/// var numbers = [10, 20, 30, 40, 50]
/// print("Count: \(numbers.count), capacity: \(numbers.capacity)")
/// // Prints "Count: 5, capacity: 5"
/// // numbers.count == 5
/// // numbers.capacity == 5
///
/// numbers.append(contentsOf: stride(from: 60, through: 100, by: 10))
/// print("Count: \(numbers.count), capacity: \(numbers.capacity)")
/// // Prints "Count: 10, capacity: 12"
/// // numbers.count == 10
/// // numbers.capacity == 12
public var capacity: Int {
return _getCapacity()
}
Expand Down Expand Up @@ -1184,13 +1200,19 @@ extension ${Self} : RangeReplaceableCollection, _ArrayProtocol {
/// unique, mutable, contiguous storage, with space allocated for at least
/// the requested number of elements.
///
/// For performance reasons, the newly allocated storage may be larger than
/// the requested capacity. Use the array's `capacity` property to determine
/// the size of the new storage.
% if Self != 'ContiguousArray':
/// Calling the `reserveCapacity(_:)` method on an array with bridged storage
/// triggers a copy to contiguous storage even if the existing storage
/// has room to store `minimumCapacity` elements.
///
% end
/// For performance reasons, the size of the newly allocated storage might be
/// greater than the requested capacity. Use the array's `capacity` property
/// to determine the size of the new storage.
///
/// - Parameter minimumCapacity: The requested number of elements to store.
///
/// - Complexity: O(*n*), where *n* is the count of the array.
/// - Complexity: O(*n*), where *n* is the number of elements in the array.
@_semantics("array.mutate_unknown")
public mutating func reserveCapacity(_ minimumCapacity: Int) {
if _buffer.requestUniqueMutableBackingBuffer(
Expand Down Expand Up @@ -1515,7 +1537,6 @@ extension ${Self} {

extension ${Self} {
/// Calls a closure with a pointer to the array's contiguous storage.
/// ${contiguousCaveat}
///
/// Often, the optimizer can eliminate bounds checks within an array
/// algorithm, but when that fails, invoking the same algorithm on the
Expand All @@ -1534,9 +1555,13 @@ extension ${Self} {
/// }
/// // 'sum' == 9
///
/// The pointer passed as an argument to `body` is valid only for the
/// lifetime of the closure. Do not escape it from the closure for later
/// use.
///
/// - Parameter body: A closure with an `UnsafeBufferPointer` parameter that
/// points to the contiguous storage for the array. If `body` has a return
/// value, it is used as the return value for the
/// points to the contiguous storage for the array. ${contiguousCaveat} If
/// `body` has a return value, it is used as the return value for the
/// `withUnsafeBufferPointer(_:)` method. The pointer argument is valid
/// only for the duration of the closure's execution.
/// - Returns: The return value of the `body` closure parameter, if any.
Expand All @@ -1549,13 +1574,13 @@ extension ${Self} {
}

/// Calls the given closure with a pointer to the array's mutable contiguous
/// storage.${contiguousCaveat}
/// storage.
///
/// Often, the optimizer can eliminate bounds checks within an array
/// algorithm, but when that fails, invoking the same algorithm on the
/// buffer pointer passed into your closure lets you trade safety for speed.
///
/// The following example shows modifying the contents of the
/// The following example shows how modifying the contents of the
/// `UnsafeMutableBufferPointer` argument to `body` alters the contents of
/// the array:
///
Expand All @@ -1568,16 +1593,21 @@ extension ${Self} {
/// print(numbers)
/// // Prints "[2, 1, 4, 3, 5]"
///
/// - Warning: Do not rely on anything about `self` (the array that is the
/// target of this method) during the execution of the `body` closure: It
/// may not appear to have its correct value. Instead, use only the
/// The pointer passed as an argument to `body` is valid only for the
/// lifetime of the closure. Do not escape it from the closure for later
/// use.
///
/// - Warning: Do not rely on anything about the array that is the target of
/// this method during execution of the `body` closure; it might not
/// appear to have its correct value. Instead, use only the
/// `UnsafeMutableBufferPointer` argument to `body`.
///
/// - Parameter body: A closure with an `UnsafeMutableBufferPointer`
/// parameter that points to the contiguous storage for the array. If
/// `body` has a return value, it is used as the return value for the
/// `withUnsafeMutableBufferPointer(_:)` method. The pointer argument is
/// valid only for the duration of the closure's execution.
/// parameter that points to the contiguous storage for the array.
/// ${contiguousCaveat} If `body` has a return value, it is used as the
/// return value for the `withUnsafeMutableBufferPointer(_:)` method. The
/// pointer argument is valid only for the duration of the closure's
/// execution.
/// - Returns: The return value of the `body` closure parameter, if any.
///
/// - SeeAlso: `withUnsafeBufferPointer`, `UnsafeMutableBufferPointer`
Expand Down Expand Up @@ -2099,28 +2129,42 @@ public func != <Element : Equatable>(
}

extension ${Self} {
/// Calls a closure with a view of the array's underlying bytes of memory as a
/// Collection of `UInt8`.
///
/// ${contiguousCaveat}
/// Calls the given closure with a pointer to the underlying bytes of the
/// array's mutable contiguous storage.
///
/// - Precondition: `Pointee` is a trivial type.
/// The array's `Element` type must be a *trivial type*, which can be copied
/// with just a bit-for-bit copy without any indirection or
/// reference-counting operations. Generally, native Swift types that do not
/// contain strong or weak references are trivial, as are imported C structs
/// and enums.
///
/// The following example shows how you copy bytes into an array:
/// The following example copies bytes from the `byteValues` array into
/// `numbers`, an array of `Int`:
///
/// var numbers = [Int32](repeating: 0, count: 2)
/// var byteValues: [UInt8] = [0x01, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00]
/// numbers.withUnsafeMutableBytes { destBytes in
/// byteValues.withUnsafeBytes { srcBytes in
/// destBytes.copyBytes(from: srcBytes)
/// }
/// }
/// var numbers: [Int32] = [0, 0]
/// var byteValues: [UInt8] = [0x01, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00]
///
/// - Parameter body: A closure with an `UnsafeRawBufferPointer`
/// parameter that points to the contiguous storage for the array. If `body`
/// has a return value, it is used as the return value for the
/// `withUnsafeMutableBytes(_:)` method. The argument is valid only for the
/// duration of the closure's execution.
/// numbers.withUnsafeMutableBytes { destBytes in
/// byteValues.withUnsafeBytes { srcBytes in
/// destBytes.copyBytes(from: srcBytes)
/// }
/// }
/// // numbers == [1, 2]
///
/// The pointer passed as an argument to `body` is valid only for the
/// lifetime of the closure. Do not escape it from the closure for later
/// use.
///
/// - Warning: Do not rely on anything about the array that is the target of
/// this method during execution of the `body` closure; it might not
/// appear to have its correct value. Instead, use only the
/// `UnsafeMutableRawBufferPointer` argument to `body`.
///
/// - Parameter body: A closure with an `UnsafeMutableRawBufferPointer`
/// parameter that points to the contiguous storage for the array.
/// ${contiguousCaveat} If `body` has a return value, it is used as the
/// return value for the `withUnsafeMutableBytes(_:)` method. The argument
/// is valid only for the duration of the closure's execution.
/// - Returns: The return value of the `body` closure parameter, if any.
///
/// - SeeAlso: `withUnsafeBytes`, `UnsafeMutableRawBufferPointer`
Expand All @@ -2132,30 +2176,33 @@ extension ${Self} {
}
}

/// Calls a closure with a view of the array's underlying bytes of memory
/// as a Collection of `UInt8`.
///
/// ${contiguousCaveat}
/// Calls the given closure with a pointer to the underlying bytes of the
/// array's contiguous storage.
///
/// - Precondition: `Pointee` is a trivial type.
/// The array's `Element` type must be a *trivial type*, which can be copied
/// with just a bit-for-bit copy without any indirection or
/// reference-counting operations. Generally, native Swift types that do not
/// contain strong or weak references are trivial, as are imported C structs
/// and enums.
///
/// The following example shows how you copy the contents of an array into a
/// The following example copies the bytes of the `numbers` array into a
/// buffer of `UInt8`:
///
/// let numbers = [1, 2, 3]
/// var byteBuffer = [UInt8]()
/// numbers.withUnsafeBytes {
/// byteBuffer += $0
/// }
/// var numbers = [1, 2, 3]
/// var byteBuffer: [UInt8] = []
/// numbers.withUnsafeBytes {
/// byteBuffer.append(contentsOf: $0)
/// }
/// // byteBuffer == [1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, ...]
///
/// - Parameter body: A closure with an `UnsafeRawBufferPointer` parameter
/// that points to the contiguous storage for the array. If `body` has a
/// return value, it is used as the return value for the
/// `withUnsafeBytes(_:)` method. The argument is valid only for the
/// duration of the closure's execution.
/// that points to the contiguous storage for the array.
/// ${contiguousCaveat} If `body` has a return value, it is used as the
/// return value for the `withUnsafeBytes(_:)` method. The argument is
/// valid only for the duration of the closure's execution.
/// - Returns: The return value of the `body` closure parameter, if any.
///
/// - SeeAlso: `withUnsafeBytes`, `UnsafeRawBufferPointer`
/// - SeeAlso: `withUnsafeMutableBytes`, `UnsafeRawBufferPointer`
public func withUnsafeBytes<R>(
_ body: (UnsafeRawBufferPointer) throws -> R
) rethrows -> R {
Expand Down
23 changes: 15 additions & 8 deletions stdlib/public/core/Bool.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,9 @@

/// A value type whose instances are either `true` or `false`.
///
/// `Bool` represents Boolean values in Swift. Create instances of
/// `Bool` by using one of the Boolean literals `true` and `false` or by
/// assigning the result of a Boolean method or operation to a variable or
/// constant.
/// `Bool` represents Boolean values in Swift. Create instances of `Bool` by
/// using one of the Boolean literals `true` or `false`, or by assigning the
/// result of a Boolean method or operation to a variable or constant.
///
/// var godotHasArrived = false
///
Expand All @@ -33,8 +32,8 @@
///
/// Swift uses only simple Boolean values in conditional contexts to help avoid
/// accidental programming errors and to help maintain the clarity of each
/// control statement. Unlike other programming languages, in Swift integers
/// and strings cannot be used where a Boolean value is expected.
/// control statement. Unlike in other programming languages, in Swift, integers
/// and strings cannot be used where a Boolean value is required.
///
/// For example, the following code sample does not compile, because it
/// attempts to use the integer `i` in a logical context:
Expand All @@ -52,13 +51,21 @@
/// print(i)
/// i -= 1
/// }
///
/// Using Imported Boolean values
/// =============================
///
/// The C `bool` and `Boolean` types and the Objective-C `BOOL` type are all
/// bridged into Swift as `Bool`. The single `Bool` type in Swift guarantees
/// that functions, methods, and properties imported from C and Objective-C
/// have a consistent type interface.
@_fixed_layout
public struct Bool {
internal var _value: Builtin.Int1

/// Creates an instance initialized to `false`.
///
/// Don't call this initializer directly. Instead, use the Boolean literal
/// Do not call this initializer directly. Instead, use the Boolean literal
/// `false` to create a new `Bool` instance.
@_transparent
public init() {
Expand All @@ -85,7 +92,7 @@ extension Bool : _ExpressibleByBuiltinBooleanLiteral, ExpressibleByBooleanLitera
///
/// Do not call this initializer directly. It is used by the compiler when
/// you use a Boolean literal. Instead, create a new `Bool` instance by
/// using one of the Boolean literals `true` and `false`.
/// using one of the Boolean literals `true` or `false`.
///
/// var printedMessage = false
///
Expand Down
7 changes: 4 additions & 3 deletions stdlib/public/core/Character.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ public struct Character :

/// Creates a character with the specified value.
///
/// Don't call this initializer directly. It is used by the compiler when you
/// Do not call this initializer directly. It is used by the compiler when you
/// use a string literal to initialize a `Character` instance. For example:
///
/// let snowflake: Character = "❄︎"
Expand Down Expand Up @@ -134,8 +134,9 @@ public struct Character :

/// Creates a character with the specified value.
///
/// Don't call this initializer directly. It is used by the compiler when you
/// use a string literal to initialize a `Character` instance. For example:
/// Do not call this initializer directly. It is used by the compiler when
/// you use a string literal to initialize a `Character` instance. For
/// example:
///
/// let oBreve: Character = "o\u{306}"
/// print(oBreve)
Expand Down
Loading