Skip to content

Fixups for UnsafePointer documentation #5994

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 3 commits into from
Dec 2, 2016
Merged

Fixups for UnsafePointer documentation #5994

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3d0d3e1
[docs] Add GEP preconditions to UnsafePointer.
Nov 30, 2016
8e4f98f
[docs] downgrade internal notes to normal comments.
Nov 30, 2016
ff82c1e
[docs] Change argument name to match docs.
Nov 30, 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
36 changes: 25 additions & 11 deletions stdlib/public/core/UnsafePointer.swift.gyb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -432,21 +432,29 @@ public struct ${Self}<Pointee>
}

/// Returns the next consecutive position.
///
/// - Precondition: The result is within the bounds of the same allocation.
public func successor() -> ${Self} {
return self + 1
}

/// Returns the previous consecutive position.
///
/// - Precondition: The result is within the bounds of the same allocation.
public func predecessor() -> ${Self} {
return self - 1
}

/// Returns `end - self`.
public func distance(to x: ${Self}) -> Int {
return x - self
///
/// - Precondition: The result is within the bounds of the same allocation.
public func distance(to end: ${Self}) -> Int {
return end - self
}

/// Returns `self + n`.
///
/// - Precondition: The result is within the bounds of the same allocation.
public func advanced(by n: Int) -> ${Self} {
return self + n
}
Expand Down Expand Up @@ -478,39 +486,43 @@ extension ${Self} : CustomPlaygroundQuickLookable {
}
}

/// - Note: Strideable's implementation is potentially less efficient and cannot
/// handle misaligned pointers.
// - Note: Strideable's implementation is potentially less efficient and cannot
// handle misaligned pointers.
@_transparent
public func == <Pointee>(
lhs: ${Self}<Pointee>, rhs: ${Self}<Pointee>
) -> Bool {
return Bool(Builtin.cmp_eq_RawPointer(lhs._rawValue, rhs._rawValue))
}

/// - Note: Strideable's implementation is potentially less efficient and cannot
/// handle misaligned pointers.
///
/// - Note: This is an unsigned comparison unlike Strideable's implementation.
// - Note: Strideable's implementation is potentially less efficient and cannot
// handle misaligned pointers.
//
// - Note: This is an unsigned comparison unlike Strideable's implementation.
@_transparent
public func < <Pointee>(lhs: ${Self}<Pointee>, rhs: ${Self}<Pointee>) -> Bool {
return Bool(Builtin.cmp_ult_RawPointer(lhs._rawValue, rhs._rawValue))
}

/// - Note: The following family of operator overloads are redundant
/// with Strideable. However, optimizer improvements are needed
/// before they can be removed without affecting performance.
// - Note: The following family of operator overloads are redundant
// with Strideable. However, optimizer improvements are needed
// before they can be removed without affecting performance.

/// - Precondition: The result is within bounds of the same allocation.
@_transparent
public func + <Pointee>(lhs: ${Self}<Pointee>, rhs: Int) -> ${Self}<Pointee> {
return ${Self}(Builtin.gep_Word(
lhs._rawValue, rhs._builtinWordValue, Pointee.self))
}

/// - Precondition: The result is within the bounds of the same allocation.
@_transparent
public func + <Pointee>(lhs: Int,
rhs: ${Self}<Pointee>) -> ${Self}<Pointee> {
return rhs + lhs
}

/// - Precondition: The result is within the bounds of the same allocation.
@_transparent
public func - <Pointee>(lhs: ${Self}<Pointee>, rhs: Int) -> ${Self}<Pointee> {
return lhs + -rhs
Expand All @@ -524,11 +536,13 @@ public func - <Pointee>(lhs: ${Self}<Pointee>, rhs: ${Self}<Pointee>) -> Int {
/ MemoryLayout<Pointee>.stride
}

/// - Precondition: The result is within the bounds of the same allocation.
@_transparent
public func += <Pointee>(lhs: inout ${Self}<Pointee>, rhs: Int) {
lhs = lhs + rhs
}

/// - Precondition: The result is within the bounds of the same allocation.
@_transparent
public func -= <Pointee>(lhs: inout ${Self}<Pointee>, rhs: Int) {
lhs = lhs - rhs
Expand Down