swift-mirror/stdlib/core/UnsafePointer.swift.gyb

//===--- UnsafePointer.swift.gyb ------------------------------*- swift -*-===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2014 - 2015 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See http://swift.org/LICENSE.txt for license information
// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
//===----------------------------------------------------------------------===//

%import gyb
%TMirrorDecl = gyb.parseTemplate("../common/MirrorDecl.gyb")
%TMirrorConformance = gyb.parseTemplate("../common/MirrorConformance.gyb")
%TMirrorBoilerplate = gyb.parseTemplate("../common/MirrorBoilerplate.gyb")

% for mutable in (True, False):
%  Self = 'UnsafePointer' if mutable else 'ConstUnsafePointer'
%  a_Self = 'an UnsafePointer' if mutable else 'a ConstUnsafePointer'
%  MirrorConformance = gyb.executeTemplate(TMirrorConformance,introspecteeType=Self,genericArgs=['T'],disposition='Struct')
%  MirrorDecl = gyb.executeTemplate(TMirrorDecl,introspecteeType=Self,genericArgs=['T'],disposition='Struct')
%  MirrorBoilerplate = gyb.executeTemplate(TMirrorBoilerplate,introspecteeType=Self,genericArgs=['T'],disposition='Struct')

/// This type stores a pointer to an object of type T. It provides no
/// automated memory management, and therefore the user must take care
/// to allocate and free memory appropriately.
public struct ${Self}<T> : BidirectionalIndex, Comparable, Hashable,
                            LogicValue, NilLiteralConvertible, _Pointer {
  /// The underlying raw (untyped) pointer.
  var value : Builtin.RawPointer

  /// Construct a null pointer.
  public init() {
    self.value = Builtin.inttoptr_Word(0.value)
  }

  /// Construct ${a_Self} from a builtin raw pointer.
  public init(_ value : Builtin.RawPointer) {
    self.value = value
  }

  /// Convert from an opaque C pointer to a typed pointer
  ///
  /// This is a fundamentally unsafe conversion.
  public init(_ other : COpaquePointer) {
    value = other.value
  }

  /// Construct ${a_Self} from a given address in memory.
  ///
  /// This is a fundamentally unsafe conversion.
  public init(_ value : Int) {
    self.value = Builtin.inttoptr_Word(value.value)
  }

  /// Convert from an UnsafePointer of a different type.
  ///
  /// This is a fundamentally unsafe conversion.
  public init<U>(_ from : UnsafePointer<U>) {
    value = from.value
  }

  /// Convert from a ConstUnsafePointer of a different type.
  ///
  /// This is a fundamentally unsafe conversion.
  public init<U>(_ from : ConstUnsafePointer<U>) {
    value = from.value
  }

  // Make nil work with ${Self}.
  @transparent public
  static func convertFromNilLiteral() -> ${Self}<T> {
    return .null()
  }

  public static func null() -> ${Self} {
    return ${Self}()
  }

%  if mutable:
  public static func alloc(num: Int) -> ${Self} {
    // Don't bother with overflow checking.
    var size = Int(Builtin.strideof(T.self)) * num
    return ${Self}(Builtin.allocRaw(size.value, Builtin.alignof(T.self)))
  }

  public func dealloc(num: Int) {
    // Overflow checking is actually not required here.
    var size = Int(Builtin.strideof(T.self)) * num
    Builtin.deallocRaw(value, size.value, Builtin.alignof(T.self))
  }
%  end

  /// Access the underlying raw memory, getting and
  /// setting values.
  public var memory : T {
    @transparent get {
      return Builtin.load(value)
    }
%  if mutable:
    @transparent nonmutating set {
      Builtin.assign(newValue, value)
    }
%  end
  }

%  if mutable:
  /// Initialize the value the pointer points to, to construct
  /// an object where there was no object previously stored.
  public func initialize(newvalue: T) {
    Builtin.initialize(newvalue, value)
  }

  /// Retrieve the value the pointer points to, moving it away
  /// from the location referenced in memory.
  ///
  /// Postcondition: The value has been destroyed and the memory must
  /// be initialized before being used again.
  public func move() -> T {
    return Builtin.take(value)
  }

  /// Move count values beginning at source into uninitialized memory,
  /// transforming the source values into raw memory, proceeding from
  /// the last value to the first.  Use this for copying ranges into
  /// later memory that may overlap with the source range.
  ///
  /// Requires: either `source` precedes `self` or follows `self + count`.
  public func moveInitializeBackwardFrom(source: ${Self}, count: Int) {
    _debugPrecondition(
      count >= 0, "${Self}.moveInitializeBackwardFrom with negative count")
    _debugPrecondition(
      source <= self || source > self + count,
      "${Self}.moveInitializeBackwardFrom non-preceding overlapping range; use moveInitializeFrom instead")
    var src = source + count
    var dst = self + count
    while dst != self {
      (--dst).initialize((--src).move())
    }
  }

  /// Assign from count values beginning at source into initialized
  /// memory, transforming the source values into raw memory.
  public func moveAssignFrom(source: ${Self}, count: Int) {
    _debugPrecondition(
      count >= 0, "moveAssignFrom with negative count")
    _debugPrecondition(
      source > self || source < self - count,
      "moveAssignFrom non-following overlapping range")
    for i in 0..<count {
      self[i] = (source + i).move()
    }
  }

  /// Move count values beginning at source into raw memory,
  /// transforming the source values into raw memory.
  public func moveInitializeFrom(source: ${Self}, count: Int) {
    _debugPrecondition(
      count >= 0, "${Self}.moveInitializeFrom with negative count")
    _debugPrecondition(
      source >= self || source < self - count,
      "${Self}.moveInitializeFrom non-following overlapping range; use moveInitializeBackwardFrom")
    for i in 0..<count {
      (self + i).initialize((source + i).move())
    }
  }

  /// Copy count values beginning at source into raw memory.
  public func initializeFrom(source: ${Self}, count: Int) {
    _debugPrecondition(
      count >= 0, "${Self}.initializeFrom with negative count")
    _debugPrecondition(
      source >= self || source < self - count,
      "${Self}.initializeFrom non-following overlapping range")
    for i in 0..<count {
      (self + i).initialize(source[i])
    }
  }

  /// Copy the elements of `C` into raw memory.
  public func initializeFrom<
    C: Collection where C._Element == T
  >(
    source: C
  ) {
    var p = self
    for x in source {
      // FIXME: <rdar://problem/16951692> We should be able to use a
      // C.GeneratorType.Element == T constraint here, because C._Element ==
      // C.GeneratorType.Element in all cases, but doing so crashes the
      // type-checker.
      p++.initialize(reinterpretCast(x))
    }
  }

  /// Destroy the object the pointer points to.
  public func destroy() {
    Builtin.destroy(T.self, value)
  }

  /// Destroy the `count` objects the pointer points to.
  public func destroy(count: Int) {
    _debugPrecondition(count >= 0, "${Self}.destroy with negative count")
    Builtin.destroyArray(T.self, value, count.value)
  }
%  end

  @transparent public
  var _isNull : Bool {
    return self == ${Self}.null()
  }

  @transparent public
  func getLogicValue() -> Bool {
    return !_isNull
  }

  public subscript (i : Int) -> T {
    @transparent
    get {
      return (self + i).memory
    }
%  if mutable:
    @transparent
    nonmutating set {
      (self + i).memory = newValue
    }
%  end
  }

% if mutable:
  /// If self was converted from nil, writes the result of invoking body into 
  /// the pointee
  public
  func _setIfNonNil(body: () -> T) {
    if self {
      memory = body()
    }
  }

  /// Return the result of invoking body.  If self was converted from
  /// nil, passes nil as the argument.  Otherwise, passes the address
  /// of a T which is written into buffer before this method returns
  @transparent public
  func _withBridgeObject<U: AnyObject, R>(
    inout buffer: U?, body: (AutoreleasingUnsafePointer<U?>)->R
  ) -> R {
    return self ? body(&buffer) : body(nil)
  }

  /// Return the result of invoking body.  If self was converted from
  /// nil, passes nil as the argument.  Otherwise, passes the address
  /// of buffer
  @transparent public
  func _withBridgeValue<U, R>(
    inout buffer: U, body: (UnsafePointer<U>)->R
  ) -> R {
    return self ? body(&buffer) : body(nil)
  }
% end

  //
  // Protocol conformance
  //
  public var hashValue: Int {
    return Int(Builtin.ptrtoint_Word(value))
  }
  public func successor() -> ${Self} {
    return self + 1
  }
  public func predecessor() -> ${Self} {
    return self - 1
  }
}

