com.ibm.cloud.objectstorage.thirdparty.ion.Span Maven / Gradle / Ivy
Show all versions of ibm-cos-java-sdk-bundle Show documentation
/*
* 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?
}