Home | History | Annotate | Download | only in util 
      1 /*
      2  * Copyright (C) 2007 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package com.android.dx.util;
     18 
     19 import com.android.dex.util.ByteOutput;
     20 
     21 /**
     22  * Interface for a sink for binary output. This is similar to
     23  * {@code java.util.DataOutput}, but no {@code IOExceptions}
     24  * are declared, and multibyte output is defined to be little-endian.
     25  */
     26 public interface Output extends ByteOutput {
     27     /**
     28      * Gets the current cursor position. This is the same as the number of
     29      * bytes written to this instance.
     30      *
     31      * @return {@code >= 0;} the cursor position
     32      */
     33     public int getCursor();
     34 
     35     /**
     36      * Asserts that the cursor is the given value.
     37      *
     38      * @param expectedCursor the expected cursor value
     39      * @throws RuntimeException thrown if {@code getCursor() !=
     40      * expectedCursor}
     41      */
     42     public void assertCursor(int expectedCursor);
     43 
     44     /**
     45      * Writes a {@code byte} to this instance.
     46      *
     47      * @param value the value to write; all but the low 8 bits are ignored
     48      */
     49     public void writeByte(int value);
     50 
     51     /**
     52      * Writes a {@code short} to this instance.
     53      *
     54      * @param value the value to write; all but the low 16 bits are ignored
     55      */
     56     public void writeShort(int value);
     57 
     58     /**
     59      * Writes an {@code int} to this instance.
     60      *
     61      * @param value the value to write
     62      */
     63     public void writeInt(int value);
     64 
     65     /**
     66      * Writes a {@code long} to this instance.
     67      *
     68      * @param value the value to write
     69      */
     70     public void writeLong(long value);
     71 
     72     /**
     73      * Writes a DWARFv3-style unsigned LEB128 integer. For details,
     74      * see the "Dalvik Executable Format" document or DWARF v3 section
     75      * 7.6.
     76      *
     77      * @param value value to write, treated as an unsigned value
     78      * @return {@code 1..5;} the number of bytes actually written
     79      */
     80     public int writeUleb128(int value);
     81 
     82     /**
     83      * Writes a DWARFv3-style unsigned LEB128 integer. For details,
     84      * see the "Dalvik Executable Format" document or DWARF v3 section
     85      * 7.6.
     86      *
     87      * @param value value to write
     88      * @return {@code 1..5;} the number of bytes actually written
     89      */
     90     public int writeSleb128(int value);
     91 
     92     /**
     93      * Writes a {@link ByteArray} to this instance.
     94      *
     95      * @param bytes {@code non-null;} the array to write
     96      */
     97     public void write(ByteArray bytes);
     98 
     99     /**
    100      * Writes a portion of a {@code byte[]} to this instance.
    101      *
    102      * @param bytes {@code non-null;} the array to write
    103      * @param offset {@code >= 0;} offset into {@code bytes} for the first
    104      * byte to write
    105      * @param length {@code >= 0;} number of bytes to write
    106      */
    107     public void write(byte[] bytes, int offset, int length);
    108 
    109     /**
    110      * Writes a {@code byte[]} to this instance. This is just
    111      * a convenient shorthand for {@code write(bytes, 0, bytes.length)}.
    112      *
    113      * @param bytes {@code non-null;} the array to write
    114      */
    115     public void write(byte[] bytes);
    116 
    117     /**
    118      * Writes the given number of {@code 0} bytes.
    119      *
    120      * @param count {@code >= 0;} the number of zeroes to write
    121      */
    122     public void writeZeroes(int count);
    123 
    124     /**
    125      * Adds extra bytes if necessary (with value {@code 0}) to
    126      * force alignment of the output cursor as given.
    127      *
    128      * @param alignment {@code > 0;} the alignment; must be a power of two
    129      */
    130     public void alignTo(int alignment);
    131 }
    132