Source code

001/*
002 * Copyright (C) 2012 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.io;
016
017import static com.google.common.base.Preconditions.checkArgument;
018import static com.google.common.base.Preconditions.checkNotNull;
019import static com.google.common.base.Preconditions.checkPositionIndexes;
020import static com.google.common.base.Preconditions.checkState;
021import static com.google.common.math.IntMath.divide;
022import static com.google.common.math.IntMath.log2;
023import static java.math.RoundingMode.CEILING;
024import static java.math.RoundingMode.FLOOR;
025import static java.math.RoundingMode.UNNECESSARY;
026
027import com.google.common.annotations.GwtCompatible;
028import com.google.common.annotations.GwtIncompatible;
029import com.google.common.base.Ascii;
030import com.google.common.base.Objects;
031import com.google.errorprone.annotations.concurrent.LazyInit;
032import java.io.IOException;
033import java.io.InputStream;
034import java.io.OutputStream;
035import java.io.Reader;
036import java.io.Writer;
037import java.util.Arrays;
038import org.checkerframework.checker.nullness.compatqual.NullableDecl;
039
040/**
041 * A binary encoding scheme for reversibly translating between byte sequences and printable ASCII
042 * strings. This class includes several constants for encoding schemes specified by <a
043 * href="http://tools.ietf.org/html/rfc4648">RFC 4648</a>. For example, the expression:
044 *
045 * <pre>{@code
046 * BaseEncoding.base32().encode("foo".getBytes(Charsets.US_ASCII))
047 * }</pre>
048 *
049 * <p>returns the string {@code "MZXW6==="}, and
050 *
051 * <pre>{@code
052 * byte[] decoded = BaseEncoding.base32().decode("MZXW6===");
053 * }</pre>
054 *
055 * <p>...returns the ASCII bytes of the string {@code "foo"}.
056 *
057 * <p>By default, {@code BaseEncoding}'s behavior is relatively strict and in accordance with RFC
058 * 4648. Decoding rejects characters in the wrong case, though padding is optional. To modify
059 * encoding and decoding behavior, use configuration methods to obtain a new encoding with modified
060 * behavior:
061 *
062 * <pre>{@code
063 * BaseEncoding.base16().lowerCase().decode("deadbeef");
064 * }</pre>
065 *
066 * <p>Warning: BaseEncoding instances are immutable. Invoking a configuration method has no effect
067 * on the receiving instance; you must store and use the new encoding instance it returns, instead.
068 *
069 * <pre>{@code
070 * // Do NOT do this
071 * BaseEncoding hex = BaseEncoding.base16();
072 * hex.lowerCase(); // does nothing!
073 * return hex.decode("deadbeef"); // throws an IllegalArgumentException
074 * }</pre>
075 *
076 * <p>It is guaranteed that {@code encoding.decode(encoding.encode(x))} is always equal to {@code
077 * x}, but the reverse does not necessarily hold.
078 *
079 * <table>
080 * <caption>Encodings</caption>
081 * <tr>
082 * <th>Encoding
083 * <th>Alphabet
084 * <th>{@code char:byte} ratio
085 * <th>Default padding
086 * <th>Comments
087 * <tr>
088 * <td>{@link #base16()}
089 * <td>0-9 A-F
090 * <td>2.00
091 * <td>N/A
092 * <td>Traditional hexadecimal. Defaults to upper case.
093 * <tr>
094 * <td>{@link #base32()}
095 * <td>A-Z 2-7
096 * <td>1.60
097 * <td>=
098 * <td>Human-readable; no possibility of mixing up 0/O or 1/I. Defaults to upper case.
099 * <tr>
100 * <td>{@link #base32Hex()}
101 * <td>0-9 A-V
102 * <td>1.60
103 * <td>=
104 * <td>"Numerical" base 32; extended from the traditional hex alphabet. Defaults to upper case.
105 * <tr>
106 * <td>{@link #base64()}
107 * <td>A-Z a-z 0-9 + /
108 * <td>1.33
109 * <td>=
110 * <td>
111 * <tr>
112 * <td>{@link #base64Url()}
113 * <td>A-Z a-z 0-9 - _
114 * <td>1.33
115 * <td>=
116 * <td>Safe to use as filenames, or to pass in URLs without escaping
117 * </table>
118 *
119 * <p>All instances of this class are immutable, so they may be stored safely as static constants.
120 *
121 * @author Louis Wasserman
122 * @since 14.0
123 */
124@GwtCompatible(emulated = true)
125public abstract class BaseEncoding {
126  // TODO(lowasser): consider making encodeTo(Appendable, byte[], int, int) public.
127
128  BaseEncoding() {}
129
130  /**
131   * Exception indicating invalid base-encoded input encountered while decoding.
132   *
133   * @author Louis Wasserman
134   * @since 15.0
135   */
136  public static final class DecodingException extends IOException {
137    DecodingException(String message) {
138      super(message);
139    }
140
141    DecodingException(Throwable cause) {
142      super(cause);
143    }
144  }
145
146  /** Encodes the specified byte array, and returns the encoded {@code String}. */
147  public String encode(byte[] bytes) {
148    return encode(bytes, 0, bytes.length);
149  }
150
151  /**
152   * Encodes the specified range of the specified byte array, and returns the encoded {@code
153   * String}.
154   */
155  public final String encode(byte[] bytes, int off, int len) {
156    checkPositionIndexes(off, off + len, bytes.length);
157    StringBuilder result = new StringBuilder(maxEncodedSize(len));
158    try {
159      encodeTo(result, bytes, off, len);
160    } catch (IOException impossible) {
161      throw new AssertionError(impossible);
162    }
163    return result.toString();
164  }
165
166  /**
167   * Returns an {@code OutputStream} that encodes bytes using this encoding into the specified
168   * {@code Writer}. When the returned {@code OutputStream} is closed, so is the backing {@code
169   * Writer}.
170   */
171  @GwtIncompatible // Writer,OutputStream
172  public abstract OutputStream encodingStream(Writer writer);
173
174  /**
175   * Returns a {@code ByteSink} that writes base-encoded bytes to the specified {@code CharSink}.
176   */
177  @GwtIncompatible // ByteSink,CharSink
178  public final ByteSink encodingSink(final CharSink encodedSink) {
179    checkNotNull(encodedSink);
180    return new ByteSink() {
181      @Override
182      public OutputStream openStream() throws IOException {
183        return encodingStream(encodedSink.openStream());
184      }
185    };
186  }
187
188  // TODO(lowasser): document the extent of leniency, probably after adding ignore(CharMatcher)
189
190  private static byte[] extract(byte[] result, int length) {
191    if (length == result.length) {
192      return result;
193    }
194    byte[] trunc = new byte[length];
195    System.arraycopy(result, 0, trunc, 0, length);
196    return trunc;
197  }
198
199  /**
200   * Determines whether the specified character sequence is a valid encoded string according to this
201   * encoding.
202   *
203   * @since 20.0
204   */
205  public abstract boolean canDecode(CharSequence chars);
206
207  /**
208   * Decodes the specified character sequence, and returns the resulting {@code byte[]}. This is the
209   * inverse operation to {@link #encode(byte[])}.
210   *
211   * @throws IllegalArgumentException if the input is not a valid encoded string according to this
212   *     encoding.
213   */
214  public final byte[] decode(CharSequence chars) {
215    try {
216      return decodeChecked(chars);
217    } catch (DecodingException badInput) {
218      throw new IllegalArgumentException(badInput);
219    }
220  }
221
222  /**
223   * Decodes the specified character sequence, and returns the resulting {@code byte[]}. This is the
224   * inverse operation to {@link #encode(byte[])}.
225   *
226   * @throws DecodingException if the input is not a valid encoded string according to this
227   *     encoding.
228   */
229  final byte[] decodeChecked(CharSequence chars)
230      throws DecodingException {
231    chars = trimTrailingPadding(chars);
232    byte[] tmp = new byte[maxDecodedSize(chars.length())];
233    int len = decodeTo(tmp, chars);
234    return extract(tmp, len);
235  }
236
237  /**
238   * Returns an {@code InputStream} that decodes base-encoded input from the specified {@code
239   * Reader}. The returned stream throws a {@link DecodingException} upon decoding-specific errors.
240   */
241  @GwtIncompatible // Reader,InputStream
242  public abstract InputStream decodingStream(Reader reader);
243
244  /**
245   * Returns a {@code ByteSource} that reads base-encoded bytes from the specified {@code
246   * CharSource}.
247   */
248  @GwtIncompatible // ByteSource,CharSource
249  public final ByteSource decodingSource(final CharSource encodedSource) {
250    checkNotNull(encodedSource);
251    return new ByteSource() {
252      @Override
253      public InputStream openStream() throws IOException {
254        return decodingStream(encodedSource.openStream());
255      }
256    };
257  }
258
259  // Implementations for encoding/decoding
260
261  abstract int maxEncodedSize(int bytes);
262
263  abstract void encodeTo(Appendable target, byte[] bytes, int off, int len) throws IOException;
264
265  abstract int maxDecodedSize(int chars);
266
267  abstract int decodeTo(byte[] target, CharSequence chars) throws DecodingException;
268
269  CharSequence trimTrailingPadding(CharSequence chars) {
270    return checkNotNull(chars);
271  }
272
273  // Modified encoding generators
274
275  /**
276   * Returns an encoding that behaves equivalently to this encoding, but omits any padding
277   * characters as specified by <a href="http://tools.ietf.org/html/rfc4648#section-3.2">RFC 4648
278   * section 3.2</a>, Padding of Encoded Data.
279   */
280  public abstract BaseEncoding omitPadding();
281
282  /**
283   * Returns an encoding that behaves equivalently to this encoding, but uses an alternate character
284   * for padding.
285   *
286   * @throws IllegalArgumentException if this padding character is already used in the alphabet or a
287   *     separator
288   */
289  public abstract BaseEncoding withPadChar(char padChar);
290
291  /**
292   * Returns an encoding that behaves equivalently to this encoding, but adds a separator string
293   * after every {@code n} characters. Any occurrences of any characters that occur in the separator
294   * are skipped over in decoding.
295   *
296   * @throws IllegalArgumentException if any alphabet or padding characters appear in the separator
297   *     string, or if {@code n <= 0}
298   * @throws UnsupportedOperationException if this encoding already uses a separator
299   */
300  public abstract BaseEncoding withSeparator(String separator, int n);
301
302  /**
303   * Returns an encoding that behaves equivalently to this encoding, but encodes and decodes with
304   * uppercase letters. Padding and separator characters remain in their original case.
305   *
306   * @throws IllegalStateException if the alphabet used by this encoding contains mixed upper- and
307   *     lower-case characters
308   */
309  public abstract BaseEncoding upperCase();
310
311  /**
312   * Returns an encoding that behaves equivalently to this encoding, but encodes and decodes with
313   * lowercase letters. Padding and separator characters remain in their original case.
314   *
315   * @throws IllegalStateException if the alphabet used by this encoding contains mixed upper- and
316   *     lower-case characters
317   */
318  public abstract BaseEncoding lowerCase();
319
320  private static final BaseEncoding BASE64 =
321      new Base64Encoding(
322          "base64()", "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/", '=');
323
324  /**
325   * The "base64" base encoding specified by <a
326   * href="http://tools.ietf.org/html/rfc4648#section-4">RFC 4648 section 4</a>, Base 64 Encoding.
327   * (This is the same as the base 64 encoding from <a
328   * href="http://tools.ietf.org/html/rfc3548#section-3">RFC 3548</a>.)
329   *
330   * <p>The character {@code '='} is used for padding, but can be {@linkplain #omitPadding()
331   * omitted} or {@linkplain #withPadChar(char) replaced}.
332   *
333   * <p>No line feeds are added by default, as per <a
334   * href="http://tools.ietf.org/html/rfc4648#section-3.1">RFC 4648 section 3.1</a>, Line Feeds in
335   * Encoded Data. Line feeds may be added using {@link #withSeparator(String, int)}.
336   */
337  public static BaseEncoding base64() {
338    return BASE64;
339  }
340
341  private static final BaseEncoding BASE64_URL =
342      new Base64Encoding(
343          "base64Url()", "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_", '=');
344
345  /**
346   * The "base64url" encoding specified by <a
347   * href="http://tools.ietf.org/html/rfc4648#section-5">RFC 4648 section 5</a>, Base 64 Encoding
348   * with URL and Filename Safe Alphabet, also sometimes referred to as the "web safe Base64." (This
349   * is the same as the base 64 encoding with URL and filename safe alphabet from <a
350   * href="http://tools.ietf.org/html/rfc3548#section-4">RFC 3548</a>.)
351   *
352   * <p>The character {@code '='} is used for padding, but can be {@linkplain #omitPadding()
353   * omitted} or {@linkplain #withPadChar(char) replaced}.
354   *
355   * <p>No line feeds are added by default, as per <a
356   * href="http://tools.ietf.org/html/rfc4648#section-3.1">RFC 4648 section 3.1</a>, Line Feeds in
357   * Encoded Data. Line feeds may be added using {@link #withSeparator(String, int)}.
358   */
359  public static BaseEncoding base64Url() {
360    return BASE64_URL;
361  }
362
363  private static final BaseEncoding BASE32 =
364      new StandardBaseEncoding("base32()", "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567", '=');
365
366  /**
367   * The "base32" encoding specified by <a href="http://tools.ietf.org/html/rfc4648#section-6">RFC
368   * 4648 section 6</a>, Base 32 Encoding. (This is the same as the base 32 encoding from <a
369   * href="http://tools.ietf.org/html/rfc3548#section-5">RFC 3548</a>.)
370   *
371   * <p>The character {@code '='} is used for padding, but can be {@linkplain #omitPadding()
372   * omitted} or {@linkplain #withPadChar(char) replaced}.
373   *
374   * <p>No line feeds are added by default, as per <a
375   * href="http://tools.ietf.org/html/rfc4648#section-3.1">RFC 4648 section 3.1</a>, Line Feeds in
376   * Encoded Data. Line feeds may be added using {@link #withSeparator(String, int)}.
377   */
378  public static BaseEncoding base32() {
379    return BASE32;
380  }
381
382  private static final BaseEncoding BASE32_HEX =
383      new StandardBaseEncoding("base32Hex()", "0123456789ABCDEFGHIJKLMNOPQRSTUV", '=');
384
385  /**
386   * The "base32hex" encoding specified by <a
387   * href="http://tools.ietf.org/html/rfc4648#section-7">RFC 4648 section 7</a>, Base 32 Encoding
388   * with Extended Hex Alphabet. There is no corresponding encoding in RFC 3548.
389   *
390   * <p>The character {@code '='} is used for padding, but can be {@linkplain #omitPadding()
391   * omitted} or {@linkplain #withPadChar(char) replaced}.
392   *
393   * <p>No line feeds are added by default, as per <a
394   * href="http://tools.ietf.org/html/rfc4648#section-3.1">RFC 4648 section 3.1</a>, Line Feeds in
395   * Encoded Data. Line feeds may be added using {@link #withSeparator(String, int)}.
396   */
397  public static BaseEncoding base32Hex() {
398    return BASE32_HEX;
399  }
400
401  private static final BaseEncoding BASE16 = new Base16Encoding("base16()", "0123456789ABCDEF");
402
403  /**
404   * The "base16" encoding specified by <a href="http://tools.ietf.org/html/rfc4648#section-8">RFC
405   * 4648 section 8</a>, Base 16 Encoding. (This is the same as the base 16 encoding from <a
406   * href="http://tools.ietf.org/html/rfc3548#section-6">RFC 3548</a>.) This is commonly known as
407   * "hexadecimal" format.
408   *
409   * <p>No padding is necessary in base 16, so {@link #withPadChar(char)} and {@link #omitPadding()}
410   * have no effect.
411   *
412   * <p>No line feeds are added by default, as per <a
413   * href="http://tools.ietf.org/html/rfc4648#section-3.1">RFC 4648 section 3.1</a>, Line Feeds in
414   * Encoded Data. Line feeds may be added using {@link #withSeparator(String, int)}.
415   */
416  public static BaseEncoding base16() {
417    return BASE16;
418  }
419
420  private static final class Alphabet {
421    private final String name;
422    // this is meant to be immutable -- don't modify it!
423    private final char[] chars;
424    final int mask;
425    final int bitsPerChar;
426    final int charsPerChunk;
427    final int bytesPerChunk;
428    private final byte[] decodabet;
429    private final boolean[] validPadding;
430
431    Alphabet(String name, char[] chars) {
432      this.name = checkNotNull(name);
433      this.chars = checkNotNull(chars);
434      try {
435        this.bitsPerChar = log2(chars.length, UNNECESSARY);
436      } catch (ArithmeticException e) {
437        throw new IllegalArgumentException("Illegal alphabet length " + chars.length, e);
438      }
439
440      /*
441       * e.g. for base64, bitsPerChar == 6, charsPerChunk == 4, and bytesPerChunk == 3. This makes
442       * for the smallest chunk size that still has charsPerChunk * bitsPerChar be a multiple of 8.
443       */
444      int gcd = Math.min(8, Integer.lowestOneBit(bitsPerChar));
445      try {
446        this.charsPerChunk = 8 / gcd;
447        this.bytesPerChunk = bitsPerChar / gcd;
448      } catch (ArithmeticException e) {
449        throw new IllegalArgumentException("Illegal alphabet " + new String(chars), e);
450      }
451
452      this.mask = chars.length - 1;
453
454      byte[] decodabet = new byte[Ascii.MAX + 1];
455      Arrays.fill(decodabet, (byte) -1);
456      for (int i = 0; i < chars.length; i++) {
457        char c = chars[i];
458        checkArgument(c < decodabet.length, "Non-ASCII character: %s", c);
459        checkArgument(decodabet[c] == -1, "Duplicate character: %s", c);
460        decodabet[c] = (byte) i;
461      }
462      this.decodabet = decodabet;
463
464      boolean[] validPadding = new boolean[charsPerChunk];
465      for (int i = 0; i < bytesPerChunk; i++) {
466        validPadding[divide(i * 8, bitsPerChar, CEILING)] = true;
467      }
468      this.validPadding = validPadding;
469    }
470
471    char encode(int bits) {
472      return chars[bits];
473    }
474
475    boolean isValidPaddingStartPosition(int index) {
476      return validPadding[index % charsPerChunk];
477    }
478
479    boolean canDecode(char ch) {
480      return ch <= Ascii.MAX && decodabet[ch] != -1;
481    }
482
483    int decode(char ch) throws DecodingException {
484      if (ch > Ascii.MAX) {
485        throw new DecodingException("Unrecognized character: 0x" + Integer.toHexString(ch));
486      }
487      int result = decodabet[ch];
488      if (result == -1) {
489        if (ch <= 0x20 || ch == Ascii.MAX) {
490          throw new DecodingException("Unrecognized character: 0x" + Integer.toHexString(ch));
491        } else {
492          throw new DecodingException("Unrecognized character: " + ch);
493        }
494      }
495      return result;
496    }
497
498    private boolean hasLowerCase() {
499      for (char c : chars) {
500        if (Ascii.isLowerCase(c)) {
501          return true;
502        }
503      }
504      return false;
505    }
506
507    private boolean hasUpperCase() {
508      for (char c : chars) {
509        if (Ascii.isUpperCase(c)) {
510          return true;
511        }
512      }
513      return false;
514    }
515
516    Alphabet upperCase() {
517      if (!hasLowerCase()) {
518        return this;
519      }
520      checkState(!hasUpperCase(), "Cannot call upperCase() on a mixed-case alphabet");
521      char[] upperCased = new char[chars.length];
522      for (int i = 0; i < chars.length; i++) {
523        upperCased[i] = Ascii.toUpperCase(chars[i]);
524      }
525      return new Alphabet(name + ".upperCase()", upperCased);
526    }
527
528    Alphabet lowerCase() {
529      if (!hasUpperCase()) {
530        return this;
531      }
532      checkState(!hasLowerCase(), "Cannot call lowerCase() on a mixed-case alphabet");
533      char[] lowerCased = new char[chars.length];
534      for (int i = 0; i < chars.length; i++) {
535        lowerCased[i] = Ascii.toLowerCase(chars[i]);
536      }
537      return new Alphabet(name + ".lowerCase()", lowerCased);
538    }
539
540    public boolean matches(char c) {
541      return c < decodabet.length && decodabet[c] != -1;
542    }
543
544    @Override
545    public String toString() {
546      return name;
547    }
548
549    @Override
550    public boolean equals(@NullableDecl Object other) {
551      if (other instanceof Alphabet) {
552        Alphabet that = (Alphabet) other;
553        return Arrays.equals(this.chars, that.chars);
554      }
555      return false;
556    }
557
558    @Override
559    public int hashCode() {
560      return Arrays.hashCode(chars);
561    }
562  }
563
564  static class StandardBaseEncoding extends BaseEncoding {
565    // TODO(lowasser): provide a useful toString
566    final Alphabet alphabet;
567
568    @NullableDecl final Character paddingChar;
569
570    StandardBaseEncoding(String name, String alphabetChars, @NullableDecl Character paddingChar) {
571      this(new Alphabet(name, alphabetChars.toCharArray()), paddingChar);
572    }
573
574    StandardBaseEncoding(Alphabet alphabet, @NullableDecl Character paddingChar) {
575      this.alphabet = checkNotNull(alphabet);
576      checkArgument(
577          paddingChar == null || !alphabet.matches(paddingChar),
578          "Padding character %s was already in alphabet",
579          paddingChar);
580      this.paddingChar = paddingChar;
581    }
582
583    @Override
584    int maxEncodedSize(int bytes) {
585      return alphabet.charsPerChunk * divide(bytes, alphabet.bytesPerChunk, CEILING);
586    }
587
588    @GwtIncompatible // Writer,OutputStream
589    @Override
590    public OutputStream encodingStream(final Writer out) {
591      checkNotNull(out);
592      return new OutputStream() {
593        int bitBuffer = 0;
594        int bitBufferLength = 0;
595        int writtenChars = 0;
596
597        @Override
598        public void write(int b) throws IOException {
599          bitBuffer <<= 8;
600          bitBuffer |= b & 0xFF;
601          bitBufferLength += 8;
602          while (bitBufferLength >= alphabet.bitsPerChar) {
603            int charIndex = (bitBuffer >> (bitBufferLength - alphabet.bitsPerChar)) & alphabet.mask;
604            out.write(alphabet.encode(charIndex));
605            writtenChars++;
606            bitBufferLength -= alphabet.bitsPerChar;
607          }
608        }
609
610        @Override
611        public void flush() throws IOException {
612          out.flush();
613        }
614
615        @Override
616        public void close() throws IOException {
617          if (bitBufferLength > 0) {
618            int charIndex = (bitBuffer << (alphabet.bitsPerChar - bitBufferLength)) & alphabet.mask;
619            out.write(alphabet.encode(charIndex));
620            writtenChars++;
621            if (paddingChar != null) {
622              while (writtenChars % alphabet.charsPerChunk != 0) {
623                out.write(paddingChar.charValue());
624                writtenChars++;
625              }
626            }
627          }
628          out.close();
629        }
630      };
631    }
632
633    @Override
634    void encodeTo(Appendable target, byte[] bytes, int off, int len) throws IOException {
635      checkNotNull(target);
636      checkPositionIndexes(off, off + len, bytes.length);
637      for (int i = 0; i < len; i += alphabet.bytesPerChunk) {
638        encodeChunkTo(target, bytes, off + i, Math.min(alphabet.bytesPerChunk, len - i));
639      }
640    }
641
642    void encodeChunkTo(Appendable target, byte[] bytes, int off, int len) throws IOException {
643      checkNotNull(target);
644      checkPositionIndexes(off, off + len, bytes.length);
645      checkArgument(len <= alphabet.bytesPerChunk);
646      long bitBuffer = 0;
647      for (int i = 0; i < len; ++i) {
648        bitBuffer |= bytes[off + i] & 0xFF;
649        bitBuffer <<= 8; // Add additional zero byte in the end.
650      }
651      // Position of first character is length of bitBuffer minus bitsPerChar.
652      final int bitOffset = (len + 1) * 8 - alphabet.bitsPerChar;
653      int bitsProcessed = 0;
654      while (bitsProcessed < len * 8) {
655        int charIndex = (int) (bitBuffer >>> (bitOffset - bitsProcessed)) & alphabet.mask;
656        target.append(alphabet.encode(charIndex));
657        bitsProcessed += alphabet.bitsPerChar;
658      }
659      if (paddingChar != null) {
660        while (bitsProcessed < alphabet.bytesPerChunk * 8) {
661          target.append(paddingChar.charValue());
662          bitsProcessed += alphabet.bitsPerChar;
663        }
664      }
665    }
666
667    @Override
668    int maxDecodedSize(int chars) {
669      return (int) ((alphabet.bitsPerChar * (long) chars + 7L) / 8L);
670    }
671
672    @Override
673    CharSequence trimTrailingPadding(CharSequence chars) {
674      checkNotNull(chars);
675      if (paddingChar == null) {
676        return chars;
677      }
678      char padChar = paddingChar.charValue();
679      int l;
680      for (l = chars.length() - 1; l >= 0; l--) {
681        if (chars.charAt(l) != padChar) {
682          break;
683        }
684      }
685      return chars.subSequence(0, l + 1);
686    }
687
688    @Override
689    public boolean canDecode(CharSequence chars) {
690      checkNotNull(chars);
691      chars = trimTrailingPadding(chars);
692      if (!alphabet.isValidPaddingStartPosition(chars.length())) {
693        return false;
694      }
695      for (int i = 0; i < chars.length(); i++) {
696        if (!alphabet.canDecode(chars.charAt(i))) {
697          return false;
698        }
699      }
700      return true;
701    }
702
703    @Override
704    int decodeTo(byte[] target, CharSequence chars) throws DecodingException {
705      checkNotNull(target);
706      chars = trimTrailingPadding(chars);
707      if (!alphabet.isValidPaddingStartPosition(chars.length())) {
708        throw new DecodingException("Invalid input length " + chars.length());
709      }
710      int bytesWritten = 0;
711      for (int charIdx = 0; charIdx < chars.length(); charIdx += alphabet.charsPerChunk) {
712        long chunk = 0;
713        int charsProcessed = 0;
714        for (int i = 0; i < alphabet.charsPerChunk; i++) {
715          chunk <<= alphabet.bitsPerChar;
716          if (charIdx + i < chars.length()) {
717            chunk |= alphabet.decode(chars.charAt(charIdx + charsProcessed++));
718          }
719        }
720        final int minOffset = alphabet.bytesPerChunk * 8 - charsProcessed * alphabet.bitsPerChar;
721        for (int offset = (alphabet.bytesPerChunk - 1) * 8; offset >= minOffset; offset -= 8) {
722          target[bytesWritten++] = (byte) ((chunk >>> offset) & 0xFF);
723        }
724      }
725      return bytesWritten;
726    }
727
728    @Override
729    @GwtIncompatible // Reader,InputStream
730    public InputStream decodingStream(final Reader reader) {
731      checkNotNull(reader);
732      return new InputStream() {
733        int bitBuffer = 0;
734        int bitBufferLength = 0;
735        int readChars = 0;
736        boolean hitPadding = false;
737
738        @Override
739        public int read() throws IOException {
740          while (true) {
741            int readChar = reader.read();
742            if (readChar == -1) {
743              if (!hitPadding && !alphabet.isValidPaddingStartPosition(readChars)) {
744                throw new DecodingException("Invalid input length " + readChars);
745              }
746              return -1;
747            }
748            readChars++;
749            char ch = (char) readChar;
750            if (paddingChar != null && paddingChar.charValue() == ch) {
751              if (!hitPadding
752                  && (readChars == 1 || !alphabet.isValidPaddingStartPosition(readChars - 1))) {
753                throw new DecodingException("Padding cannot start at index " + readChars);
754              }
755              hitPadding = true;
756            } else if (hitPadding) {
757              throw new DecodingException(
758                  "Expected padding character but found '" + ch + "' at index " + readChars);
759            } else {
760              bitBuffer <<= alphabet.bitsPerChar;
761              bitBuffer |= alphabet.decode(ch);
762              bitBufferLength += alphabet.bitsPerChar;
763
764              if (bitBufferLength >= 8) {
765                bitBufferLength -= 8;
766                return (bitBuffer >> bitBufferLength) & 0xFF;
767              }
768            }
769          }
770        }
771
772        @Override
773        public int read(byte[] buf, int off, int len) throws IOException {
774          // Overriding this to work around the fact that InputStream's default implementation of
775          // this method will silently swallow exceptions thrown by the single-byte read() method
776          // (other than on the first call to it), which in this case can cause invalid encoded
777          // strings to not throw an exception.
778          // See https://github.com/google/guava/issues/3542
779          checkPositionIndexes(off, off + len, buf.length);
780
781          int i = off;
782          for (; i < off + len; i++) {
783            int b = read();
784            if (b == -1) {
785              int read = i - off;
786              return read == 0 ? -1 : read;
787            }
788            buf[i] = (byte) b;
789          }
790          return i - off;
791        }
792
793        @Override
794        public void close() throws IOException {
795          reader.close();
796        }
797      };
798    }
799
800    @Override
801    public BaseEncoding omitPadding() {
802      return (paddingChar == null) ? this : newInstance(alphabet, null);
803    }
804
805    @Override
806    public BaseEncoding withPadChar(char padChar) {
807      if (8 % alphabet.bitsPerChar == 0
808          || (paddingChar != null && paddingChar.charValue() == padChar)) {
809        return this;
810      } else {
811        return newInstance(alphabet, padChar);
812      }
813    }
814
815    @Override
816    public BaseEncoding withSeparator(String separator, int afterEveryChars) {
817      for (int i = 0; i < separator.length(); i++) {
818        checkArgument(
819            !alphabet.matches(separator.charAt(i)),
820            "Separator (%s) cannot contain alphabet characters",
821            separator);
822      }
823      if (paddingChar != null) {
824        checkArgument(
825            separator.indexOf(paddingChar.charValue()) < 0,
826            "Separator (%s) cannot contain padding character",
827            separator);
828      }
829      return new SeparatedBaseEncoding(this, separator, afterEveryChars);
830    }
831
832    @LazyInit @NullableDecl private transient BaseEncoding upperCase;
833    @LazyInit @NullableDecl private transient BaseEncoding lowerCase;
834
835    @Override
836    public BaseEncoding upperCase() {
837      BaseEncoding result = upperCase;
838      if (result == null) {
839        Alphabet upper = alphabet.upperCase();
840        result = upperCase = (upper == alphabet) ? this : newInstance(upper, paddingChar);
841      }
842      return result;
843    }
844
845    @Override
846    public BaseEncoding lowerCase() {
847      BaseEncoding result = lowerCase;
848      if (result == null) {
849        Alphabet lower = alphabet.lowerCase();
850        result = lowerCase = (lower == alphabet) ? this : newInstance(lower, paddingChar);
851      }
852      return result;
853    }
854
855    BaseEncoding newInstance(Alphabet alphabet, @NullableDecl Character paddingChar) {
856      return new StandardBaseEncoding(alphabet, paddingChar);
857    }
858
859    @Override
860    public String toString() {
861      StringBuilder builder = new StringBuilder("BaseEncoding.");
862      builder.append(alphabet.toString());
863      if (8 % alphabet.bitsPerChar != 0) {
864        if (paddingChar == null) {
865          builder.append(".omitPadding()");
866        } else {
867          builder.append(".withPadChar('").append(paddingChar).append("')");
868        }
869      }
870      return builder.toString();
871    }
872
873    @Override
874    public boolean equals(@NullableDecl Object other) {
875      if (other instanceof StandardBaseEncoding) {
876        StandardBaseEncoding that = (StandardBaseEncoding) other;
877        return this.alphabet.equals(that.alphabet)
878            && Objects.equal(this.paddingChar, that.paddingChar);
879      }
880      return false;
881    }
882
883    @Override
884    public int hashCode() {
885      return alphabet.hashCode() ^ Objects.hashCode(paddingChar);
886    }
887  }
888
889  static final class Base16Encoding extends StandardBaseEncoding {
890    final char[] encoding = new char[512];
891
892    Base16Encoding(String name, String alphabetChars) {
893      this(new Alphabet(name, alphabetChars.toCharArray()));
894    }
895
896    private Base16Encoding(Alphabet alphabet) {
897      super(alphabet, null);
898      checkArgument(alphabet.chars.length == 16);
899      for (int i = 0; i < 256; ++i) {
900        encoding[i] = alphabet.encode(i >>> 4);
901        encoding[i | 0x100] = alphabet.encode(i & 0xF);
902      }
903    }
904
905    @Override
906    void encodeTo(Appendable target, byte[] bytes, int off, int len) throws IOException {
907      checkNotNull(target);
908      checkPositionIndexes(off, off + len, bytes.length);
909      for (int i = 0; i < len; ++i) {
910        int b = bytes[off + i] & 0xFF;
911        target.append(encoding[b]);
912        target.append(encoding[b | 0x100]);
913      }
914    }
915
916    @Override
917    int decodeTo(byte[] target, CharSequence chars) throws DecodingException {
918      checkNotNull(target);
919      if (chars.length() % 2 == 1) {
920        throw new DecodingException("Invalid input length " + chars.length());
921      }
922      int bytesWritten = 0;
923      for (int i = 0; i < chars.length(); i += 2) {
924        int decoded = alphabet.decode(chars.charAt(i)) << 4 | alphabet.decode(chars.charAt(i + 1));
925        target[bytesWritten++] = (byte) decoded;
926      }
927      return bytesWritten;
928    }
929
930    @Override
931    BaseEncoding newInstance(Alphabet alphabet, @NullableDecl Character paddingChar) {
932      return new Base16Encoding(alphabet);
933    }
934  }
935
936  static final class Base64Encoding extends StandardBaseEncoding {
937    Base64Encoding(String name, String alphabetChars, @NullableDecl Character paddingChar) {
938      this(new Alphabet(name, alphabetChars.toCharArray()), paddingChar);
939    }
940
941    private Base64Encoding(Alphabet alphabet, @NullableDecl Character paddingChar) {
942      super(alphabet, paddingChar);
943      checkArgument(alphabet.chars.length == 64);
944    }
945
946    @Override
947    void encodeTo(Appendable target, byte[] bytes, int off, int len) throws IOException {
948      checkNotNull(target);
949      checkPositionIndexes(off, off + len, bytes.length);
950      int i = off;
951      for (int remaining = len; remaining >= 3; remaining -= 3) {
952        int chunk = (bytes[i++] & 0xFF) << 16 | (bytes[i++] & 0xFF) << 8 | bytes[i++] & 0xFF;
953        target.append(alphabet.encode(chunk >>> 18));
954        target.append(alphabet.encode((chunk >>> 12) & 0x3F));
955        target.append(alphabet.encode((chunk >>> 6) & 0x3F));
956        target.append(alphabet.encode(chunk & 0x3F));
957      }
958      if (i < off + len) {
959        encodeChunkTo(target, bytes, i, off + len - i);
960      }
961    }
962
963    @Override
964    int decodeTo(byte[] target, CharSequence chars) throws DecodingException {
965      checkNotNull(target);
966      chars = trimTrailingPadding(chars);
967      if (!alphabet.isValidPaddingStartPosition(chars.length())) {
968        throw new DecodingException("Invalid input length " + chars.length());
969      }
970      int bytesWritten = 0;
971      for (int i = 0; i < chars.length(); ) {
972        int chunk = alphabet.decode(chars.charAt(i++)) << 18;
973        chunk |= alphabet.decode(chars.charAt(i++)) << 12;
974        target[bytesWritten++] = (byte) (chunk >>> 16);
975        if (i < chars.length()) {
976          chunk |= alphabet.decode(chars.charAt(i++)) << 6;
977          target[bytesWritten++] = (byte) ((chunk >>> 8) & 0xFF);
978          if (i < chars.length()) {
979            chunk |= alphabet.decode(chars.charAt(i++));
980            target[bytesWritten++] = (byte) (chunk & 0xFF);
981          }
982        }
983      }
984      return bytesWritten;
985    }
986
987    @Override
988    BaseEncoding newInstance(Alphabet alphabet, @NullableDecl Character paddingChar) {
989      return new Base64Encoding(alphabet, paddingChar);
990    }
991  }
992
993  @GwtIncompatible
994  static Reader ignoringReader(final Reader delegate, final String toIgnore) {
995    checkNotNull(delegate);
996    checkNotNull(toIgnore);
997    return new Reader() {
998      @Override
999      public int read() throws IOException {
1000        int readChar;
1001        do {
1002          readChar = delegate.read();
1003        } while (readChar != -1 && toIgnore.indexOf((char) readChar) >= 0);
1004        return readChar;
1005      }
1006
1007      @Override
1008      public int read(char[] cbuf, int off, int len) throws IOException {
1009        throw new UnsupportedOperationException();
1010      }
1011
1012      @Override
1013      public void close() throws IOException {
1014        delegate.close();
1015      }
1016    };
1017  }
1018
1019  static Appendable separatingAppendable(
1020      final Appendable delegate, final String separator, final int afterEveryChars) {
1021    checkNotNull(delegate);
1022    checkNotNull(separator);
1023    checkArgument(afterEveryChars > 0);
1024    return new Appendable() {
1025      int charsUntilSeparator = afterEveryChars;
1026
1027      @Override
1028      public Appendable append(char c) throws IOException {
1029        if (charsUntilSeparator == 0) {
1030          delegate.append(separator);
1031          charsUntilSeparator = afterEveryChars;
1032        }
1033        delegate.append(c);
1034        charsUntilSeparator--;
1035        return this;
1036      }
1037
1038      @Override
1039      public Appendable append(@NullableDecl CharSequence chars, int off, int len)
1040          throws IOException {
1041        throw new UnsupportedOperationException();
1042      }
1043
1044      @Override
1045      public Appendable append(@NullableDecl CharSequence chars) throws IOException {
1046        throw new UnsupportedOperationException();
1047      }
1048    };
1049  }
1050
1051  @GwtIncompatible // Writer
1052  static Writer separatingWriter(
1053      final Writer delegate, final String separator, final int afterEveryChars) {
1054    final Appendable separatingAppendable =
1055        separatingAppendable(delegate, separator, afterEveryChars);
1056    return new Writer() {
1057      @Override
1058      public void write(int c) throws IOException {
1059        separatingAppendable.append((char) c);
1060      }
1061
1062      @Override
1063      public void write(char[] chars, int off, int len) throws IOException {
1064        throw new UnsupportedOperationException();
1065      }
1066
1067      @Override
1068      public void flush() throws IOException {
1069        delegate.flush();
1070      }
1071
1072      @Override
1073      public void close() throws IOException {
1074        delegate.close();
1075      }
1076    };
1077  }
1078
1079  static final class SeparatedBaseEncoding extends BaseEncoding {
1080    private final BaseEncoding delegate;
1081    private final String separator;
1082    private final int afterEveryChars;
1083
1084    SeparatedBaseEncoding(BaseEncoding delegate, String separator, int afterEveryChars) {
1085      this.delegate = checkNotNull(delegate);
1086      this.separator = checkNotNull(separator);
1087      this.afterEveryChars = afterEveryChars;
1088      checkArgument(
1089          afterEveryChars > 0, "Cannot add a separator after every %s chars", afterEveryChars);
1090    }
1091
1092    @Override
1093    CharSequence trimTrailingPadding(CharSequence chars) {
1094      return delegate.trimTrailingPadding(chars);
1095    }
1096
1097    @Override
1098    int maxEncodedSize(int bytes) {
1099      int unseparatedSize = delegate.maxEncodedSize(bytes);
1100      return unseparatedSize
1101          + separator.length() * divide(Math.max(0, unseparatedSize - 1), afterEveryChars, FLOOR);
1102    }
1103
1104    @GwtIncompatible // Writer,OutputStream
1105    @Override
1106    public OutputStream encodingStream(final Writer output) {
1107      return delegate.encodingStream(separatingWriter(output, separator, afterEveryChars));
1108    }
1109
1110    @Override
1111    void encodeTo(Appendable target, byte[] bytes, int off, int len) throws IOException {
1112      delegate.encodeTo(separatingAppendable(target, separator, afterEveryChars), bytes, off, len);
1113    }
1114
1115    @Override
1116    int maxDecodedSize(int chars) {
1117      return delegate.maxDecodedSize(chars);
1118    }
1119
1120    @Override
1121    public boolean canDecode(CharSequence chars) {
1122      StringBuilder builder = new StringBuilder();
1123      for (int i = 0; i < chars.length(); i++) {
1124        char c = chars.charAt(i);
1125        if (separator.indexOf(c) < 0) {
1126          builder.append(c);
1127        }
1128      }
1129      return delegate.canDecode(builder);
1130    }
1131
1132    @Override
1133    int decodeTo(byte[] target, CharSequence chars) throws DecodingException {
1134      StringBuilder stripped = new StringBuilder(chars.length());
1135      for (int i = 0; i < chars.length(); i++) {
1136        char c = chars.charAt(i);
1137        if (separator.indexOf(c) < 0) {
1138          stripped.append(c);
1139        }
1140      }
1141      return delegate.decodeTo(target, stripped);
1142    }
1143
1144    @Override
1145    @GwtIncompatible // Reader,InputStream
1146    public InputStream decodingStream(final Reader reader) {
1147      return delegate.decodingStream(ignoringReader(reader, separator));
1148    }
1149
1150    @Override
1151    public BaseEncoding omitPadding() {
1152      return delegate.omitPadding().withSeparator(separator, afterEveryChars);
1153    }
1154
1155    @Override
1156    public BaseEncoding withPadChar(char padChar) {
1157      return delegate.withPadChar(padChar).withSeparator(separator, afterEveryChars);
1158    }
1159
1160    @Override
1161    public BaseEncoding withSeparator(String separator, int afterEveryChars) {
1162      throw new UnsupportedOperationException("Already have a separator");
1163    }
1164
1165    @Override
1166    public BaseEncoding upperCase() {
1167      return delegate.upperCase().withSeparator(separator, afterEveryChars);
1168    }
1169
1170    @Override
1171    public BaseEncoding lowerCase() {
1172      return delegate.lowerCase().withSeparator(separator, afterEveryChars);
1173    }
1174
1175    @Override
1176    public String toString() {
1177      return delegate + ".withSeparator(\"" + separator + "\", " + afterEveryChars + ")";
1178    }
1179  }
1180}