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

Instance Attribute Summary

Attributes inherited from Base

#ptr

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

check_cftype, #eql?, #equals?, finalize, #hash, #initialize, #null?, #to_cf, typecast

Methods included from Memory

#inspect, #release, #retain, #to_ptr

Methods included from Register

included, #register_type

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))
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)
  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) 


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

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))
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
 
# 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)
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)
  end
  CF.CFArrayApplyFunction(self, range, callback, nil)
  self
end

#length ⇒ Integer Also known as: size

Returns the number of elements the array contains

Returns:

  • (Integer) 


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

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



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

def to_ruby
  collect(&:to_ruby)
end