istr-python 1.1.32.post0__tar.gz → 1.1.34__tar.gz

{istr_python-1.1.32.post0/istr_python.egg-info → istr_python-1.1.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: istr-python
-Version: 1.1.32.post0
+Version: 1.1.34
 Summary: istr - strings you can count on
 Author-email: Ruud van der Ham <rt.van.der.ham@gmail.com>
 Project-URL: Homepage, https://github.com/salabim/istr
@@ -367,7 +367,18 @@ to unpack multiple values, e.g.
 a, b, c = istr(5, 6, 7) ==> a=istr('5') , b=istr('6'), c=istr('7') 
 a, b, c = istr(*range(3)) ==> a=istr('0') , b=istr('1'), c=istr('2') 
   ```
+#### Alternative way of range specification
+
+Instead of `istr(range(..))` it is possible to use `istr,range(..)` instead, like
+
+`list(istr.range(3,6))` ==> `[istr('3'), istr('4'), istr('5')]`
+
+In contrast to the builtin `range`, `istr.range` supports a non keyword parameter `length`:
+
+`list(istr.range(length=3))` is equivalent to `istr.range(100, 1000)`
+
 #### test for even/odd
+
 It is possible to test for even/odd (provided the istr can be interpreted as an int) with the `is_even` and `is_odd` method, e.g.
 
 ```
@@ -424,18 +435,19 @@ It is also possible to test for divisibility of an ordinary int:
 istr.is_divisible(18, 3) ==> True
 istr.is_divisible(19, 3) ==> False
 ```
-The method `divided_by` not only tests divisibility, but also returns the result of the division. If not possible, None will be returned,
-unless the *fallback* (last argument) is given, in which case *fallback* will be returned.
+The method `divided_by` not only tests divisibility, but also returns the result of the division. If not possible, `istr('')` will be returned, unless the *fallback* (last argument) is given, in which case *fallback* will be returned.
+
+The result will be always istr-ed, except for None.
 ```
 istr(18).divided_by(3) ==> 6 (actually istr("6"))
 istr(18).divided_by(istr(3)) ==> 6
-istr(19).divided_by(3) ==> None
-istr(19).divided_by(3, 0) ==> 0
-istr(19).divided_by(3) ==> None
-istr(19).divided_by(istr(3)) ==> None
+istr(19).divided_by(3) ==> istr('')
+istr(19).divided_by(3, 0) ==> istr('0')
+istr(19).divided_by(3) ==> istr('')
+istr(19).divided_by(istr(3)) ==> istr('')
 istr.divided_by(18, 3) ==>  6
-istr.divided_by(19, 3) ==>  None
-istr.divided_by(19, 3, 0) ==>  0
+istr.divided_by(19, 3) ==>  istr('')
+istr.divided_by(19, 3, 0) ==>  istr('0')
 ```
 #### test for square
 
@@ -754,15 +766,44 @@ In contrast to `math.sumprod()`, `istr.sumprod()` supports a `strict` parameter
 Thus, `istr.sumprod("12", (3,4,5), strict=False)` is `istr(11)`, whereas `istr.sumprod("12", (3,4,5))` 
 raises a ValueError. 
 
-#### get all squares, cubes, power ofs or primes in a given range
+#### get all squares, cubes, power ofs or primes in a given range or with a given length
 
 The class methods `istr.squares`, `istr.cubes`, `istr.power_ofs` and `istr.primes` can be used to get a list of all squares, cubes, power_ofs or primes up to a given upperbound (non inclusive) or between a given lower bound and upper bound (non inclusive), like:
 
 `istr.squares (100)` returns a list of all squares <100
 `istr.squares(50, 100)` returns a list of all squares in the range [50, 100)
 
+Alternatively, it is possible to get a list of all squares, cubes, power_ofs or primes with a given length, like:
+
+`istr.squares (length=2)` returns a list of all squares of length 2, so between 10 and 99.
+
 Unless `cache=False` is specified, the query result is cached.
 
+#### Safe indexing (getitem)
+
+The `istr.getitem` method is essentially, a safe version of indexing an istr.
+If the index is within the bounds of the istr, `getitem` just works like indexing. Otherwise, where normally an IndexError would be raised, the istr('') will be returned unless `fallback` (last argument) is specified.
+
+Note that the result will always be istr-ed, except when the result is None.
+
+Examples:
+```
+istr(1234).getitem(2) ==> 2
+istr(1234).getitem(-2) ==> 3
+istr(1234).getitem(5) ==> istr('2')
+istr(1234).getitem(5, '0') ==> istr('0')
+istr(1234).getitem(5, None) ==> None
+```
+This method can also be used with an str. E.g.:
+```
+istr.getitem('1234', 2) ==> 2
+istr.getitem('1234', -2) ==> 3
+istr.getitem('1234', 5) ==> istr('2')
+istr.getitem('1234',5, '0') ==> istr('0')
+istr.getitem('1234',5, None) ==> None
+```
+Note that this method has the advantage that it can accept an istr as index, in contrast to normal indexing.
+
 #### generate istr with digits
 
 The class method `digits` can be used to return an istr of digits according to a given specification.