Class: CF::Array

Inherits:
Base
  • Object
show all
Includes:
Enumerable
Defined in:
lib/corefoundation/array.rb

Overview

Wrapper class for CFArrayRef. It implements enumberable so you can use a lot of your favourite ruby methods on it.

Values returned by the accessor methods or yielded by the block are retained and marked as releasable on garbage collection This means you can safely use the returned values even if the CFArray itself has been destroyed

Unlike ruby arrays you cannot set arbitary array indexes - You can only set indexes in the range 0..length

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

check_cftype, #eql?, #equals?, #hash, #initialize, #inspect, #null?, #ptr=, #release, #release_on_gc, #retain, #to_cf, #to_ptr, typecast

Constructor Details

This class inherits a constructor from CF::Base

Class Method Details

.immutable(array) ⇒ CF::Array

Creates a new, immutable CFArray from a ruby array of cf objects

Parameters:

  • array (Array<CF::Base>) —

    The objects to place in the array. They must inherit from CF::Base

Returns:

  • (CF::Array) —

    A CF::Array containing the objects, setup to release the array upon garbage collection



61
62
63
64
65
66
67
68
 
# File 'lib/corefoundation/array.rb', line 61

def self.immutable(array)
  if bad_element = array.detect {|value| !value.is_a?(CF::Base)}
    raise TypeError, "Array contains non cftype #{bad_element.inspect}" 
  end
  m = FFI::MemoryPointer.new(:pointer, array.length)
  m.write_array_of_pointer(array)
  new(CF.CFArrayCreate(nil,m,array.length,CF::kCFTypeArrayCallBacks.to_ptr)).release_on_gc
end

.mutable ⇒ CF::Array

Creates a new, empty mutable CFArray

Returns:

  • (CF::Array) —

    A mutable CF::Array containing the objects, setup to release the array upon garbage collection



72
73
74
75
76
 
# File 'lib/corefoundation/array.rb', line 72

def self.mutable
  result = new(CF.CFArrayCreateMutable nil, 0, CF::kCFTypeArrayCallBacks.to_ptr).release_on_gc
  result.instance_variable_set(:@mutable, true)
  result
end

Instance Method Details

#<<(value) ⇒ CF::Array Also known as: push

Appends a value to the array

Returns:

Raises:

  • (TypeError) 


101
102
103
104
105
106
 
# File 'lib/corefoundation/array.rb', line 101

def <<(value)
  raise TypeError, "instance is not mutable" unless mutable?
  self.class.check_cftype(value)
  CF.CFArrayAppendValue(self, value)
  self
end

#[](index) ⇒ CF::Base

Returns the object at the index

Parameters:

  • index (Integer) —

    the 0 based index of the item to retrieve. Behaviour is undefined if it is not in the range 0…size

Returns:



81
82
83
 
# File 'lib/corefoundation/array.rb', line 81

def [](index)
  Base.typecast(CF.CFArrayGetValueAtIndex(self, index)).retain.release_on_gc
end

#[]=(index, value) ⇒ CF::Base

Sets object at the index

Parameters:

  • index (Integer) —

    the 0 based index of the item to retrieve. Behaviour is undefined if it is not in the range 0..size It is legal to set the value at index n of a n item array - this is equivalent to appending the object

  • value (CF::Base) —

    the value to store

Returns:

Raises:

  • (TypeError) 


91
92
93
94
95
96
 
# File 'lib/corefoundation/array.rb', line 91

def []=(index, value)
  raise TypeError, "instance is not mutable" unless mutable?
  self.class.check_cftype(value)
  CF.CFArraySetValueAtIndex(self, index, value)
  value
end

#each ⇒ Object

Iterates over the array yielding the value to the block The value is wrapped in the appropriate CF::Base subclass and retained (but marked for releasing upon garbage collection)

Returns:

  • self



47
48
49
50
51
52
53
54
55
56
 
# File 'lib/corefoundation/array.rb', line 47

def each
  range = CF::Range.new
  range[:location] = 0
  range[:length] = length
  callback = lambda do |value, _|
    yield Base.typecast(value).retain.release_on_gc
  end
  CF.CFArrayApplyFunction(self, range, callback, nil)
  self
end

#length ⇒ Integer Also known as: size

Returns the number of elements the array contains

Returns:



118
119
120
 
# File 'lib/corefoundation/array.rb', line 118

def length
  CF.CFArrayGetCount(self)
end

#mutable? ⇒ Boolean

Whether the array is mutable

WARNING: this only works for arrays created by CF::Array, there is no public api for telling whether an arbitrary CFTypeRef is a mutable array or not

Returns:



40
41
42
 
# File 'lib/corefoundation/array.rb', line 40

def mutable?
  @mutable
end

#to_ruby ⇒ Object

Returns a ruby array containing the result of calling to_ruby on each of the array’s elements



110
111
112
 
# File 'lib/corefoundation/array.rb', line 110

def to_ruby
  collect(&:to_ruby)
end