svg_path - v0.3.0

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.

Join

</>

How construction and editing helpers reconcile segment endpoints.

pub type Join {
  Strict
  Wiggle
  Bridge
  WiggleThenBridge
}

Constructors 

  • Strict

    Endpoints must already match exactly.

  • Wiggle

    Move nearby endpoints together within the default wiggle tolerance.

  • Bridge

    Keep endpoints unchanged and insert a straight line if needed.

  • WiggleThenBridge

    Try Wiggle; if that fails, use Bridge.

Path

</>

An SVG path, made of zero or more subpaths.

pub type Path {
  Path(subpaths: List(Subpath))
}

Constructors

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)

Segment

</>

A single SVG path segment.

pub type Segment {
  Line(start: vec2.Vec2(Float), end: vec2.Vec2(Float))
  QuadraticBezier(
    start: vec2.Vec2(Float),
    control: vec2.Vec2(Float),
    end: vec2.Vec2(Float),
  )
  CubicBezier(
    start: vec2.Vec2(Float),
    control1: vec2.Vec2(Float),
    control2: vec2.Vec2(Float),
    end: vec2.Vec2(Float),
  )
  Arc(
    start: vec2.Vec2(Float),
    radius: vec2.Vec2(Float),
    x_axis_rotation: Float,
    large_arc: Bool,
    sweep: Bool,
    end: vec2.Vec2(Float),
  )
}

Constructors

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_segment, or their _with variants to build values.

pub opaque type Subpath

Values

append_segment

</> 
pub fn append_segment(
  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.

append_segment_with

</> 
pub fn append_segment_with(
  subpath: Subpath,
  segment: Segment,
  join join: Join,
) -> Result(Subpath, Error)

Append a segment to an open subpath using the given join policy.

append_subpath

</> 
pub fn append_subpath(path: Path, subpath: Subpath) -> Path

Append a subpath to the end of a path.

arc

</> 
pub fn arc(
  start start: vec2.Vec2(Float),
  radius radius: vec2.Vec2(Float),
  x_axis_rotation x_axis_rotation: Float,
  large_arc large_arc: Bool,
  sweep sweep: Bool,
  end end: vec2.Vec2(Float),
) -> Segment

Create an elliptical arc segment.

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_append_segment

</> 
pub fn assert_append_segment(
  subpath: Subpath,
  segment: Segment,
) -> Subpath

Append a segment to an open subpath, panicking if invalid.

assert_append_segment_with

</> 
pub fn assert_append_segment_with(
  subpath: Subpath,
  segment: Segment,
  join join: Join,
) -> Subpath

Append a segment with a join policy, panicking if invalid.

assert_concat

</> 
pub fn assert_concat(first: Subpath, second: Subpath) -> Subpath

Concatenate two open subpaths, panicking if invalid.

assert_concat_with

</> 
pub fn assert_concat_with(
  first: Subpath,
  second: Subpath,
  join join: Join,
) -> Subpath

Concatenate two open subpaths with a join policy, panicking if invalid.

assert_set_closed

</> 
pub fn assert_set_closed(
  subpath: Subpath,
  closed closed: Bool,
) -> Subpath

Set a subpath’s semantic closed state, panicking if invalid.

assert_set_closed_with

</> 
pub fn assert_set_closed_with(
  subpath: Subpath,
  closed closed: Bool,
  join join: Join,
) -> Subpath

Set a subpath’s semantic closed state with a join policy, panicking if invalid.

assert_splice

</> 
pub fn assert_splice(
  subpath: Subpath,
  start start: Int,
  delete delete: Int,
  insert insert: List(Segment),
) -> Subpath

Replace a range of segments, panicking if the splice is invalid.

assert_splice_with

</> 
pub fn assert_splice_with(
  subpath: Subpath,
  start start: Int,
  delete delete: Int,
  insert insert: List(Segment),
  join join: Join,
) -> Subpath

Replace a range of segments with a join policy, panicking if invalid.

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.

assert_subpath_with

</> 
pub fn assert_subpath_with(
  segments: List(Segment),
  join join: Join,
) -> Subpath

Create an open subpath with a join policy, panicking if construction fails.

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.

concat

</> 
pub fn concat(
  first: Subpath,
  second: Subpath,
) -> Result(Subpath, Error)

Concatenate two open subpaths.

The first subpath’s end point must exactly match the second subpath’s start point. Empty open subpaths are treated as identity values.

concat_with

</> 
pub fn concat_with(
  first: Subpath,
  second: Subpath,
  join join: Join,
) -> Result(Subpath, Error)

Concatenate two open subpaths using the given join policy.

cubic_bezier

</> 
pub fn cubic_bezier(
  start start: vec2.Vec2(Float),
  control1 control1: vec2.Vec2(Float),
  control2 control2: vec2.Vec2(Float),
  end end: vec2.Vec2(Float),
) -> Segment

Create a cubic Bezier segment.

empty_path

</> 
pub fn empty_path() -> Path

Create an empty path.

empty_subpath

</> 
pub fn empty_subpath() -> Subpath

Create an empty open subpath.

end

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

Return the end point of a non-empty subpath.

from_subpath

</> 
pub fn from_subpath(subpath: Subpath) -> Path

Create a path containing a single subpath.

is_closed

</> 
pub fn is_closed(subpath: Subpath) -> Bool

Check whether a subpath is closed.

line

</> 
pub fn line(
  start start: vec2.Vec2(Float),
  end end: vec2.Vec2(Float),
) -> Segment

Create a straight line segment.

path

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

Create a path from a list of subpaths.

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.

quadratic_bezier

</> 
pub fn quadratic_bezier(
  start start: vec2.Vec2(Float),
  control control: vec2.Vec2(Float),
  end end: vec2.Vec2(Float),
) -> Segment

Create a quadratic Bezier segment.

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_end

</> 
pub fn segment_end(segment: Segment) -> vec2.Vec2(Float)

Return the end point of a segment.

segment_start

</> 
pub fn segment_start(segment: Segment) -> vec2.Vec2(Float)

Return the start point of a segment.

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.

segments

</> 
pub fn segments(subpath: Subpath) -> List(Segment)

Return the segments in a subpath.

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.

set_closed_with

</> 
pub fn set_closed_with(
  subpath: Subpath,
  closed closed: Bool,
  join join: Join,
) -> Result(Subpath, Error)

Set a subpath’s semantic closed state with a join policy.

Setting closed to False only clears the semantic closed flag. Setting it to True uses the given join policy to reconcile the subpath’s end point with 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.

splice_with

</> 
pub fn splice_with(
  subpath: Subpath,
  start start: Int,
  delete delete: Int,
  insert insert: List(Segment),
  join join: Join,
) -> Result(Subpath, Error)

Replace a range of segments in a subpath using the given join policy.

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.

subpath_with

</> 
pub fn subpath_with(
  segments: List(Segment),
  join join: Join,
) -> Result(Subpath, Error)

Create an open subpath using the given endpoint reconciliation policy.

subpaths

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

Return the subpaths in a path.

✨ Search Document