Class: KXI::Collections::Enumerable Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/kxi/collections/enumerable.rb

Overview

This class is abstract.
Note:

Order of items is not guaranteed

Allows it’s superclass to be enumerated

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Enumerable

Instantiates the KXI::Collections::Enumerable class



10
11
12
13
 
# File 'lib/kxi/collections/enumerable.rb', line 10

def initialize
	@locks = 0
	@alter = false
end

Instance Method Details

#aggregate(start = nil) {|current, item| ... } ⇒ Object

Aggregates all items of collection

Parameters:

  • start (Object, nil) (defaults to: nil) —

    Starting value

Yields:

  • (current, item) —

    Aggregation function

Yield Parameters:

  • current (Object) —

    Current aggregate

  • item (Object) —

    Item of collection

Yield Returns:

  • (Object) —

    Aggregated value

Returns:

  • (Object) —

    Aggregated value



315
316
317
318
319
320
 
# File 'lib/kxi/collections/enumerable.rb', line 315

def aggregate(start = nil)
	foreach do |item|
		start = yield(start, item)
	end
	return start
end

#all {|item| ... } ⇒ Bool

Checks if all items in collection satisfy given function

Yields:

  • (item) —

    Function used for checking

Yield Parameters:

  • item (Object) —

    Item of collection

Yield Returns:

  • (Bool) —

    True if item satisfies given function; otherwise false

Returns:

  • (Bool) —

    True if all items of collection satisfy given function; otherwise false



158
159
160
161
162
163
 
# File 'lib/kxi/collections/enumerable.rb', line 158

def all
	foreach do |item|
		return false unless yield(item)
	end
	return true
end

#any ⇒ Bool #any {|item| ... } ⇒ Bool

Checks if collection contains any item

Overloads:

  • #any ⇒ Bool

    Checks if collection is not empty

    Returns:

    • (Bool) —

      True if collection is not empty; otherwise false

  • #any {|item| ... } ⇒ Bool

    Checks if there is any item in collection that satisfies given function

    Yields:

    • (item) —

      Function used for checking

    Yield Parameters:

    • item (Object) —

      Item of collection

    Yield Returns:

    • (Bool) —

      True if item satisfies given function; otherwise false

    Returns:

    • (Bool) —

      True if collection contains item that satisfies given function; otherwise false

Returns:

  • (Bool) —

    True if collection contains any item; otherwise false



139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/kxi/collections/enumerable.rb', line 139

def any
	if block_given?
		foreach do |item|
			return true if yield(item)
		end
		return false
	else
		enumerator do |e|
			return false unless e.rewind
			return true
		end
	end
end

#can_alter? ⇒ Bool

Indicates whether collection can be altered

Returns:

  • (Bool) —

    True if collection can be altered; otherwise false



502
503
504
 
# File 'lib/kxi/collections/enumerable.rb', line 502

def can_alter?
	@locks == 0 and not @alter
end

#count ⇒ Number #count {|item| ... } ⇒ Number

Counts items in collection

Overloads:

  • #count ⇒ Number

    Counts the total number of items in collection

    Returns:

    • (Number) —

      Number of items in collection

  • #count {|item| ... } ⇒ Number

    Counts the number of items that satisfy given function

    Yields:

    • (item) —

      Function that evaluates whether item should be counted

    Yield Parameters:

    • item (Object) —

      Item of collection

    Yield Returns:

    • (Bool) —

      True if item should be counted; otherwise false

    Returns:

    • (Number) —

      Number of items that satisfy given function

Returns:

  • (Number) —

    Number of items



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/kxi/collections/enumerable.rb', line 110

def count
	count = 0
	if block_given?
		foreach do |item|
			count = count + 1 if yield(item)
		end
	else
		enumerator do |e|
			return 0 unless e.rewind
			count += 1
			while e.next
				count = count + 1
			end
		end
	end
	return count
end

#enumerator {|enumerator| ... } ⇒ nil

Allows protected usage of KXI::Collections::Enumerator within bounds of block

Yields:

Yield Parameters:

Yield Returns:

  • (void)

Returns:

  • (nil)

Raises:



21
22
23
24
25
26
 
# File 'lib/kxi/collections/enumerable.rb', line 21

def enumerator
	lock do
		yield(create_enumerator)
	end
	return nil
end

#first(df = nil) ⇒ Object? #first(df = nil) {|item| ... } ⇒ Object?

