- Update some docs on methods of `Str`

- Add two nuw objects `MSet` and `MBag` which are mutable `Set`s and `Bag`s repsectively
- Update some docs on methods of `Array`

docs/maat_dev_ref/maat.md

@@ -307,7 +307,9 @@ each types here.
 - Array
 - Map
 - Set
+- MSet
 - Bag
+- MBag
 - Fun
 - File
 - Dir
@@ -320,6 +322,7 @@ each types here.
 - Supply
 - Work
 - Lazy
+- Term
 
 # Flow control
 

docs/maat_dev_ref/objects/Array.md

@@ -11,7 +11,7 @@ var b = ["kueppo", "cyrus", "christ"]
 var c = Array.new(2, 3, "four", a<5 6>)
 
 .say for a.lmap(.split) -- a{l i z a m a d j o u m o n t h e}
-.say for a.map(.split) -- a{l i z a}, a{m a d j o u}, a{m o n t h e}
+.say for a.map(.split)  -- a{l i z a}, a{m a d j o u}, a{m o n t h e}
 ```
 
 ## Methods
@@ -31,33 +31,37 @@ Let `a` be a variable containing an object of type `Array`, `a` has the followin
 methods:
 
 - `a.len -> Num`: Return the number of elements in `a`
-- `a.of()`: Tell us `of` what type are the elements of `a`
-- `a.clone()`: Clone object in `a` into a new fresh one and return it
+- `a.of -> ` Tell us `of` what type are the elements of `a`
+- `a.clone`: Clone object in `a` into a new fresh one and return it
 - `a.min -> Any`: Return the minimum element in `a` based on numeric comparison
 - `a.minstr -> Any`: Return the minimum element in `a` based on stringwise comparison
 - `a.max -> Any`: Return the maximum element in `a` based on numeric comparison
 - `a.maxstr -> Any`: Return the maximum element in `a` based on stringwise comparison
-- `a.cmp(Array b) -> Num`: 
 - `a.end -> Any`: Return the index of the last element in `a`
-- `a.minmax -> Array`: Return two element in the list, first the the maxinum and second in the minimum both in `a` (Completely different from infix `minmax` operator)
+- `a.minmax -> Array`: Return an `Array` of two elements, first and second is the max and min in `a`
+- `a.minmax_op(Array | Set | MSet | Bag | MBag b) -> Array`: Return an `Array` of two elements, first and second are the max and min in `a` and `b` resepctively
+- `a.minmax_op_str(Array | Set | MSet | Bag | MBag b) -> Array`: Stringwise version of `a.minmax_op`
 - `a.minmaxstr -> Array`: The stringwise version of `a.minmax`
 - `a.keys -> Array`: Return an Array of indexes of `a`
-- `a.kv -> Map`: Return a created Map from elements of `a`, abort if `a.len` is odd.
-- `a.ikv -> Map`: Return the Map version of `a` with indexes as keys
-- `a.rev -> Array`: Return the list in reverse order
-- `a.join([ Str sep ]) -> Str`: Stringyfy elements in `a` and interleave them with the separator `sep` or empty string if not specified
-- `a.pop([ Num | Str n ]) -> Num | Array`: If `n` is omitted, pop last element from `a` and return it else pop `n` elements from it. Fail if array is emty.
-- `a.push(Any x [, Any y, ... ]) -> Array`: Push into `a` elements passed as arguments to `push` into `a`. return the modified array.
-- `a.append(Any x [, Any y, ... ]) -> Array`: Same as `push` except that it flattens arrays to append them invidually. Return the modified array.
-- `a.shift([ Num | Str n ])`: 
-- `a.unshift([ Num | Str n ])`: 
-- `a.prepend() -> Array`: 
-- `a.del(Num | Str n)`:
-- `a.splice() -> Array`: 
-- `a.flat() -> Array`: flattens 
-- `a.map(Fun f | Exp) -> Array`: run function F or evaluate expression for each elements in `a` and collect the return values into an Array
+- `a.kv -> Map`: Return a new `Map` object elements of `a`, abort if `a.len` is odd
+- `a.ikv -> Map`: Return in a new object the `Map` version of `a` with indexes as keys
+- `a.rev -> Array`: Return a new array which contains reversed elements of `a`
+- `a.join([ Str | Num sep ]) -> Str`: Stringyfy elements in `a` and interleave them with the separator `sep` or empty string if not specified
+- `a.pop([ Num | Str n ]) -> Num | Array`: `n` defaults do `1` if omitted. At the end, pop and return `n` elements from `a`, as a `Num` if n is 1 else as an `Array`
+- `a.push(Any x [, Any y, ... ]) -> Array`: At the end, push into `a` elements passed as arguments to `push`
+- `a.append(Any x [, Any y, ... ]) -> Array`: Same as `push` except that it flattens arrays to append individual elements
+- `a.shift([ Num | Str n ])`: Same as `a.pop` but does it at the front
+- `a.unshift([ Num | Str n ])`: Same as `a.push` but does it at the front
+- `a.prepend() -> Array`: Same as `a.append` but does it at the front
+- `a.del(Num | Str n)`: Delete element at index `n`, fail if index does not exist in that array
+- `a.splice([ Num | Str start ] [, Num | Str end ] [, Array | Bag | MBag | Set | MSet b ]) -> Array`: 
+- `a.flat() -> Array`: It flattens the Array object so that all the elements found in nested array end up direct elements of `a`
+- `a.map(Fun f | Exp) -> Array`: Run function `f` or evaluate expression `Exp` for each elements in `a` and collect their return values into an array
 - `a.lmap(Fun f | Exp) -> Array`: Same as `a.map` but `.flat` the result return it
-- `a.grep(Fun f | Exp) -> Array:
+- `a.grep(Fun f | Exp) -> Array`: Returns elements in `a` for which it evaluation by `f` or `Exp` return a true value
 - `a.last_by(Fun f | Exp) -> Any`:
 - `a.first_by(Fun f | Exp) -> Any`:
-- ``
+- `a.cmp(Array b) -> Num`: 
+- `a.print -> Bool`:
+- `a.say`:
+- `a.dump`:

docs/maat_dev_ref/objects/Str.md

@@ -1,83 +1,89 @@
 # String
 
-Let `s` be a variable whose content is a object of type `String`, `s` of type
-`String` supports the following public methods:
+Let `s` be a variable whose content is an object of type `Str`, `s` supports following public methods:
 
-- `s.len`: return string length
-- `s.gt(s1)`: return true if `s` gt `s1` else false, see opts above
-- `s.ge(s1)`: return true if `s` ge `s1` else false
-- `s.lt(s1)`: return true if `s` lt `s1` else false
-- `s.le(s1)`: return true if `s` le `s1` else false
-- `s.eq(s1)`: return true if `s` eq `s1` else false
-- `s.ne(s1)`: return true if `s` ne `s1` else false
-- `s.div(num)`: divide string `s` by `num`
+- `s.len`: Return string length
+- `s.gt(s1)`: Return `True` if `s` gt `s1` else `False`, see opts below
+- `s.ge(s1)`: Return `True` if `s` ge `s1` else `False`
+- `s.lt(s1)`: Return `True` if `s` lt `s1` else `False`
+- `s.le(s1)`: Return `True` if `s` le `s1` else `False`
+- `s.eq(s1)`: Return `True` if `s` eq `s1` else `False`
+- `s.ne(s1)`: Return `True` if `s` ne `s1` else `False`
+- `s.div(Num n)`: Divide string `s` by `n`
 
-> Well, this is new let so me give an example
-> `"ILovePity".div(3)` yields `["ILo", "veP", "ity"]`.
-> In case `num` is greater than `s.len` then return
-> an array containing `s` as the single element.
-> also, `"Pity".div(3)` yields `["Pit", "y"]`.
+Well, this is new so let me give an example:
 
