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

{istr_python-1.1.33 → istr_python-1.1.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: istr-python
-Version: 1.1.33
+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
@@ -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('')` 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
 
@@ -778,6 +779,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('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.

{istr_python-1.1.33 → istr_python-1.1.34}/README.md

@@ -422,18 +422,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
 
@@ -765,6 +766,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('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.

istr_python-1.1.33/istr/istr.py → istr_python-1.1.34/istr/istr - Copy.py

@@ -464,15 +464,15 @@ class istr(str):
         return result
 
     @classmethod
-    def _primes(cls, lb, ub):
-        sieve = bytearray(b"\x01") * (ub + 1)
+    def _primes(cls, start, stop):
+        sieve = bytearray(b"\x01") * (stop + 1)
         sieve[0:2] = b"\x00\x00"
 
-        for i in range(2, int(ub**0.5) + 1):
+        for i in range(2, int(stop**0.5) + 1):
             if sieve[i]:
-                sieve[i * i : ub + 1 : i] = b"\x00" * (((ub - i * i) // i) + 1)
+                sieve[i * i : stop + 1 : i] = b"\x00" * (((stop - i * i) // i) + 1)
 
-        return list(map(cls, ([i for i, is_prime in enumerate(sieve) if is_prime and lb <= i < ub])))  # range check just to be sure
+        return list(map(cls, ([i for i, is_prime in enumerate(sieve) if is_prime and start <= i < stop])))  # range check just to be sure
 
     @classmethod
     @functools.lru_cache
@@ -555,25 +555,25 @@ class istr(str):
         return result
 
     @classmethod
-    def _power_ofs(cls, exponent, lb, ub):
+    def _power_ofs(cls, exponent, start, stop):
         if exponent % 2 == 0:
-            lb = max(0, lb)
+            start = max(0, start)
         match exponent:
             case 0:
-                if lb <= 1 < ub:
+                if start <= 1 < stop:
                     result = [1]
                 else:
                     result = []
             case 1:
-                result = [*range(lb, ub)]
+                result = [*range(start, stop)]
             case _:
                 result = []
-                if lb < 0:  # can't be the case for even n (because of above limiting)
-                    i = -int((-lb) ** (1 / exponent))
+                if start < 0:  # can't be the case for even n (because of above limiting)
+                    i = -int((-start) ** (1 / exponent))
                 else:
-                    i = int(lb ** (1 / exponent))
-                while (i_n := i**exponent) < ub:
-                    if i_n >= lb:  # just to be sure
+                    i = int(start ** (1 / exponent))
+                while (i_n := i**exponent) < stop:
+                    if i_n >= start:  # just to be sure
                         result.append(i_n)
                     i += 1
 
@@ -987,7 +987,7 @@ _cache = {}
 
 def in_range(lst, start, stop):
     """
-    this function will give all values of lst in the range [lb, ub)
+    this function will give all values of lst in the range [start, stop)
 
     Parameters
     ----------