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
17package com.android.dx.util;
18
19import 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 */
26public 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