1 package nom.tam.util;
2
3 import java.io.DataOutput;
4
5 /*
6 * #%L
7 * nom.tam FITS library
8 * %%
9 * Copyright (C) 2004 - 2024 nom-tam-fits
10 * %%
11 * This is free and unencumbered software released into the public domain.
12 *
13 * Anyone is free to copy, modify, publish, use, compile, sell, or
14 * distribute this software, either in source code form or as a compiled
15 * binary, for any purpose, commercial or non-commercial, and by any
16 * means.
17 *
18 * In jurisdictions that recognize copyright laws, the author or authors
19 * of this software dedicate any and all copyright interest in the
20 * software to the public domain. We make this dedication for the benefit
21 * of the public at large and to the detriment of our heirs and
22 * successors. We intend this dedication to be an overt act of
23 * relinquishment in perpetuity of all present and future rights to this
24 * software under copyright law.
25 *
26 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
27 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
28 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
29 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
30 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
31 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
32 * OTHER DEALINGS IN THE SOFTWARE.
33 * #L%
34 */
35
36 import java.io.IOException;
37
38 /**
39 * Interface for writing array data to outputs.
40 */
41 public interface ArrayDataOutput extends OutputWriter, DataOutput, FitsIO {
42
43 /**
44 * Flush the output buffer
45 *
46 * @throws IOException if the flush of the underlying stream failed
47 */
48 void flush() throws IOException;
49
50 /**
51 * Write an array of boolean's.
52 *
53 * @param buf array of boolean's.
54 *
55 * @throws IOException if one of the underlying write operations failed
56 */
57 default void write(boolean[] buf) throws IOException {
58 write(buf, 0, buf.length);
59 }
60
61 /**
62 * Write a segment of an array of boolean's.
63 *
64 * @param buf array of boolean's.
65 * @param offset start index in the array
66 * @param size number of array elements to write
67 *
68 * @throws IOException if one of the underlying write operations failed
69 */
70 void write(boolean[] buf, int offset, int size) throws IOException;
71
72 /**
73 * Write an array of booleans, including legal <code>null</code> values.
74 *
75 * @param buf array of booleans.
76 *
77 * @throws IOException if one of the underlying write operations failed
78 *
79 * @since 1.16
80 */
81 default void write(Boolean[] buf) throws IOException {
82 write(buf, 0, buf.length);
83 }
84
85 /**
86 * Write a segment of an array of booleans, possibly including legal <code>null</code> values. The method has a
87 * default implementation, which calls {@link #writeBoolean(boolean)} element by element. Classes that implement
88 * this interface might want to replace that with a more efficient block read implementation/
89 *
90 * @param buf array of booleans.
91 * @param offset start index in the array
92 * @param size number of array elements to write
93 *
94 * @throws IOException if one of the underlying write operations failed
95 *
96 * @since 1.16
97 */
98 default void write(Boolean[] buf, int offset, int size) throws IOException {
99 int to = offset + size;
100
101 for (int i = offset; i < to; i++) {
102 writeBoolean(buf[i].booleanValue());
103 }
104 }
105
106 /**
107 * Write an array of char's.
108 *
109 * @param buf array of char's.
110 *
111 * @throws IOException if one of the underlying write operations failed
112 */
113 default void write(char[] buf) throws IOException {
114 write(buf, 0, buf.length);
115 }
116
117 /**
118 * Write a segment of an array of char's.
119 *
120 * @param buf array of char's.
121 * @param offset start index in the array
122 * @param size number of array elements to write
123 *
124 * @throws IOException if one of the underlying write operations failed
125 */
126 void write(char[] buf, int offset, int size) throws IOException;
127
128 /**
129 * Write an array of double's.
130 *
131 * @param buf array of double's.
132 *
133 * @throws IOException if one of the underlying write operations failed
134 */
135 default void write(double[] buf) throws IOException {
136 write(buf, 0, buf.length);
137 }
138
139 /**
140 * Write a segment of an array of double's.
141 *
142 * @param buf array of double's.
143 * @param offset start index in the array
144 * @param size number of array elements to write
145 *
146 * @throws IOException if one of the underlying write operations failed
147 */
148 void write(double[] buf, int offset, int size) throws IOException;
149
150 /**
151 * Write an array of float's.
152 *
153 * @param buf array of float's.
154 *
155 * @throws IOException if one of the underlying write operations failed
156 */
157 default void write(float[] buf) throws IOException {
158 write(buf, 0, buf.length);
159 }
160
161 /**
162 * Write a segment of an array of float's.
163 *
164 * @param buf array of float's.
165 * @param offset start index in the array
166 * @param size number of array elements to write
167 *
168 * @throws IOException if one of the underlying write operations failed
169 */
170 void write(float[] buf, int offset, int size) throws IOException;
171
172 /**
173 * Write an array of int's.
174 *
175 * @param buf array of int's
176 *
177 * @throws IOException if one of the underlying write operations failed
178 */
179 default void write(int[] buf) throws IOException {
180 write(buf, 0, buf.length);
181 }
182
183 /**
184 * Write a segment of an array of int's.
185 *
186 * @param buf array of int's
187 * @param offset start index in the array
188 * @param size number of array elements to write
189 *
190 * @throws IOException if one of the underlying write operations failed
191 */
192 void write(int[] buf, int offset, int size) throws IOException;
193
194 /**
195 * Write an array of longs.
196 *
197 * @param buf array of longs
198 *
199 * @throws IOException if one of the underlying write operations failed
200 */
201 default void write(long[] buf) throws IOException {
202 write(buf, 0, buf.length);
203 }
204
205 /**
206 * Write a segment of an array of longs.
207 *
208 * @param buf array of longs
209 * @param offset start index in the array
210 * @param size number of array elements to write
211 *
212 * @throws IOException if one of the underlying write operations failed
213 */
214 void write(long[] buf, int offset, int size) throws IOException;
215
216 /**
217 * Write an array of shorts.
218 *
219 * @param buf the value to write
220 *
221 * @throws IOException if one of the underlying write operations failed
222 */
223 default void write(short[] buf) throws IOException {
224 write(buf, 0, buf.length);
225 }
226
227 /**
228 * Write a segment of an array of shorts.
229 *
230 * @param buf the value to write
231 * @param offset start index in the array
232 * @param size number of array elements to write
233 *
234 * @throws IOException if one of the underlying write operations failed
235 */
236 void write(short[] buf, int offset, int size) throws IOException;
237
238 /**
239 * Write an array of Strings. Equivalent to calling writeBytes for the selected elements.
240 *
241 * @param buf the array to write
242 *
243 * @throws IOException if one of the underlying write operations failed
244 */
245 default void write(String[] buf) throws IOException {
246 write(buf, 0, buf.length);
247 }
248
249 /**
250 * Write a segment of an array of Strings. Equivalent to calling writeBytes for the selected elements.
251 *
252 * @param buf the array to write
253 * @param offset start index in the array
254 * @param size number of array elements to write
255 *
256 * @throws IOException if one of the underlying write operations failed
257 */
258 void write(String[] buf, int offset, int size) throws IOException;
259
260 /**
261 * Writes the contents of a Java array to the output translating the data to the required binary representation. The
262 * argument may be a generic Java array, including multi-dimensional arrays and heterogeneous arrays of arrays.
263 *
264 * @param o the Java array, including heterogeneous arrays of arrays. If <code>null</code>
265 * nothing will be written to the output.
266 *
267 * @throws IOException if there was an IO error writing to the output
268 * @throws IllegalArgumentException if the supplied object is not a Java array or if it contains Java types that are
269 * not supported by the encoder.
270 */
271 void writeArray(Object o) throws IOException, IllegalArgumentException;
272
273 }