kdtree 0.16__tar.gz → 1.0__tar.gz

kdtree-1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include AUTHORS
+include LICENSE
+include readme.md
+include test.py
+include kdtree.pyi
+include test_typing.py
+include typing_sample.py

kdtree-1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: kdtree
+Version: 1.0
+Summary: A Python implementation of a kd-tree
+Home-page: https://github.com/stefankoegl/kdtree
+Download-URL: http://pypi.python.org/packages/source/k/kdtree/kdtree-1.0.tar.gz
+Author: Stefan Kögl
+Author-email: stefan@skoegl.net
+License: ISC license
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+License-File: LICENSE
+License-File: AUTHORS
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+This package provides a simple implementation of a kd-tree in Python.
+https://en.wikipedia.org/wiki/K-d_tree

kdtree-1.0/kdtree.egg-info/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: kdtree
+Version: 1.0
+Summary: A Python implementation of a kd-tree
+Home-page: https://github.com/stefankoegl/kdtree
+Download-URL: http://pypi.python.org/packages/source/k/kdtree/kdtree-1.0.tar.gz
+Author: Stefan Kögl
+Author-email: stefan@skoegl.net
+License: ISC license
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+License-File: LICENSE
+License-File: AUTHORS
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+This package provides a simple implementation of a kd-tree in Python.
+https://en.wikipedia.org/wiki/K-d_tree

{kdtree-0.16 → kdtree-1.0}/kdtree.egg-info/SOURCES.txt

@@ -2,10 +2,13 @@ AUTHORS
 LICENSE
 MANIFEST.in
 kdtree.py
+kdtree.pyi
 readme.md
 setup.cfg
 setup.py
 test.py
+test_typing.py
+typing_sample.py
 kdtree.egg-info/PKG-INFO
 kdtree.egg-info/SOURCES.txt
 kdtree.egg-info/dependency_links.txt

{kdtree-0.16 → kdtree-1.0}/kdtree.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
 
-"""A Python implemntation of a kd-tree
+"""A Python implementation of a kd-tree
 
 This package provides a simple implementation of a kd-tree in Python.
 https://en.wikipedia.org/wiki/K-d_tree
@@ -17,7 +17,7 @@ from collections import deque
 from functools import wraps
 
 __author__ = u'Stefan Kögl <stefan@skoegl.net>'
-__version__ = '0.16'
+__version__ = '1.0'
 __website__ = 'https://github.com/stefankoegl/kdtree'
 __license__ = 'ISC license'
 
@@ -44,7 +44,7 @@ class Node(object):
         >>> Node( 1, left=Node(2) ).is_leaf
         False
         """
-        return (not self.data) or \
+        return (self.data is None) or \
                (all(not bool(c) for c, p in self.children))
 
 
@@ -175,10 +175,10 @@ class Node(object):
     __bool__ = __nonzero__
 
     def __eq__(self, other):
-        if isinstance(other, tuple):
-            return self.data == other
-        else:
+        if isinstance(other, Node):
             return self.data == other.data
+        else:
+            return self.data == other
 
     def __hash__(self):
         return id(self)
@@ -190,7 +190,7 @@ def require_axis(f):
     @wraps(f)
     def _wrapper(self, *args, **kwargs):
         if None in (self.axis, self.sel_axis):
-            raise ValueError('%(func_name) requires the node %(node)s '
+            raise ValueError('%(func_name)s requires the node %(node)s '
                     'to have an axis and a sel_axis function' %
                     dict(func_name=f.__name__, node=repr(self)))
 
@@ -229,10 +229,10 @@ class KDNode(Node):
         Users should call add() only to the topmost tree.
         """
 
+        check_dimensionality([point], dimensions=self.dimensions)
+
         current = self
         while True:
-            check_dimensionality([point], dimensions=current.dimensions)
-
             # Adding has hit an empty leaf-node, add here
             if current.data is None:
                 current.data = point
@@ -294,33 +294,49 @@ class KDNode(Node):
 
         If there are multiple points matching "point", only one is removed. The
         optional "node" parameter is used for checking the identity, once the
-        removeal candidate is decided."""
+        removal candidate is decided."""
+
+        return self._remove_one(point, node)[0]
+
+
+    def _remove_one(self, point, node):
+        """ Removes at most one matching node from the (sub)tree
+
+        Returns a (new-subtree-root, removed) tuple, where removed indicates
+        whether a node has been removed. """
 
         # Recursion has reached an empty leaf node, nothing here to delete
         if not self:
-            return
+            return self, False
 
         # Recursion has reached the node to be deleted
         if self.should_remove(point, node):