${MirrorDecl} {
  ${MirrorBoilerplate}
  
  public var count: Int { return 1 }
  
  func _getPointerValue() -> UInt64 {
    return UInt64(Int(Builtin.ptrtoint_Word(_value.value)))
  }

  public subscript(i: Int) -> (String, Mirror) {
    switch i {
    case 0: return ("pointerValue",reflect(_getPointerValue()))
    default: _preconditionFailure("cannot extract this child index")
    }
  }

  public var summary: String {
    let selfType = "${Self}"
    let ptrValue = _getPointerValue()
    if ptrValue == 0 { return "\(selfType)(nil)" }
    return "\(selfType)(0x\(_uint64ToString(ptrValue, radix:16, uppercase:true)))"
  }

  public var quickLookObject: QuickLookObject? { return .Some(.Text(summary)) }
}

${MirrorConformance}

@transparent public
func == <T> (lhs: ${Self}<T>, rhs: ${Self}<T>) -> Bool {
  return Bool(Builtin.cmp_eq_RawPointer(lhs.value, rhs.value))
}

@transparent public
func < <T>(lhs: ${Self}<T>, rhs: ${Self}<T>) -> Bool {
  return Bool(Builtin.cmp_ult_RawPointer(lhs.value, rhs.value))
}

@transparent public
func + <T>(lhs: ${Self}<T>, rhs: Int) -> ${Self}<T> {
  return ${Self}(
    Builtin.gep_Word(lhs.value, (rhs * Int(Builtin.strideof(T.self))).value))
}

@transparent public
func + <T>(lhs: Int,
           rhs: ${Self}<T>) -> ${Self}<T> {
  return rhs + lhs
}

@transparent public
func - <T>(lhs: ${Self}<T>, rhs: Int) -> ${Self}<T> {
  return lhs + -rhs
}

@transparent public
func - <T>(lhs: ${Self}<T>, rhs: ${Self}<T>) -> Int {
  return
    Int(Builtin.sub_Word(Builtin.ptrtoint_Word(lhs.value),
                         Builtin.ptrtoint_Word(rhs.value)))
    / Int(Builtin.strideof(T.self))
}

@transparent @assignment public
func += <T>(inout lhs: ${Self}<T>, rhs: Int) {
  lhs = lhs + rhs
}

@transparent @assignment public
func -= <T>(inout lhs: ${Self}<T>, rhs: Int) {
  lhs = lhs - rhs
}

extension ${Self} : Printable {
  public var description: String {
    return ""
  }
}
% end # for mutable

/// A byte-sized thing that isn't designed to interoperate with
/// any other types; it makes a decent parameter to UnsafePointer when
/// you just want to do bytewise pointer arithmetic.
public struct RawByte {
  let _inaccessible: UInt8
}

// ${'Local Variables'}:
// eval: (read-only-mode 1)
// End: