package org.litesoft.codec;

import org.litesoft.commonfoundation.charstreams.*;
import org.litesoft.commonfoundation.annotations.*;

/**
 * Implementations of this TypedTerminatingCodec must produce and consume self-terminating encodings.
 * <p/>
 * A self-terminating encoded value, when decoding, will only consume as many characters
 * from the CharSource as were generated by the encode method.
 */
public interface TypedTerminatingCodec<T>
{
    /**
     * Encode the Value into a self-terminating non-Null String.
     */
    @NotNull String encode( @Nullable T pValue );

    /**
     * Encode the Value (as a self-terminating character sequence) into the StringBuilder.
     */
    void encode( @NotNull CharSink pCharSink, @Nullable T pValue );

    /**
     * Decode the Value as a self-terminating non-Null String (generated by the encode method).
     * <p/>
     * Note: No extraneous characters allowed on the parameter Value.
     */
    @Nullable T decode( @NotNull CharSequence pValue );

    /**
     * Decode the next self-terminating character stream from the CharSource.
     */
    @Nullable T decode( @NotNull CharSource pCharSource );
}