# mruby-set

`mruby-set` provides a `Set` class for mruby, offering a collection of unordered, unique elements. It's useful when you need to store a group of items and quickly check for membership, or perform set operations like union, intersection, and difference.

## Installation

To use `mruby-set` in your mruby project, add the following to your `build_config.rb`:

```ruby
conf.gem "#{MRUBY_ROOT}/mrbgems/mruby-set"
```

Or, if you have it as a separate gem:

```ruby
conf.gem :github => "mruby/mruby-set"
```

## Usage and Examples

### Creating a Set

You can create a set from an array or by using the `Set.[]` shorthand:

```ruby
require 'set' # Not strictly necessary in mruby if compiled in

set1 = Set.new([1, 2, 3])
#=> Set[1, 2, 3]

set2 = Set[3, 4, 5]
#=> Set[3, 4, 5]
```

### Adding and Deleting Elements

```ruby
s = Set.new
s.add(10)    #=> Set[10]
s << 20      #=> Set[10, 20]
s.add?(30)   #=> Set[10, 20, 30]
s.add?(20)   #=> nil (20 is already in the set)

s.delete(10) #=> Set[20, 30]
s.delete?(5) #=> nil (5 was not in the set)
s.delete?(20) #=> Set[30]
```

### Set Operations

`mruby-set` supports common set operations:

**Union (`|`, `+`, `union`):** Returns a new set containing all elements from both sets.

```ruby
set_a = Set[1, 2, 3]
set_b = Set[3, 4, 5]

set_a | set_b  #=> Set[1, 2, 3, 4, 5]
set_a + set_b  #=> Set[1, 2, 3, 4, 5]
```

**Intersection (`&`, `intersection`):** Returns a new set containing elements common to both sets.

```ruby
set_a = Set[1, 2, 3]
set_b = Set[3, 4, 5]

set_a & set_b  #=> Set[3]
```

**Difference (`-`, `difference`):** Returns a new set containing elements from the first set that are not in the second set.

```ruby
set_a = Set[1, 2, 3]
set_b = Set[3, 4, 5]

set_a - set_b  #=> Set[1, 2]
```

**Exclusive OR (`^`):** Returns a new set containing elements that are in one or the other of the sets, but not in both.

```ruby
set_a = Set[1, 2, 3]
set_b = Set[3, 4, 5]

set_a ^ set_b  #=> Set[1, 2, 4, 5]
```

### Querying the Set

**Checking for inclusion (`include?`, `member?`, `===`):**

```ruby
s = Set["apple", "banana", "cherry"]
s.include?("banana")  #=> true
s.member?("grape")    #=> false
```

**Checking size (`size`, `length`):**

```ruby
s = Set[10, 20, 30]
s.size #=> 3
```

**Checking if empty (`empty?`):**

```ruby
Set.new.empty? #=> true
Set[1].empty?  #=> false
```

**Subset and Superset (`subset?`, `superset?`, `<`, `<=`, `>`, `>=`):**

```ruby
set_main = Set[1, 2, 3, 4]
sub = Set[2, 3]
super_set = Set[1, 2, 3, 4, 5]

sub.subset?(set_main)         #=> true
set_main.superset?(sub)       #=> true
set_main < super_set          #=> true (proper subset)
super_set > set_main          #=> true (proper superset)
Set[1,2].proper_subset?(Set[1,2,3]) #=> true
Set[1,2,3].proper_superset?(Set[1,2]) #=> true
```

**Disjoint (`disjoint?`):** Returns `true` if the set has no elements in common with the given set.

```ruby
Set[1, 2].disjoint?(Set[3, 4]) #=> true
Set[1, 2].disjoint?(Set[2, 3]) #=> false
```

**Intersect (`intersect?`):** Returns `true` if the set has any elements in common with the given set.

```ruby
Set[1, 2].intersect?(Set[2, 3]) #=> true
Set[1, 2].intersect?(Set[3, 4]) #=> false
```

### Other Useful Methods

**Convert to Array (`to_a`):**

```ruby
s = Set["a", "b", "c"]
s.to_a #=> ["a", "b", "c"] (order may vary)
```

**Iterating (`each`):**

```ruby
s = Set[1, 2, 3]
s.each { |x| puts x * 10 }
# Output:
# 10
# 20
# 30
```

**Map/Collect (`map!`, `collect!`):** Modifies the set by applying the block to each element.

```ruby
s = Set[1, 2, 3]
s.map! { |x| x * x } #=> Set[1, 4, 9]
```

**Select/Filter (`select!`, `filter!`):** Keeps elements for which the block returns true.

```ruby
s = Set[1, 2, 3, 4, 5]
s.select! { |x| x.even? } #=> Set[2, 4]
```

**Reject (`reject!`):** Deletes elements for which the block returns true.

```ruby
s = Set[1, 2, 3, 4, 5]
s.reject! { |x| x.odd? } #=> Set[2, 4]
```

**Clear (`clear`):** Removes all elements from the set.

```ruby
s = Set[1, 2, 3]
s.clear #=> Set[]
```

**Replace (`replace`):** Replaces the contents of the set with the contents of the given enumerable.

```ruby
s = Set[1, 2, 3]
s.replace([4, 5]) #=> Set[4, 5]
```

**Flatten (`flatten`, `flatten!`):** Returns a new set that is a copy of the set, flattening any nested sets. `flatten!` modifies the set in place.

```ruby
s = Set[1, Set[2, 3], 4]
s.flatten #=> Set[1, 2, 3, 4]
```

## Method Overview

Here's a list of commonly used methods available in `mruby-set`:

- `Set.[](*ary)`
- `initialize(enum = nil, &block)`
- `size`, `length`
- `empty?`
- `clear`
- `replace(enum)`
- `to_a`
- `include?(o)`, `member?(o)`, `===`
- `superset?(set)`, `>=`
- `proper_superset?(set)`, `>`
- `subset?(set)`, `<=`
- `proper_subset?(set)`, `<`
- `intersect?(set)`
- `disjoint?(set)`
- `each(&block)`
- `add(o)`, `<<(o)`
- `add?(o)`
- `delete(o)`
- `delete?(o)`
- `delete_if { |o| ... }`
- `keep_if { |o| ... }`
- `collect! { |o| ... }`, `map! { |o| ... }`
- `reject! { |o| ... }`
- `select! { |o| ... }`, `filter! { |o| ... }`
- `merge(enum)`
- `subtract(enum)`
- `|(enum)`, `+(enum)`, `union(enum)`
- `-(enum)`, `difference(enum)`
- `&(enum)`, `intersection(enum)`
- `^(enum)`
- `==(other)`
- `hash`
- `eql?(o)`
- `classify { |o| ... }`
- `divide(&func)`
- `join(separator = nil)`
- `inspect`, `to_s`
- `flatten`, `flatten!`

## Limitations

These methods are not implemented yet:

- freeze
- to_set
- divide(Set#divide with 2 arity block is not implemented.)

## License

Under the MIT License:

- see [LICENSE](LICENSE) file