1 /* 2 * Copyright (C) 2011 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 5 * in compliance with the License. You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software distributed under the License 10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 11 * or implied. See the License for the specific language governing permissions and limitations under 12 * the License. 13 */ 14 15 package com.google.common.hash; 16 17 import com.google.common.annotations.Beta; 18 import com.google.errorprone.annotations.CanIgnoreReturnValue; 19 import java.nio.ByteBuffer; 20 import java.nio.charset.Charset; 21 22 /** 23 * An object which can receive a stream of primitive values. 24 * 25 * @author Kevin Bourrillion 26 * @since 12.0 (in 11.0 as {@code Sink}) 27 */ 28 @Beta 29 @CanIgnoreReturnValue 30 public interface PrimitiveSink { 31 /** 32 * Puts a byte into this sink. 33 * 34 * @param b a byte 35 * @return this instance 36 */ putByte(byte b)37 PrimitiveSink putByte(byte b); 38 39 /** 40 * Puts an array of bytes into this sink. 41 * 42 * @param bytes a byte array 43 * @return this instance 44 */ putBytes(byte[] bytes)45 PrimitiveSink putBytes(byte[] bytes); 46 47 /** 48 * Puts a chunk of an array of bytes into this sink. {@code bytes[off]} is the first byte written, 49 * {@code bytes[off + len - 1]} is the last. 50 * 51 * @param bytes a byte array 52 * @param off the start offset in the array 53 * @param len the number of bytes to write 54 * @return this instance 55 * @throws IndexOutOfBoundsException if {@code off < 0} or {@code off + len > bytes.length} or 56 * {@code len < 0} 57 */ putBytes(byte[] bytes, int off, int len)58 PrimitiveSink putBytes(byte[] bytes, int off, int len); 59 60 /** 61 * Puts the remaining bytes of a byte buffer into this sink. {@code bytes.position()} is the first 62 * byte written, {@code bytes.limit() - 1} is the last. The position of the buffer will be equal 63 * to the limit when this method returns. 64 * 65 * @param bytes a byte buffer 66 * @return this instance 67 * @since 23.0 68 */ putBytes(ByteBuffer bytes)69 PrimitiveSink putBytes(ByteBuffer bytes); 70 71 /** Puts a short into this sink. */ putShort(short s)72 PrimitiveSink putShort(short s); 73 74 /** Puts an int into this sink. */ putInt(int i)75 PrimitiveSink putInt(int i); 76 77 /** Puts a long into this sink. */ putLong(long l)78 PrimitiveSink putLong(long l); 79 80 /** Puts a float into this sink. */ putFloat(float f)81 PrimitiveSink putFloat(float f); 82 83 /** Puts a double into this sink. */ putDouble(double d)84 PrimitiveSink putDouble(double d); 85 86 /** Puts a boolean into this sink. */ putBoolean(boolean b)87 PrimitiveSink putBoolean(boolean b); 88 89 /** Puts a character into this sink. */ putChar(char c)90 PrimitiveSink putChar(char c); 91 92 /** 93 * Puts each 16-bit code unit from the {@link CharSequence} into this sink. 94 * 95 * <p><b>Warning:</b> This method will produce different output than most other languages do when 96 * running on the equivalent input. For cross-language compatibility, use {@link #putString}, 97 * usually with a charset of UTF-8. For other use cases, use {@code putUnencodedChars}. 98 * 99 * @since 15.0 (since 11.0 as putString(CharSequence)) 100 */ putUnencodedChars(CharSequence charSequence)101 PrimitiveSink putUnencodedChars(CharSequence charSequence); 102 103 /** 104 * Puts a string into this sink using the given charset. 105 * 106 * <p><b>Warning:</b> This method, which reencodes the input before processing it, is useful only 107 * for cross-language compatibility. For other use cases, prefer {@link #putUnencodedChars}, which 108 * is faster, produces the same output across Java releases, and processes every {@code char} in 109 * the input, even if some are invalid. 110 */ putString(CharSequence charSequence, Charset charset)111 PrimitiveSink putString(CharSequence charSequence, Charset charset); 112 } 113