-            return self._remove(point)
+            return self._remove(point), True
 
         # Remove direct subnode
         if self.left and self.left.should_remove(point, node):
             self.left = self.left._remove(point)
+            return self, True
 
         elif self.right and self.right.should_remove(point, node):
             self.right = self.right._remove(point)
+            return self, True
 
-        # Recurse to subtrees
+        # Recurse to subtrees. If the point lies on the splitting plane, both
+        # subtrees may contain it, but only one node must be removed
         if point[self.axis] <= self.data[self.axis]:
             if self.left:
-                self.left = self.left.remove(point, node)
+                self.left, removed = self.left._remove_one(point, node)
+                if removed:
+                    return self, True
 
         if point[self.axis] >= self.data[self.axis]:
             if self.right:
-                self.right = self.right.remove(point, node)
+                self.right, removed = self.right._remove_one(point, node)
+                if removed:
+                    return self, True
 
-        return self
+        return self, False
 
 
     @require_axis
@@ -376,7 +392,10 @@ class KDNode(Node):
         Returns the (possibly new) root of the rebalanced tree
         """
 
-        return create([x.data for x in self.inorder()])
+        points = [x.data for x in self.inorder()]
+        axis = self.axis if self.axis is not None else 0
+        return create(points, dimensions=self.dimensions, axis=axis,
+                      sel_axis=self.sel_axis)
 
 
     def axis_dist(self, point, axis):
@@ -387,13 +406,17 @@ class KDNode(Node):
         return math.pow(self.data[axis] - point[axis], 2)
 
 
-    def dist(self, point):
+    def dist(self, point, axis=None):
         """
         Squared distance between the current Node
         and the given point
         """
-        r = range(self.dimensions)
-        return sum([self.axis_dist(point, i) for i in r])
+        if axis is None:
+            axes = range(self.dimensions)
+        else:
+            axes = [axis]
+
+        return sum([self.axis_dist(point, i) for i in axes])
 
 
     def search_knn(self, point, k, dist=None):
@@ -406,7 +429,9 @@ class KDNode(Node):
         distances.
 
         dist is a distance function, expecting two points and returning a
-        distance value. Distance values can be any compareable type.
+        distance value. dist should expect an optional `axis` parameter. If
+        given, the distance on the specified axis should be calculated.
+        Distance values must support comparison and unary negation.
 
         The result is an ordered list of (node, distance) tuples.
         """
@@ -414,21 +439,23 @@ class KDNode(Node):
         if k < 1:
             raise ValueError("k must be greater than 0.")
 
-        if dist is None:
-            get_dist = lambda n: n.dist(point)
-        else:
-            get_dist = lambda n: dist(n.data, point)
+        def get_dist(n, axis=None):
+            if dist is None:
+                return n.dist(point, axis=axis)
+            else:
+                return dist(n.data, point, axis=axis)
 
         results = []
 
-        self._search_node(point, k, results, get_dist, itertools.count())
+        self._search_node(point, k, results, get_dist, itertools.count(),
+                          prune=dist is None)
 
         # We sort the final result by the distance in the tuple
         # (<KdNode>, distance).
         return [(node, -d) for d, _, node in sorted(results, reverse=True)]
 
 
-    def _search_node(self, point, k, results, get_dist, counter):
+    def _search_node(self, point, k, results, get_dist, counter, prune=True):
         if not self:
             return
 
@@ -446,32 +473,33 @@ class KDNode(Node):
                 heapq.heapreplace(results, item)
         else:
             heapq.heappush(results, item)
+
         # get the splitting plane
         split_plane = self.data[self.axis]
-        # get the squared distance between the point and the splitting plane
-        # (squared since all distances are squared).
-        plane_dist = point[self.axis] - split_plane
-        plane_dist2 = plane_dist * plane_dist
+        # get the distance between the point and the splitting plane
+        plane_dist = get_dist(self, axis=self.axis)
 
         # Search the side of the splitting plane that the point is in
         if point[self.axis] < split_plane:
             if self.left is not None:
-                self.left._search_node(point, k, results, get_dist, counter)
+                self.left._search_node(point, k, results, get_dist, counter,
+                                       prune=prune)
         else:
             if self.right is not None:
-                self.right._search_node(point, k, results, get_dist, counter)
+                self.right._search_node(point, k, results, get_dist, counter,
+                                        prune=prune)
 
         # Search the other side of the splitting plane if it may contain
         # points closer than the farthest point in the current results.
