svg_path

Core SVG path data structures and constructors.

This module models paths as a list of subpaths, and subpaths as continuous segment lists. Use svg_path/parse and svg_path/serialize when working directly with SVG path data strings.

Types

Error

Errors returned by path construction and editing helpers.

pub type Error {
  AlreadyClosed
  ClosedEmptySubpath
  Discontinuous(
    previous_index: Int,
    next_index: Int,
    expected: vec2.Vec2(Float),
    got: vec2.Vec2(Float),
    distance: Float,
  )
  EmptySubpath
  IncompatibleHorizontalWiggle(
    previous_end: vec2.Vec2(Float),
    next_start: vec2.Vec2(Float),
  )
  IncompatibleVerticalWiggle(
    previous_end: vec2.Vec2(Float),
    next_start: vec2.Vec2(Float),
  )
  InvalidSplice(start: Int, delete: Int, length: Int)
  MultipleNonemptySubpaths
  NotCloseEnough(
    expected: vec2.Vec2(Float),
    got: vec2.Vec2(Float),
    tolerance: Float,
  )
}

Constructors

```
AlreadyClosed
```
The subpath is already closed and cannot accept more segments.
```
ClosedEmptySubpath
```
An operation would produce a closed subpath with no segments.

Empty open subpaths are valid, but this package does not represent a closed empty subpath.
```
Discontinuous(
  previous_index: Int,
  next_index: Int,
  expected: vec2.Vec2(Float),
  got: vec2.Vec2(Float),
  distance: Float,
)
```
A segment starts somewhere other than the previous segment’s end point.

previous_index is the segment whose end point was expected. next_index is the segment whose start point did not match. distance is the distance between expected and got.
```
EmptySubpath
```
The operation requires a non-empty subpath.

IncompatibleHorizontalWiggle(
  previous_end: vec2.Vec2(Float),
  next_start: vec2.Vec2(Float),
)

A wiggle operation could not reconcile two horizontal line segments.

IncompatibleVerticalWiggle(
  previous_end: vec2.Vec2(Float),
  next_start: vec2.Vec2(Float),
)

A wiggle operation could not reconcile two vertical line segments.

```
InvalidSplice(start: Int, delete: Int, length: Int)
```
A splice was requested with invalid bounds.

This is returned when start is negative, delete is negative, or start is greater than the subpath length.
```
MultipleNonemptySubpaths
```
The path contains more than one non-empty subpath.

NotCloseEnough(
  expected: vec2.Vec2(Float),
  got: vec2.Vec2(Float),
  tolerance: Float,
)

Two points were too far apart for a wiggle operation to merge them.

Point

A 2D point.

This is a vec.Vec2(Float), so its coordinates are available as .x and .y.

pub type Point =
  vec2.Vec2(Float)

Subpath

opaque

A continuous sequence of path segments, optionally closed.

The constructor is opaque so that subpaths cannot be created in an invalid discontinuous state. Use subpath, empty_subpath, append, or force_append to build values.

pub opaque type Subpath

Values

append

pub fn append(
  subpath: Subpath,
  segment: Segment,
) -> Result(Subpath, Error)

Append a segment to an open subpath.

The new segment must start exactly at the current end point.

as_subpath

pub fn as_subpath(path: Path) -> Result(Subpath, Error)

Convert a path with zero or one non-empty subpaths into a subpath.

Empty subpaths are ignored. If more than one non-empty subpath is present, this returns MultipleNonemptySubpaths.

assert_close

pub fn assert_close(subpath: Subpath) -> Subpath

Close a subpath if its start and end points already match, panicking if the subpath cannot be closed.

This is useful for hand-authored paths where invalid continuity would be a programmer error. Use close when you want to handle closure errors.

assert_subpath

pub fn assert_subpath(segments: List(Segment)) -> Subpath

Create an open subpath from a continuous list of segments, panicking if the segments are invalid.

This is useful for hand-authored paths where invalid continuity would be a programmer error. Use subpath when you want to handle construction errors.

clean_subpath

pub fn clean_subpath(subpath: Subpath) -> Subpath

Remove zero-length line segments from a subpath.

If the subpath contains only one zero-length line, it is preserved so the subpath does not become empty.

close

pub fn close(subpath: Subpath) -> Result(Subpath, Error)

Close a subpath if its start and end points already match.

end

pub fn end(subpath: Subpath) -> Result(vec2.Vec2(Float), Error)

Return the end point of a non-empty subpath.

force_append

pub fn force_append(
  subpath: Subpath,
  segment: Segment,
) -> Result(Subpath, Error)

Append a segment to an open subpath, inserting a connecting line if needed.

If the subpath is empty, this behaves like append. If the new segment does not start at the current end point, a line segment is inserted between them.

force_close

pub fn force_close(subpath: Subpath) -> Result(Subpath, Error)

Close a subpath, inserting a line back to the start point if needed.

from_subpath