Gets first item, or default

Overloads:

  • #first(df = nil) ⇒ Object?

    Gets first item of collection

    Parameters:

    • df (Object, nil) (defaults to: nil) —

      Default value

    Returns:

    • (Object, nil) —

      First item of collection; default value if collection is empty

  • #first(df = nil) {|item| ... } ⇒ Object?

    Gets first item of collection that satisfies given function

    Parameters:

    • df (Object, nil) (defaults to: nil) —

      Default value

    Yields:

    • (item) —

      Function for evaluation

    Yield Parameters:

    • item (Object) —

      Item of collection

    Yield Returns:

    • (Bool) —

      True if item satisfies given function; false otherwise

    Returns:

    • (Object, nil) —

      First item of collection that satisfies given function; default value if no such item exists



177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/kxi/collections/enumerable.rb', line 177

def first(df = nil)
	if block_given?
		foreach do |item|
			return item if yield(item)
		end
	else
		enumerator do |e|
			return e.current if e.rewind
		end
	end
	return df
end

#first! ⇒ Object? #first! {|item| ... } ⇒ Object?

Gets first item

Overloads:

  • #first! ⇒ Object?

    Gets first item of collection

    Returns:

    • (Object, nil) —

      First item of collection

    Raises:

  • #first! {|item| ... } ⇒ Object?

    Gets first item of collection that satisfies given function

    Yields:

    • (item) —

      Function for evaluation

    Yield Parameters:

    • item (Object) —

      Item of collection

    Yield Returns:

    • (Bool) —

      True if item satisfies given function; false otherwise

    Returns:

    • (Object, nil) —

      First item of collection that satisfies given function

    Raises:

Raises:



203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/kxi/collections/enumerable.rb', line 203

def first!
	if block_given?
		foreach do |item|
			return item if yield(item)
		end
	else
		enumerator do |e|
			return e.current if e.rewind
		end
	end
	raise(KXI::Exceptions::CollectionException.new("Collection contains no #{(block_given? ? 'such ' : '')}items!"))
end

#foreach {|item| ... } ⇒ nil

Calls block with each item of collection

Yields:

  • (item) —

    Function that works with items of collection

Yield Parameters:

  • item (Object) —

    Item of collection

Yield Returns:

  • (Void)

Returns:

  • (nil) 


41
42
43
44
45
46
47
48
49
50
 
# File 'lib/kxi/collections/enumerable.rb', line 41

def foreach
	enumerator do |e|
		return nil unless e.rewind
		loop do
			yield(e.current)
			break unless e.next
		end
	end
	return nil
end

#last(df = nil) ⇒ Object? #last(df = nil) {|item| ... } ⇒ Object?

Gets last item, or default

Overloads:

  • #last(df = nil) ⇒ Object?

    Gets last item of collection

    Parameters:

    • df (Object, nil) (defaults to: nil) —

      Default value

    Returns:

    • (Object, nil) —

      Last item of collection; default value if collection is empty

  • #last(df = nil) {|item| ... } ⇒ Object?

    Gets last item of collection that satisfies given function

    Parameters:

    • df (Object, nil) (defaults to: nil) —

      Default value

    Yields:

    • (item) —

      Function for evaluation

    Yield Parameters:

    • item (Object) —

      Item of collection

    Yield Returns:

    • (Bool) —

      True if item satisfies given function; false otherwise

    Returns:

    • (Object, nil) —

      Last item of collection that satisfies given function; default value if no such item exists



228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/kxi/collections/enumerable.rb', line 228

def last(df = nil)
	found = false
	ret   = nil
	if block_given?
		foreach do |item|
			if yield(item)
				ret   = item
				found = true
			end
		end
	else
		foreach do |item|
			ret   = item
			found = true
		end
	end
	return df unless found
	return ret
end

#last! ⇒ Object? #last! {|item| ... } ⇒ Object?

Gets last item

Overloads:

  • #last! ⇒ Object?

    Gets last item of collection

    Returns:

    • (Object, nil) —

      Last item of collection

    Raises:

  • #last! {|item| ... } ⇒ Object?

    Gets last item of collection that satisfies given function

    Yields:

    • (item) —

      Function for evaluation

    Yield Parameters:

    • item (Object) —

      Item of collection

    Yield Returns:

    • (Bool) —

      True if item satisfies given function; false otherwise

    Returns:

    • (Object, nil) —

      Last item of collection that satisfies given function

    Raises:

Raises:



260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
 
# File 'lib/kxi/collections/enumerable.rb', line 260

def last!
	found = false
	ret   = nil
	if block_given?
		foreach do |item|
			if yield(item)
				ret   = item
				found = true
			end
		end
	else
		foreach do |item|
			ret   = item
			found = true
		end
	end
	raise(KXI::Exceptions::CollectionException.new("Collection contains no #{(block_given? ? 'such ' : '')}items!")) unless found
	return ret
end

#max ⇒ Object #max {|what, with| ... } ⇒ Object

Obtains item with the first maximal value

Overloads:

  • #max ⇒ Object

    Compares items using spaceship operator (<=>)

    Returns:

    • (Object) —

      Item with first maximal value; nil if collection is empty

  • #max {|what, with| ... } ⇒ Object

    Compares items using given comparison function

    Yields:

    • (what, with) —

      Comparison function

    Yield Parameters:

    • what (Object) —

      Object that is being compared

    • with (Object) —

      Object that is being compared to

    Yield Returns:

    • (Number) —

      Less then 0 if what < with, equal to 0 if what = with and bigger than 0 if what > with

    Returns:

    • (Object) —

      Item with first maximal value; nil if collection is empty



430
431
432
433
434
435
436
437
438
439
440
441
442
443
 
# File 'lib/kxi/collections/enumerable.rb', line 430

def max(&block)
	block = lambda { |a, b| a <=> b } if block == nil
	ret   = nil
	first = true
	foreach do |i|
		if first
			ret = i
			first = false
		elsif block.call(i, ret) > 0
			ret = i
		end
	end
	return ret
end

#min ⇒ Object #min {|what, with| ... } ⇒ Object

Obtains item with the first minimal value

Overloads:

  • #min ⇒ Object

    Compares items using spaceship operator (<=>)

    Returns:

    • (Object) —

      Item with first minimal value; nil if collection is empty

  • #min {|what, with| ... } ⇒ Object

    Compares items using given comparison function

    Yields:

    • (what, with) —

      Comparison function

    Yield Parameters:

    • what (Object) —

      Object that is being compared

    • with (Object) —

      Object that is being compared to

    Yield Returns:

    • (Number) —

      Less then 0 if what < with, equal to 0 if what = with and bigger than 0 if what > with

    Returns:

    • (Object) —

      Item with first minimal value; nil if collection is empty



456
457
458
459
460
461
462
463
464
465
466
467
468
469
 
# File 'lib/kxi/collections/enumerable.rb', line 456

def min(&block)
	block = lambda { |a, b| a <=> b } if block == nil
	ret   = nil
	first = true
	foreach do |i|
		if first
			ret = i
			first = false
		elsif block.call(i, ret) < 0
			ret = i
		end
	end
	return ret
end

#of_type(*klass) ⇒ KXI::Collections::ArrayCollection

Selects only those items that are of at least one of specified types

Parameters:

  • klass (Class) —

    Types to use for selection

Returns:

See Also:

  • Object#is_a?


389
390
391
392
393
394
395
396
397
398
399
400
 
# File 'lib/kxi/collections/enumerable.rb', line 389

def of_type(*klass)
	ret = []
	foreach do |i|
		klass.each do |k|
			if i.is_a?(k)
				ret.push(i)
				break
			end
		end
	end
	return KXI::Collections::ArrayCollection.new(ret)
end

#of_type!(*klass) ⇒ KXI::Collections::ArrayCollection

Selects only those items that are exactly of at least one of specified types

Parameters:

  • klass (Class) —

    Types to use for selection

Returns:

See Also:

  • Object#class


406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/kxi/collections/enumerable.rb', line 406

def of_type!(*klass)
	ret = []
	foreach do |i|
		klass.each do |k|
			if i.class == k
				ret.push(i)
				break
			end
		end
	end
	return KXI::Collections::ArrayCollection.new(ret)
end

#order_by ⇒ KXI::Collections::ArrayCollection #order_by {|what, with| ... } ⇒ KXI::Collections::ArrayCollection

Note:

Ordering is done using merge sort algorithm

Orders collection to ascending order

Overloads:

Returns:



335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
 
# File 'lib/kxi/collections/enumerable.rb', line 335