-        if -plane_dist2 > results[0][0] or len(results) < k:
+        if not prune or -plane_dist > results[0][0] or len(results) < k:
             if point[self.axis] < self.data[self.axis]:
                 if self.right is not None:
                     self.right._search_node(point, k, results, get_dist,
-                                            counter)
+                                            counter, prune=prune)
             else:
                 if self.left is not None:
                     self.left._search_node(point, k, results, get_dist,
-                                           counter)
+                                           counter, prune=prune)
 
 
     @require_axis
@@ -484,10 +512,14 @@ class KDNode(Node):
         with this location will be returned (not its neighbor).
 
         dist is a distance function, expecting two points and returning a
-        distance value. Distance values can be any compareable type.
+        distance value. dist should expect an optional `axis` parameter. If
+        given, the distance on the specified axis should be calculated.
+        Distance values must support comparison and unary negation.
 
         The result is a (node, distance) tuple.
         """
+        if not self:
+            raise ValueError("tree is empty")
 
         return next(iter(self.search_knn(point, 1, dist)), None)
 
@@ -499,28 +531,36 @@ class KDNode(Node):
         nodeDist = get_dist(self)
 
         if nodeDist < dist:
-          results.append(self.data)
+            results.append(self.data)
 
         # get the splitting plane
         split_plane = self.data[self.axis]
+        # dist is compared against squared distances, so the distance to the
+        # splitting plane has to be squared as well
+        plane_dist = self.axis_dist(point, self.axis)
 
-        # Search the side of the splitting plane that the point is in
-        if point[self.axis] <= split_plane + dist:
+        # Search each side of the splitting plane that may contain points
+        # within the given distance
+        if point[self.axis] <= split_plane or plane_dist < dist:
             if self.left is not None:
                 self.left._search_nn_dist(point, dist, results, get_dist)
-        if point[self.axis] >= split_plane - dist:
+        if point[self.axis] >= split_plane or plane_dist < dist:
             if self.right is not None:
                 self.right._search_nn_dist(point, dist, results, get_dist)
 
 
     @require_axis
-    def search_nn_dist(self, point, distance, best=None):
+    def search_nn_dist(self, point, distance):
         """
         Search the n nearest nodes of the given point which are within given
         distance
 
         point must be a location, not a node. A list containing the n nearest
         nodes to the point within the distance will be returned.