-- `s.match(/regex/flags)`: return a matched object, see `Match` object below
-- `s.gmatch(/regex/flags)`: global match, return an array of `Match` objects
-- `s.sub()`:
-- `s.gsub()`:
-- `s.esub()`:
-- `s.tr()`: transliteration `s`
+`"ILoveMaat".div(3) -- returns a(ILo veM aat)`
 
-- `s.uc`: uppercase `s`
-- `s.ucfirst`: uppercase the first character of `s`
-- `s.lc`: lowercase `s`
-- `s.lcfirst`: lowercase the first character of `s`
-- `s.fc`: foldcase `s`
-- `s.split(delim)`: split `s` based on delimiter (`delim`: string or regex) which is a regex
-- `s.cmp(s1)`: cmp `s` with `s1`: `s` eq `s1` yield 0, `s` lt `s1` yields -1, `s` gt `s1` yield 1
-- `s.mul(num)`: multiply `s` by `num`, just  like the `x` operator
-- `s.append(s1)`, `s.concat(s1)`: append `s1` to `s`
-- `s.prepend(s1)`: prepend `s1` to `s`
-- `s.first(num)`: return the first `num` characters of `s`
-- `s.last(num)`: return the last `num` characters of `s`
-- `s.char(pos)`: return character at position `pos`, NB: zero indexed.
-- `s.wordcase`: word case `s`, example `"i love afRica".wordcase` yield `"I Love Africa"`
-- `s.capitalize(X)`: capitalize `s`
-- `s.chop()`: (From Perl) remove the last character of `s` and return it
-- `s.pop()`: remove the last character from `s` and return the rest
-- `s.chomp()`: (From Perl) remove trailing new lines
-- `s.bin()`: coerce `s` into a number and return it in base 2
-- `s.oct()`: coerce `s` into a number and return it in base 8
-- `s.hex()`: ..... `s` into ... and in base 16
-- `s.crypt()`: crypt s, crypt from the C standard library
-- `s.decode_base64()`: base64 decode `s`
-- `s.encode_base65()`: base64 encode `s`
-- `s.md5()`: 
-- `s.sha()`:
-- `s.clear()`: set `s` to an empty string
+In case `n` is greater than `s.len` then return an array containing `s` as the single element.
+also, `"Maat".div(3)` returns `["Maa", "t"]`.
+
+- `s.match(/regex/flags)`: Return a matched object, see `Match` object below
+- `s.gmatch(/regex/flags)`: Global match, return an array of `Match` objects
+- `s.sub`:
+- `s.gsub`:
+- `s.esub`:
+- `s.tr`: Transliteration `s`
+
+- `s.clone`: Return a new object which is a clone of `s`
+- `s.uc`: Uppercase `s`
+- `s.ucfirst`: Uppercase the first character of `s`
+- `s.lc`: Lowercase `s`
+- `s.lcfirst`: Lowercase the first character of `s`
+- `s.fc`: Foldcase `s`
+- `s.split(delim)`: Split `s` based on delimiter (`delim`: string or regex) which is a regex
+- `s.cmp(s1)`: Cmp `s` with `s1`: `s` eq `s1` return 0, `s` lt `s1` returns -1, `s` gt `s1` yield 1
+- `s.mul(Num n)`: Multiply `s` by `n`, just  like the `x` operator
+- `s.append(s1)`, `s.concat(s1)`: Append `s1` to `s`
+- `s.prepend(s1)`: Prepend `s1` to `s` and return the result in a new object
+- `s.first(Num n)`: Return the first `n` characters of `s`
+- `s.last(Num n)`: Return the last `n` characters of `s`
+- `s.char(pos)`: Return character at position `pos`, NB: zero indexed.
+- `s.wordcase`: Word case `s`, example `"i love BurkinA faSo".wordcase` return `"I Love Burkina Faso"`
+- `s.capitalize(X)`: Capitalize `s`
+- `s.chop -> Str`: Remove the last character of `s` and return it
+- `s.pop`: Remove the last character from `s` and return the rest
+- `s.chomp`: Remove trailing new lines
+- `s.bin`: Coerce `s` into a number and return it in base 2
+- `s.oct`: Coerce `s` into a number and return it in base 8
+- `s.hex`: ..... `s` into ... and in base 16
+- `s.crypt`: Crypt s, crypt from the C standard library
+- `s.decode_base64`: Return base64 decoded `s`
+- `s.encode_base65`: Return base64 encoded `s`
+- `s.md5`: Return a md5 hashed `s`
+- `s.sha1`: Return a sha1 hashed `s`
+- `s.sha256`: Return a sha256 hashed `s`
+- `s.sha512`: Return a sha512 hashed `s`
+- `s.clear`: Set `s` to an empty string
 - `s.substr(offset, len)`: NB: inclusive
-- `s.join([s1, s2, ...])`: join strings in argument to `s`
-- `s.slice(start, end)`: negative numbers mean relative to the end of s, since s.char(-1) is s.char(s.len - 1); NB: inclusive
-- `s.insert(string, pos, [len])`: insert at pos if len is 0 else replace `len` chars with `s1` starting from `pos`
+- `s.join(Any s0 [, Any s1, Any s2, ...]) -> Str`: Join strings in argument to `s` and return the results
+- `s.slice(Num start, Num end) -> Str`: Negative numbers mean relative to the end of s, since s.char(-1) is s.char(s.len - 1); NB: inclusive
+- `s.insert(Str s1, Num pos [, Num len ]) -> Str`: Insert at pos if len is 0 else replace `len` chars with `s1` starting from `pos`
 - `s.index`:
 - `s.rindex`:
 - `s.ord`:
-- `s.reverse`:
-- `s.print`: print without new line
-- `s.printf`: printf ...
-- `s.sprintf`: sprintf ...
-- `s.say`: print with new line
-- `s.printlnf`: printf with new line
-- `s.sprintflnf`: sprintf with new line
+- `s.rev`: Return reversed `s`
+- `s.say`: Print `s` to the standard output with a trailing new line
+- `s.print`: Print `s` to the standard output without a trailing new line
+- `s.dump`: Same as above
+
+- `s.print`: Print without new line
+- `s.printf`: Printf ...
+- `s.sprintf`: Sprintf ...
+- `s.printlnf`: Printf with new line
+- `s.sprintflnf`: Sprintf with new line
 
-- `s.is_empty`: return bool, check if string is empty
-- `s.is_lowercase`: ...
-- `s.is_uppercase`: ...
-- `s.is_ascii`: ...
-- `s.is_space`: ...
-- `s.is_word`: ...
-- `s.is_punct`: ...
-- `s.is_alpha`: ...
-- `s.is_alphanum`: ...
-- `s.is_digit`: ...
-- `s.is_xdigit`: ...
-- `s.is_control`: ...
-- `s.is_printable`: ...
-- `s.is.graph`: ...
+- `s.is_empty -> Bool`: Return bool, check if string is empty
+- `s.is_lc -> Bool`: ...
+- `s.is_uc -> Bool`: ...
+- `s.is_ascii -> Bool`: ...
+- `s.is_space -> Bool`: ...
+- `s.is_word -> Bool`: ...
+- `s.is_punct -> Bool`: ...
+- `s.is_alpha -> Bool`: ...
+- `s.is_alphanum -> Bool`: ...
+- `s.is_digit -> Bool`: ...
+- `s.is_xdigit -> Bool`: ...
+- `s.is_control -> Bool`: ...
+- `s.is_printable -> Bool`: ...
+- `s.is.graph -> Bool`: ...