src/main/java/jp/sfjp/mikutoga/bin/parser/BinParser.java

   1 /*
   2  * binary parser interface
   3  *
   4  * License : The MIT License
   5  * Copyright(c) 2013 MikuToga Partners
   6  */
   7
   8 package jp.sfjp.mikutoga.bin.parser;
   9
  10 import java.io.IOException;
  11
  12 /**
  13  * バイナリパーサの共通インタフェース。
  14  *
  15  * <p>バイト列、各種プリミティブ型値およびエンコードされた文字列を読み込む。
  16  *
  17  * <p>long,double、およびビッグエンディアン形式のデータは未サポート。
  18  */
  19 public interface BinParser {
  20
  21     /**
  22      * 入力ソースの読み込み位置を返す。
  23      *
  24      * @return 入力ソースの読み込み位置。単位はbyte。
  25      */
  26     public abstract long getPosition();
  27
  28     /**
  29      * 入力ソースにまだデータが残っているか判定する。
  30      *
  31      * @return まだ読み込んでいないデータが残っていればtrue
  32      * @throws IOException IOエラー
  33      */
  34     public abstract boolean hasMore() throws IOException;
  35
  36     /**
  37      * 入力ソースを読み飛ばす。
  38      *
  39      * @param skipLength 読み飛ばすバイト数。
  40      * @throws IOException IOエラー
  41      * @throws MmdEofException 読み飛ばす途中でストリーム終端に達した。
  42      * @see java.io.InputStream#skip(long)
  43      */
  44     public abstract void skip(long skipLength)
  45             throws IOException, MmdEofException;
  46
  47     /**
  48      * byte配列を読み込む。
  49      *
  50      * @param dst 格納先配列
  51      * @param off 読み込み開始オフセット
  52      * @param length 読み込みバイト数
  53      * @throws NullPointerException 配列がnull
  54      * @throws IndexOutOfBoundsException 引数が配列属性と矛盾
  55      * @throws IOException IOエラー
  56      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
  57      * @see java.io.InputStream#read(byte[], int, int)
  58      */
  59     public abstract void parseByteArray(byte[] dst, int off, int length)
  60             throws NullPointerException,
  61                    IndexOutOfBoundsException,
  62                    IOException,
  63                    MmdEofException;
  64
  65     /**
  66      * byte配列を読み込む。
  67      *
  68      * <p>配列要素全ての読み込みが試みられる。
  69      *
  70      * @param dst 格納先配列
  71      * @throws NullPointerException 配列がnull
  72      * @throws IOException IOエラー
  73      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
  74      * @see java.io.InputStream#read(byte[])
  75      */
  76     public abstract void parseByteArray(byte[] dst)
  77             throws NullPointerException, IOException, MmdEofException;
  78
  79     /**
  80      * byte値を読み込む。
  81      *
  82      * @return 読み込んだbyte値
  83      * @throws IOException IOエラー
  84      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
  85      */
  86     public abstract byte parseByte() throws IOException, MmdEofException;
  87
  88     /**
  89      * 符号無し値としてbyte値を読み込み、int型に変換して返す。
  90      *
  91      * <p>符号は拡張されない。(0xffは0x000000ffとなる)
  92      *
  93      * @return 読み込まれた値のint値
  94      * @throws IOException IOエラー
  95      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
  96      */
  97     public abstract int parseUByteAsInt() throws IOException, MmdEofException;
  98
  99     /**
 100      * byte値を読み込み、boolean型に変換して返す。
 101      *
 102      * <p>0x00は偽、それ以外は真と解釈される。
 103      *
 104      * @return 読み込まれた値のboolean値
 105      * @throws IOException IOエラー
 106      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
 107      */
 108     public abstract boolean parseBoolean()
 109             throws IOException, MmdEofException;
 110
 111     /**
 112      * short値を読み込む。
 113      *
 114      * <p>short値はリトルエンディアンで格納されていると仮定される。
 115      *
 116      * @return 読み込んだshort値
 117      * @throws IOException IOエラー
 118      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
 119      */
 120     public abstract short parseLeShort() throws IOException, MmdEofException;
 121
 122     /**
 123      * 符号無し値としてshort値を読み込み、int型に変換して返す。
 124      *
 125      * <p>符号は拡張されない。(0xffffは0x0000ffffとなる)
 126      *
 127      * <p>short値はリトルエンディアンで格納されていると仮定される。
 128      *
 129      * @return 読み込まれた値のint値
 130      * @throws IOException IOエラー
 131      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
 132      */
 133     public abstract int parseLeUShortAsInt()
 134             throws IOException, MmdEofException;
 135
 136     /**
 137      * int値を読み込む。
 138      *
 139      * <p>int値はリトルエンディアンで格納されていると仮定される。
 140      *
 141      * @return 読み込んだint値
 142      * @throws IOException IOエラー
 143      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
 144      */
 145     public abstract int parseLeInt() throws IOException, MmdEofException;
 146
 147     /**
 148      * float値を読み込む。
 149      *
 150      * <p>float値はリトルエンディアンで格納されていると仮定される。
 151      *
 152      * @return 読み込んだfloat値
 153      * @throws IOException IOエラー
 154      * @throws MmdEofException 読み込む途中でストリーム終端に達した。
 155      */
 156     public abstract float parseLeFloat() throws IOException, MmdEofException;
 157
 158     /**
 159      * 固定バイト長の文字列を読み込む。
 160      * @param decoder 文字デコーダ
 161      * @param byteLen 読み込む固定バイト長
 162      * @return 文字列
 163      * @throws IOException 入力エラー
 164      * @throws MmdEofException 固定長バイト列を読む前に末端に達した。
 165      * @throws MmdFormatException 文字エンコーディングに関するエラー
 166      */
 167     public abstract String parseString(TextDecoder decoder, int byteLen)
 168             throws IOException, MmdEofException, MmdFormatException;
 169
 170 }