Class: Minisketch

Inherits:
Object
  • Object
show all
Extended by:
MinisketchFFI
Includes:
MinisketchFFI
Defined in:
lib/minisketch.rb,
lib/minisketch/version.rb

Overview

Minisketch class

Defined Under Namespace

Classes: Error

Constant Summary collapse

VERSION = 
"0.1.0"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(pointer) ⇒ Minisketch

Constructor

Parameters:

  • pointer (FFI::AutoPointer) —

    minisketch ffi pointer

Raises:



20
21
22
23
 
# File 'lib/minisketch.rb', line 20

def initialize(pointer)
  @pointer = pointer
  raise Error, "invalid parameter specified" if @pointer.address.zero?
end

Instance Attribute Details

#pointer ⇒ Object (readonly)

Returns the value of attribute pointer.



12
13
14
 
# File 'lib/minisketch.rb', line 12

def pointer
  @pointer
end

Class Method Details

.compute_capacity(bits, max_elements, fpbits) ⇒ Integer

Compute the capacity needed to achieve a certain rate of false positives.

Parameters:

  • Bits (Integer) —

    field size.

  • max_elements (Integer) —

    Intended number of elements that can be decoded max_elements

  • fpbits (Integer) —

    A false positive probability of 1 in 2**fpbits.

Returns:

  • (Integer) —

    capacity



59
60
61
 
# File 'lib/minisketch.rb', line 59

def self.compute_capacity(bits, max_elements, fpbits)
  minisketch_compute_capacity(bits, max_elements, fpbits)
end

.compute_max_elements(bits, capacity, fpbits) ⇒ Integer

Compute what max_elements can be decoded for a certain rate of false positives.

Parameters:

  • bits (Integer)
  • capacity (Integer)
  • fpbits (Integer)

Returns:

  • (Integer) —

    max elements



68
69
70
 
# File 'lib/minisketch.rb', line 68

def self.compute_max_elements(bits, capacity, fpbits)
  minisketch_compute_max_elements(bits, capacity, fpbits)
end

.create(bits, implementation, capacity) ⇒ Object

Create minisketch for a given element size, implementation and capacity.

Parameters:

  • bits (Integer)
  • implementation (Integer)
  • capacity (Integer)

Raises:



30
31
32
33
34
35
36
37
 
# File 'lib/minisketch.rb', line 30

def self.create(bits, implementation, capacity)
  pointer =
    FFI::AutoPointer.new(
      minisketch_create(bits, implementation, capacity),
      method(:minisketch_destroy)
    )
  Minisketch.new(pointer)
end

.implementation_max ⇒ Integer

Determine the maximum number of implementations available.

Returns:

  • (Integer) —

    maximum implementation.



41
42
43
 
# File 'lib/minisketch.rb', line 41

def self.implementation_max
  minisketch_implementation_max
end

.implementation_supported?(bits, implementation) ⇒ Boolean

Determine if the a combination of bits and implementation number is available.

Parameters:

  • bits (Integer)
  • implementation (Integer)

Returns:

  • (Boolean) 


49
50
51
52
 
# File 'lib/minisketch.rb', line 49

def self.implementation_supported?(bits, implementation)
  result = minisketch_implementation_supported(bits, implementation)
  result == 1
end

Instance Method Details

#add(element) ⇒ Object Also known as: <<

Add an element to a sketch.

Parameters:

  • element (Integer) 


132
133
134
 
# File 'lib/minisketch.rb', line 132

def add(element)
  minisketch_add_uint64(@pointer, element)
end

#bits ⇒ Integer

Get the element size of a sketch in bits.

Returns:

  • (Integer) 


74
75
76
 
# File 'lib/minisketch.rb', line 74

def bits
  minisketch_bits(@pointer)
end

#capacity ⇒ Integer

Get the capacity of a sketch.

Returns:

  • (Integer) 


80
81
82
 
# File 'lib/minisketch.rb', line 80

def capacity
  minisketch_capacity(@pointer)
end

#clone ⇒ Minisketch

Clone a sketch.

Returns:



98
99
100
101
102
103
104
105
 
# File 'lib/minisketch.rb', line 98

def clone
  pointer =
    FFI::AutoPointer.new(
      minisketch_clone(@pointer),
      method(:minisketch_destroy)
    )
  Minisketch.new(pointer)
end

#decode(max_len) ⇒ Array(Integer, Array(Integer))

Decode a sketch. After merging, sketch will contain every element that existed in one but not both of the input sketches. It can be seen as an exclusive or operation on the set elements. If the capacity of other_sketch is lower than sketch’s, merging reduces the capacity of sketch to that of other_sketch.

Parameters:

  • elements (Array(Integer))

Returns:

  • (Array(Integer, Array(Integer))) —

    Capacity of sketch after merging and decoded elements

Raises:



155
156
157
158
159
160
 
# File 'lib/minisketch.rb', line 155

def decode(max_len)
  ptr = FFI::MemoryPointer.new(:pointer, max_len)
  result = minisketch_decode(@pointer, max_len, ptr)
  raise Error, "sketch decoding failed" if result == -1
  [result, ptr.read_array_of_type(:uint64, :read_uint64, max_len)]
end

#deserialize(bytes) ⇒ Object

Deserialize a sketch from bytes.

Parameters:

  • bytes (String) 


124
125
126
127
128
 
# File 'lib/minisketch.rb', line 124

def deserialize(bytes)
  input = FFI::MemoryPointer.new(:uchar, bytes.bytesize).put_bytes(0, bytes)
  minisketch_deserialize(@pointer, input)
  self
end

#implementation ⇒ Integer

Get the implementation of a sketch.

Returns:

  • (Integer) 


86
87
88
 
# File 'lib/minisketch.rb', line 86

def implementation
  minisketch_implementation(@pointer)
end

#merge(other) ⇒ Object

Merge the elements of another sketch into this sketch.

Parameters:

Raises:



140
141
142
143
144
145
146
 
# File 'lib/minisketch.rb', line 140

def merge(other)
  unless other.is_a?(Minisketch)
    raise Error, "other must be Minisketch object"
  end
  capacity = minisketch_merge(@pointer, other.pointer)
  raise Error, "merge failed" if capacity.zero?
end

#serialize ⇒ String

Serialize a sketch to bytes.

Returns:

  • (String) 


115
116
117
118
119
120
 
# File 'lib/minisketch.rb', line 115

def serialize
  len = serialized_size
  output = FFI::MemoryPointer.new(:uchar, len)
  minisketch_serialize(@pointer, output)
  output.read_bytes(len)
end

#serialized_size ⇒ Integer

Compute the size in bytes for serializing a given sketch.

Returns:

  • (Integer) —

    sketch byte size.



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

def serialized_size
  minisketch_serialized_size(@pointer)
end

#set_seed(seed) ⇒ Object

Set the seed for randomizing algorithm choices to a fixed value.

Parameters:

  • seed (Integer) —

    64-bit integer



92
93
94
 
# File 'lib/minisketch.rb', line 92

def set_seed(seed) # rubocop:disable all
  minisketch_set_seed(@pointer, seed)
end