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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: istr-python
-Version: 1.1.33
+Version: 1.1.34.post0
 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
@@ -435,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('0')` 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('0')
+istr(19).divided_by(3, 1) ==> istr('1')
+istr(19).divided_by(3) ==> istr('0')
+istr(19).divided_by(istr(3)) ==> istr('0')
 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('0')
+istr.divided_by(19, 3, 1) ==>  istr('1')
 ```
 #### test for square
 
@@ -489,6 +490,14 @@ istr.is_power_of(81, 4) ==> True
 istr.is_power_of(82, 4) ==> False
 ```
 
+If called without an exponent, the test will be for any perfect power:
+
+```
+istr(2**10).is_power_of() ==> True
+istr(-3**3).is_power_of() ==> True
+istr(34).is_power_of() ==> False
+```
+
 #### test for prime
 
 It is possible to test whether the value is a prime number (provided the istr can be interpreted as an int) with the `is_prime` method, e.g.
@@ -503,6 +512,20 @@ It is also possible to test for prime of an ordinary int:
 istr.is_prime(4) ==> False
 istr.is_prime(5) ==> True
 ```
+#### get divisors of a number
+The method `divisors` will generate all divisors of a number.
+Normally, the divisors are sorted, but if the sorted flag is False, the order is not necessarily maintained (this is slightly more efficient).
+```
+istr(18).divisors() ==> [istr('1'), istr('2'), istr('3'), istr('6'), istr('9'), istr('18')]
+istr(19).divisors() ==> [istr('1'), istr('19')]  
+istr(18).divisors(sorted=False) ==> [istr('1'), istr('18'), istr('2'), istr('9'), istr('3'), istr('6')]  
+```
+This method can also be used with an int. E.g.:  
+```
+istr.divisors(18) ==> [istr('1'), istr('2'), istr('3'), istr('6'), istr('9'), istr('18')]
+istr.divisors(19) ==> [istr('1'), istr('19')]  
+istr.divisors(18, False) ==> [istr('1'), istr('18'), istr('2'), istr('9'), istr('3'), istr('6')]  
+```
 
 #### test whether all characters are distinct
 
@@ -778,6 +801,31 @@ Alternatively, it is possible to get a list of all squares, cubes, power_ofs or
 
 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('')
+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('')
+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.