com.amazon.ion.Span Maven / Gradle / Ivy
Show all versions of ion-java Show documentation
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazon.ion;
import com.amazon.ion.facet.Faceted;
import com.amazon.ion.util.Spans;
/**
* An immutable reference to a consecutive sequence of values (perhaps
* including large hierarchies) within some base source of Ion data.
*
* WARNING: This interface should not be implemented or extended by
* code outside of this library.
*
* A span is conceptually comprised of two abstract positions or
* offsets within the base source. The start position denotes the
* leftmost edge of the span, and the finish position denotes the
* rightmost edge.
* Positions lie between values, and when the start and finish
* positions are equal, the span is said to be empty.
*
* A span is said to cover the values that lie within its edges.
*
* A span is balanced if it starts and finishes within the same
* container, otherwise it is unbalanced. This library currently
* does not support unbalanced spans.
*
* Since different source types require different positioning techniques,
* spans is {@link Faceted} to expose the position implementation.
*
*
Acknowledgements
* This design and terminology is heavily based on Wilfred J. Hansen's work on
* subsequence references.
*
* @see SpanProvider
* @see Spans
* @see TextSpan
* @see OffsetSpan
*
* @see Subsequence
* References: First-Class Values for Substrings
*
*/
public interface Span
extends Faceted
{
/**
* Gets a span covering the container of this span.
*
* @throws IonException if the current span is at top-level.
*/
// public Span containerSpan(); // TODO later. Move to a facet?
/**
* Gets a span covering all the children of this span, which must cover a
* single container.
*
* @throws IonException if this span covers anything other than a
* single container.
*/
// public Span contentSpan(); // TODO later. Move to a facet?
}