def order_by(&block)
	block  = lambda { |a, b| a <=> b } if block == nil
	groups = []
	g      = []
	foreach do |item|
		if g.length == 0
			g.push(item)
		else
			if block.call(g.last, item) <= 0
				g.push(item)
			else
				groups.push(g)
				g = [item]
			end
		end
	end
	groups.push(g) if g.length > 0
	return KXI::Collections::ArrayCollection.new if groups.length == 0
	while groups.length > 1
		merges = []
		while groups.length >= 2
			merges.push(merge(groups.shift, groups.shift, &block))
		end
		merges.push(groups[0]) if groups.length > 0
		groups = merges
	end
	return KXI::Collections::ArrayCollection.new(groups[0])
end

#order_by ⇒ KXI::Collections::ArrayCollection #order_by {|what, with| ... } ⇒ KXI::Collections::ArrayCollection

Note:

Ordering is done using merge sort algorithm

Orders collection to descending order

Overloads:

Returns:



377
378
379
380
381
382
383
 
# File 'lib/kxi/collections/enumerable.rb', line 377

def order_by_descending(&block)
	if block == nil
		return order_by { |a, b| b <=> a }
	else
		return order_by { |a, b| -block.call(a, b) }
	end
end

#select {|item| ... } ⇒ KXI::Collections::ArrayCollection

Selects specific values

Yields:

  • (item) —

    Function that selects values from items of collection

Yield Parameters:

  • item (Object) —

    Item of collection

Yield Returns:

  • (Object) —

    Selected value from item

Returns:



57
58
59
60
61
62
63
 
# File 'lib/kxi/collections/enumerable.rb', line 57

def select
	ret = []
	foreach do |i|
		ret.push(yield(i))
	end
	return KXI::Collections::ArrayCollection.new(ret)
end

#select_many {|item| ... } ⇒ KXI::Collections::ArrayCollection

Concatenates selected collections of items

Yields:

  • (item) —

    Function that selects collections of items from given items

Yield Parameters:

  • item (Object) —

    Item of collection

Yield Returns:

Returns:

Raises:



71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/kxi/collections/enumerable.rb', line 71

def select_many
	ret = []
	foreach do |i|
		col = yield(i)
		if col.is_a?(Array)
			col.each { |j| ret.push(j) }
		elsif col.is_a?(Enumerable)
			col.foreach { |j| ret.push(j) }
		else
			raise(KXI::Exceptions::CollectionException.new('Selection function returned invalid type of object!'))
		end
	end
	return KXI::Collections::ArrayCollection.new(ret)
end

#skip(count) ⇒ KXI::Collections::ArrayCollection

Skips given number of items and returns the rest

Parameters:

  • count (Number) —

    Number of items to skip

Returns:



283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/kxi/collections/enumerable.rb', line 283

def skip(count)
	ret = []
	foreach do |item|
		if count > 0
			count -= 1
		else
			ret.push(item)
		end
	end
	return KXI::Collections::ArrayCollection.new(ret)
end

#take(count) ⇒ KXI::Collections::ArrayCollection

Returns first N elements

Parameters:

  • count (Number) —

    Number of items to take

Returns:



298
299
300
301
302
303
304
305
306
 
# File 'lib/kxi/collections/enumerable.rb', line 298

def take(count)
	ret = []
	foreach do |item|
		break unless count > 0
		count -= 1
		ret.push(item)
	end
	return KXI::Collections::ArrayCollection.new(ret)
end

#to_array ⇒ Array

Coverts collection to array

Returns:

  • (Array) —

    Array equivalent to collection



473
474
475
476
477
 
# File 'lib/kxi/collections/enumerable.rb', line 473

def to_array
	ret = []
	foreach { |item| ret.push(item) }
	return ret
end

#where {|item| ... } ⇒ KXI::Collections::ArrayCollection

Selects only those items that satisfy given function

Yields:

  • (item) —

    Function that evaluates whether item should be selected

Yield Parameters:

  • item (Object) —

    Item of collection

Yield Returns:

  • (Bool) —

    True if item should be selected; otherwise false

Returns:



91
92
93
94
95
96
97
 
# File 'lib/kxi/collections/enumerable.rb', line 91

def where
	ret = []
	foreach do |i|
		ret.push(i) if yield(i)
	end
	return KXI::Collections::ArrayCollection.new(ret)
end