API signatures: typed overloads, values instead of geometries for point-like measures, fixed exception rules
Algorithms have typed overloads whose return type follows from the strict semantics (ADR 0005), plus one general IGeometry2D overload each, which branches at run time. The compiler thus knows the result type without a cast. Point-like measures are values instead of geometries: Centroid() returns Coordinate? (null for empty input) and needs no factory. Distance with an empty geometry is NaN. This is a deliberate deviation from NTS, which returns 0 and thereby makes "touches" and "nothing there" indistinguishable.
German version: 0012-api-signaturen-typisierte-overloads.de.md
Consequences
- Binary operations:
- Intersection: polygon ∩ polygon →
IPolygon2D. Polygon ∩ polyline and polyline ∩ polyline →IPolyline2D, overlaps only, pure crossing points are dropped under strict semantics. Multipoint or point ∩ anything →IMultiPoint2D. - Union and SymDifference: only for equal dimension.
- Difference: returns the type of the first operand.
- Intersection: polygon ∩ polygon →
- Measures:
AreaonIPolygon2D,LengthonIPolyline2DandIPolygon2D(perimeter).- General overloads on
IGeometry2Dreturn 0 if the measure does not fit the dimension. Envelope()returnsEnvelope2D, for empty inputEnvelope2D.Empty(NaN,IsEmpty).
- ConvexHull returns
IGeometry2D. Depending on degeneracy this is a polygon, a polyline or a multipoint, as in JTS. - Simplify returns the input type.
- Default: Douglas-Peucker followed by normalization through the overlay (union with EvenOdd). The result is always valid (ADR 0003), collapsed rings are dropped.
preserveTopology: true: a topology-preserving simplifier after the pattern of JTSTopologyPreservingSimplifier. This is an additional algorithm within the v1 scope.
- IsValid:
IsValid()returnsbool,Validate()returnsValidationResultwith findings consisting of kind andCoordinate. The kinds areSelfIntersection,RingSelfTouch,DegenerateRing,InvalidCoordinate,TooFewPointsandOverlappingShells, according to ADR 0003 and not 1:1 from NTS (a missing closing point is valid, for example). - Exceptions:
ArgumentNullExceptionfornullargumentsArgumentOutOfRangeExceptionfor invalid numeric parameters (NaN/Infinity, negative tolerance,gridSize ≤ 0,QuadrantSegments < 1)InvalidOperationExceptionwhen no factory is available (ADR 0004)NotSupportedExceptionfor unknownIGeometry2Dtypes or combinations that cannot be represented in general overloads- Invalid or empty geometries never throw.
- Parameters: an options object exists only for more than two domain-specific knobs (
BufferOptions,OffsetOptions, ADR 0006), otherwise simple optional parameters. The order is always: required parameters → domain options →factory→gridSize.
Considered Options
- Centroid as
IPoint2Dvia the factory with exception orTryCentroid(rejected: allocation for a single value) - Distance with an empty geometry = 0 as in NTS (rejected: ambiguous) or an exception
- ConvexHull always
IPolygon2D(rejected: loses the degeneracy information) - Simplify without a validity guarantee (rejected: contradicts ADR 0003)