+        
+        distance is the threshold distance to filter nodes.
+        Note: KDNode.dist() returns squared distance, so the comparison will 
+        be done using squared_distance < distance.
         """
 
         results = []
@@ -529,6 +569,51 @@ class KDNode(Node):
         self._search_nn_dist(point, distance, results, get_dist)
         return results
 
+    @require_axis
+    def range_search(self, top_left, bottom_right):
+        """
+        Search all nodes in or on the hyperrectangle defined by the points top_left and bottom_right.
+
+        Note: the list returned is not in any particular order.
+        """
+
+        invalid_rect = False
+        if len(top_left) != len(bottom_right) or len(top_left) != self.dimensions:
+            invalid_rect = True
+        else:
+            for i in range(len(top_left)):
+                if top_left[i] > bottom_right[i]:
+                    invalid_rect = True
+                    break
+
+        if invalid_rect:
+            raise ValueError("invalid rectangle")
+
+        results = []
+        stack = [self]
+
+        while(stack):
+            node = stack.pop()
+
+            data = node.data
+            axis = node.axis
+
+            if data is None:
+                continue
+
+            in_range = True
+            for d in range(0, len(data)):
+                in_range &= (data[d] >= top_left[d]) and (data[d] <= bottom_right[d])
+
+            if in_range:
+                results.append(node)
+
+            if data[axis] >= top_left[axis] and node.left:
+                stack.append(node.left)
+            if data[axis] <= bottom_right[axis] and node.right:
+                stack.append(node.right)
+
+        return results
 
     @require_axis
     def is_valid(self):
@@ -606,8 +691,8 @@ def create(point_list=None, dimensions=None, axis=0, sel_axis=None):
     median = len(point_list) // 2
 
     loc   = point_list[median]
-    left  = create(point_list[:median], dimensions, sel_axis(axis))
-    right = create(point_list[median + 1:], dimensions, sel_axis(axis))
+    left  = create(point_list[:median], dimensions, sel_axis(axis), sel_axis)
+    right = create(point_list[median + 1:], dimensions, sel_axis(axis), sel_axis)
     return KDNode(loc, left, right, axis=axis, sel_axis=sel_axis, dimensions=dimensions)
 
 
@@ -651,7 +736,8 @@ def visualize(tree, max_level=100, node_width=10, left_padding=5):
     in_level  = 0
     level     = 0
 
-    for node in level_order(tree, include_all=True):
+    # level_order() is infinite with include_all; the loop ends with break
+    for node in level_order(tree, include_all=True):  # pragma: no branch
 
         if in_level == 0:
             print()

kdtree-1.0/kdtree.pyi

@@ -0,0 +1,165 @@
+"""Type stubs for the kdtree module
+
+kdtree is distributed as a single-file module. Type information is therefore
+shipped as this stub file, which is installed next to kdtree.py.
+"""
+
+from collections.abc import Callable, Collection, Iterable, Iterator, Sequence
+from typing import Any, Generic, ParamSpec, Protocol, Self, TypeVar, overload
+
+__author__: str
+__version__: str
+__website__: str
+__license__: str
+
+class _Point(Protocol):
+    """Anything that can be used as a point: it has a length and its
+    coordinates can be accessed by index"""
+
+    def __len__(self) -> int: ...
+    def __getitem__(self, index: int, /) -> Any: ...
+
+_T = TypeVar("_T")
+_P = TypeVar("_P", bound=_Point)
+_Q = TypeVar("_Q", bound=_Point)
+_P_contra = TypeVar("_P_contra", contravariant=True)
+_Q_contra = TypeVar("_Q_contra", contravariant=True)
+_D_co = TypeVar("_D_co", covariant=True)
+_N = TypeVar("_N", bound=Node[Any])
+_D = TypeVar("_D", bound=_Distance)
+_R = TypeVar("_R")
+_Params = ParamSpec("_Params")
+
+class _Distance(Protocol):
+    """A distance value: search_knn() negates distances and compares them"""
+
+    def __neg__(self) -> Self: ...
+    def __lt__(self, other: Any, /) -> bool: ...
+    def __gt__(self, other: Any, /) -> bool: ...
+
+class _DistFunc(Protocol[_P_contra, _Q_contra, _D_co]):
+    """A distance function, always called as dist(a, b, axis=axis)
+
+    a is a point stored in the tree, b is the point that is searched for."""
+
+    def __call__(
+        self, a: _P_contra, b: _Q_contra, /, *, axis: int | None
+    ) -> _D_co: ...
+
+class Node(Generic[_T]):
+    data: _T | None
+    left: Self | None
+    right: Self | None
+    def __init__(
+        self,
+        data: _T | None = None,
+        left: Self | None = None,
+        right: Self | None = None,
+    ) -> None: ...
+    @property
+    def is_leaf(self) -> bool: ...
+    def preorder(self) -> Iterator[Self]: ...
+    def inorder(self) -> Iterator[Self]: ...
+    def postorder(self) -> Iterator[Self]: ...
+    @property
+    def children(self) -> Iterator[tuple[Self, int]]: ...
+    def set_child(self, index: int, child: Self | None) -> None: ...
+    def height(self) -> int: ...
+    def get_child_pos(self, child: Node[Any]) -> int | None: ...
+    def __nonzero__(self) -> bool: ...
+    def __bool__(self) -> bool: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __hash__(self) -> int: ...
+
+def require_axis(f: Callable[_Params, _R]) -> Callable[_Params, _R]: ...
+
+class KDNode(Node[_P]):
+    axis: int | None
+    sel_axis: Callable[[int], int] | None
+    dimensions: int | None
+    def __init__(
+        self,
+        data: _P | None = None,
+        left: Self | None = None,
+        right: Self | None = None,
+        axis: int | None = None,
+        sel_axis: Callable[[int], int] | None = None,
+        dimensions: int | None = None,
+    ) -> None: ...
+    def add(self, point: _P) -> Self: ...
+    def create_subnode(self, data: _P | None) -> Self: ...
+    def find_replacement(self) -> tuple[Self | None, Self]: ...
+    def should_remove(self, point: _Point, node: KDNode[Any] | None) -> bool: ...
+    def remove(self, point: _Point, node: KDNode[Any] | None = None) -> Self: ...
+    @property
+    def is_balanced(self) -> bool: ...
+    def rebalance(self) -> KDNode[_P]: ...
+    def axis_dist(self, point: _Point, axis: int) -> float: ...
+    def dist(self, point: _Point, axis: int | None = None) -> float: ...
+    @overload
+    def search_knn(
+        self, point: _Point, k: int, dist: None = None
+    ) -> list[tuple[Self, float]]: ...
+    @overload
+    def search_knn(
+        self, point: _Q, k: int, dist: _DistFunc[_P, _Q, _D]
+    ) -> list[tuple[Self, _D]]: ...
+    @overload
+    def search_nn(self, point: _Point, dist: None = None) -> tuple[Self, float]: ...
+    @overload
+    def search_nn(
+        self, point: _Q, dist: _DistFunc[_P, _Q, _D]
+    ) -> tuple[Self, _D]: ...
+    def search_nn_dist(self, point: _Point, distance: float) -> list[_P]: ...
+    def range_search(self, top_left: _Point, bottom_right: _Point) -> list[Self]: ...
+    def is_valid(self) -> bool: ...
+    def extreme_child(
+        self,
+        sel_func: Callable[..., Any],
+        axis: int,
+    ) -> tuple[Self, Self | None] | tuple[None, None]: ...
+
+@overload
+def create(
+    point_list: None = None,
+    *,
+    dimensions: int,
+    axis: int = 0,
+    sel_axis: Callable[[int], int] | None = None,
+) -> KDNode[Any]: ...
+@overload
+def create(
+    point_list: None,
+    dimensions: int,
+    axis: int = 0,
+    sel_axis: Callable[[int], int] | None = None,
+) -> KDNode[Any]: ...
+@overload
+def create(
+    point_list: Sequence[_P],
+    dimensions: int | None = None,
+    axis: int = 0,
+    sel_axis: Callable[[int], int] | None = None,
+) -> KDNode[_P]: ...
+@overload
+def create(
+    # without dimensions, they are taken from point_list[0]. Iterators are
+    # not supported, as the dimensionality check consumes them
+    point_list: Collection[_P],
+    dimensions: int,
+    axis: int = 0,
+    sel_axis: Callable[[int], int] | None = None,
+) -> KDNode[_P]: ...
+@overload
+def check_dimensionality(
+    point_list: Sequence[_Point], dimensions: int | None = None
+) -> int: ...
+@overload
+def check_dimensionality(point_list: Iterable[_Point], dimensions: int) -> int: ...
+def level_order(tree: _N, include_all: bool = False) -> Iterator[_N]: ...
+def visualize(
+    tree: Node[Any],
+    max_level: int = 100,
+    node_width: int = 10,
+    left_padding: int = 5,
+) -> None: ...

{kdtree-0.16 → kdtree-1.0}/readme.md

@@ -1,4 +1,4 @@
-A simple kd-tree in Python [![Build Status](https://travis-ci.org/stefankoegl/kdtree.png?branch=master)](https://travis-ci.org/stefankoegl/kdtree)
+A simple kd-tree in Python [![Tests](https://github.com/stefankoegl/kdtree/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/stefankoegl/kdtree/actions/workflows/tests.yml)
 ==========================
 
 The kdtree package can construct, modify and search
@@ -8,7 +8,7 @@ The kdtree package can construct, modify and search
 * Repository: https://github.com/stefankoegl/kdtree.git
 * Documentation: https://python-kdtree.readthedocs.org/
 * PyPI: https://pypi.python.org/pypi/kdtree
-* Travis-CI: https://travis-ci.org/stefankoegl/kdtree
+* GitHub Actions: https://github.com/stefankoegl/kdtree/actions
 * Coveralls: https://coveralls.io/r/stefankoegl/kdtree
 
 
@@ -55,7 +55,7 @@ Usage
 
     # Find the nearest node to the location (1, 2, 3)
     >>> tree.search_nn( (1, 2, 3) )
-    <KDNode - (2, 3, 4)>
+    (<KDNode - (2, 3, 4)>, 3.0)
 
     # Add a point to make the tree more interesting
     >>> tree.add( (10, 2, 1) )
@@ -73,7 +73,7 @@ Usage
     # Take the right subtree of the root
     >>> subtree = tree.right
 
-    # and detatch it
+    # and detach it
     >>> tree.right = None
     >>> kdtree.visualize(tree)
 
@@ -122,6 +122,21 @@ Usage
 
           (2, 3, 4)
 
+### Type hints
+
+Type information is provided in the stub file `kdtree.pyi`, which is installed
+next to `kdtree.py` and, for mypy, as the stub-only package `kdtree-stubs`.
+Trees are generic in the type of their points:
+
+```python
+tree = kdtree.create([(1, 2), (3, 4)])  # KDNode[tuple[int, int]]
+node, dist = tree.search_nn((1, 1))     # KDNode[tuple[int, int]], float
+```
+
+The classes are only generic for type checkers; at runtime write
+annotations like `kdtree.KDNode[tuple[int, int]]` as strings or use
+`from __future__ import annotations`.
+
 ### Adding a payload
 
 Indexing a dict by a pair of floats is not a good idea, since there might be unexpected precision errors.