pub fn from_subpath(subpath: Subpath) -> Path

Create a path containing a single subpath.

open

pub fn open(subpath: Subpath) -> Subpath

Return an open version of a subpath.

This only clears the semantic closed flag. It does not remove or alter any segments, including any final line back to the subpath start.

path_arcs_to_bezier

pub fn path_arcs_to_bezier(path: Path) -> Path

Convert every arc in a path to cubic Bezier curves.

This applies subpath_arcs_to_bezier to each subpath.

path_to_cubic_beziers

pub fn path_to_cubic_beziers(path: Path) -> Path

Convert every segment in a path to cubic Bezier curves.

This applies subpath_to_cubic_beziers to each subpath.

point

pub fn point(x: Float, y: Float) -> vec2.Vec2(Float)

Create a point from x and y coordinates.

segment_arcs_to_bezier

pub fn segment_arcs_to_bezier(segment: Segment) -> List(Segment)

Convert an arc segment to cubic Bezier curves, preserving other segments.

Non-arc segments are returned unchanged as a single-item list. An arc may become several cubic Bezier segments.

segment_to_cubic_beziers

pub fn segment_to_cubic_beziers(
  segment: Segment,
) -> List(Segment)

Convert a segment to one or more cubic Bezier curves.

Lines and quadratic Beziers are converted exactly. Cubic Beziers are returned unchanged. Arcs may become several cubic Bezier segments.

set_closed

pub fn set_closed(
  subpath: Subpath,
  closed closed: Bool,
) -> Result(Subpath, Error)

Set a subpath’s semantic closed state.

Setting closed to False only clears the semantic closed flag. Setting it to True requires the subpath’s end point to exactly match its start point.

splice

pub fn splice(
  subpath: Subpath,
  start start: Int,
  delete delete: Int,
  insert insert: List(Segment),
) -> Result(Subpath, Error)

Replace a range of segments in a subpath.

start is a zero-based segment index and delete is the number of segments to remove. If start + delete extends past the end of the subpath, everything from start onward is deleted. Negative start, negative delete, and start greater than the subpath length return InvalidSplice.

The edited subpath must remain continuous. Closed subpaths preserve their closed state; if the splice would make a closed subpath empty, ClosedEmptySubpath is returned.

start

pub fn start(subpath: Subpath) -> Result(vec2.Vec2(Float), Error)

Return the start point of a non-empty subpath.

subpath

pub fn subpath(segments: List(Segment)) -> Result(Subpath, Error)

Create an open subpath from a continuous list of segments.

Returns Discontinuous if any segment starts somewhere other than the previous segment’s end point. The error includes the two segment indices that failed to meet.

subpath_arcs_to_bezier

pub fn subpath_arcs_to_bezier(subpath: Subpath) -> Subpath

Convert every arc in a subpath to cubic Bezier curves.

Lines, quadratic Beziers, and cubic Beziers are preserved. Elliptical arcs are approximated with one or more cubic Beziers, split into chunks of at most a quarter turn. Degenerate arcs fall back to a straight-line cubic Bezier between their endpoints.

subpath_to_cubic_beziers

pub fn subpath_to_cubic_beziers(subpath: Subpath) -> Subpath

Convert every segment in a subpath to cubic Bezier curves.

Lines and quadratic Beziers are converted exactly. Cubic Beziers are preserved. Elliptical arcs are approximated with one or more cubic Beziers, split into chunks of at most a quarter turn.

subpaths

pub fn subpaths(path: Path) -> List(Subpath)

Return the subpaths in a path.

wiggle_close

pub fn wiggle_close(subpath: Subpath) -> Result(Subpath, Error)

Close a subpath while gently reconciling tiny endpoint gaps.

This is useful after floating-point transformations that should preserve closure but leave endpoints off by a very small amount.

wiggle_set_closed

pub fn wiggle_set_closed(
  subpath: Subpath,
  closed closed: Bool,
) -> Result(Subpath, Error)

Set a subpath’s semantic closed state, reconciling tiny endpoint gaps.

Setting closed to False only clears the semantic closed flag. Setting it to True uses wiggle_close, which may adjust endpoints within the default wiggle tolerance.

wiggle_splice

pub fn wiggle_splice(
  subpath: Subpath,
  start start: Int,
  delete delete: Int,
  insert insert: List(Segment),
) -> Result(Subpath, Error)

Replace a range of segments, reconciling tiny endpoint gaps.

This has the same splice bounds behavior as splice, but validates the edited subpath with wiggle_subpath and, for closed subpaths, wiggle_close. Use this when the splice should preserve topology across floating-point noise rather than requiring exact endpoint equality.

wiggle_subpath

pub fn wiggle_subpath(
  segments: List(Segment),
) -> Result(Subpath, Error)

Create an open subpath while gently reconciling tiny endpoint gaps.

This is useful after floating-point transformations. If adjacent segment endpoints are within the default wiggle tolerance, the overlap point is used to make the segments continuous.