software.amazon.ion.Span Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of ion-java Show documentation

A Java implementation of the Amazon Ion data notation.

There is a newer version: 1.5.1

/*
 * Copyright 2011-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License").
 * You may not use this file except in compliance with the License.
 * A copy of the License is located at:
 *
 *     http://aws.amazon.com/apache2.0/
 *
 * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
 * language governing permissions and limitations under the License.
 */

package software.amazon.ion;

import software.amazon.ion.facet.Faceted;
import software.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?
}