src/com/google/common/base/Joiner.java - platform/external/guava - Git at Google

 /*
  * Copyright (C) 2008 Google Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package com.google.common.base;

 import com.google.common.annotations.GwtCompatible;
 import static com.google.common.base.Preconditions.checkNotNull;

 import java.io.IOException;
 import java.util.AbstractList;
 import java.util.Arrays;
 import java.util.Iterator;
 import java.util.Map;
 import java.util.Map.Entry;

 import javax.annotation.Nullable;

 /**
  * An object which joins pieces of text (specified as an array, {@link
  * Iterable}, varargs or even a {@link Map}) with a separator. It either
  * appends the results to an {@link Appendable} or returns them as a {@link
  * String}. Example: <pre>   {@code
  *
  *   Joiner joiner = Joiner.on("; ").skipNulls();
  *    . . .
  *   return joiner.join("Harry", null, "Ron", "Hermione");}</pre>
  *
  * This returns the string {@code "Harry; Ron; Hermione"}. Note that all input
  * elements are converted to strings using {@link Object#toString()} before
  * being appended.
  *
  * <p>If neither {@link #skipNulls()} nor {@link #useForNull(String)} is
  * specified, the joining methods will throw {@link NullPointerException} if any
  * given element is null.
  *
  * @author Kevin Bourrillion
  * @since 2010.01.04 <b>stable</b> (imported from Google Collections Library)
  */
 @GwtCompatible public class Joiner {
   /**
    * Returns a joiner which automatically places {@code separator} between
    * consecutive elements.
    */
   public static Joiner on(String separator) {
     return new Joiner(separator);
   }

   /**
    * Returns a joiner which automatically places {@code separator} between
    * consecutive elements.
    */
   public static Joiner on(char separator) {
     return new Joiner(String.valueOf(separator));
   }

   private final String separator;

   private Joiner(String separator) {
     this.separator = checkNotNull(separator);
   }

   private Joiner(Joiner prototype) {
     this.separator = prototype.separator;
   }

   /**
    * Appends the string representation of each of {@code parts}, using the
    * previously configured separator between each, to {@code appendable}.
    */
   public <A extends Appendable> A appendTo(A appendable, Iterable<?> parts)
       throws IOException {
     checkNotNull(appendable);
     Iterator<?> iterator = parts.iterator();
     if (iterator.hasNext()) {
       appendable.append(toString(iterator.next()));
       while (iterator.hasNext()) {
         appendable.append(separator);
         appendable.append(toString(iterator.next()));
       }
     }
     return appendable;
   }

   /**
    * Appends the string representation of each of {@code parts}, using the
    * previously configured separator between each, to {@code appendable}.
    */
   public final <A extends Appendable> A appendTo(
       A appendable, Object[] parts) throws IOException {
     return appendTo(appendable, Arrays.asList(parts));
   }

   /**
    * Appends to {@code appendable} the string representation of each of the
    * remaining arguments.
    */
   public final <A extends Appendable> A appendTo(A appendable,
       @Nullable Object first, @Nullable Object second, Object... rest)
       throws IOException {
     return appendTo(appendable, iterable(first, second, rest));
   }

   /**
    * Appends the string representation of each of {@code parts}, using the
    * previously configured separator between each, to {@code builder}. Identical
    * to {@link #appendTo(Appendable, Iterable)}, except that it does not throw
    * {@link IOException}.
    */
   public final StringBuilder appendTo(StringBuilder builder, Iterable<?> parts)
   {
     try {
       appendTo((Appendable) builder, parts);
     } catch (IOException impossible) {
       throw new AssertionError(impossible);
     }
     return builder;
   }

   /**
    * Appends the string representation of each of {@code parts}, using the
    * previously configured separator between each, to {@code builder}. Identical
    * to {@link #appendTo(Appendable, Iterable)}, except that it does not throw
    * {@link IOException}.
    */
   public final StringBuilder appendTo(StringBuilder builder, Object[] parts) {
     return appendTo(builder, Arrays.asList(parts));
   }

   /**
    * Appends to {@code builder} the string representation of each of the
    * remaining arguments. Identical to {@link #appendTo(Appendable, Object,
    * Object, Object[])}, except that it does not throw {@link IOException}.
    */
   public final StringBuilder appendTo(StringBuilder builder,
       @Nullable Object first, @Nullable Object second, Object... rest) {
     return appendTo(builder, iterable(first, second, rest));
   }

   /**
    * Returns a string containing the string representation of each of {@code
    * parts}, using the previously configured separator between each.
    */
   public final String join(Iterable<?> parts) {
     return appendTo(new StringBuilder(), parts).toString();
   }

   /**
    * Returns a string containing the string representation of each of {@code
    * parts}, using the previously configured separator between each.
    */
   public final String join(Object[] parts) {
     return join(Arrays.asList(parts));
   }

   /**
    * Returns a string containing the string representation of each argument,
    * using the previously configured separator between each.
    */
   public final String join(
       @Nullable Object first, @Nullable Object second, Object... rest) {
     return join(iterable(first, second, rest));
   }

   /**
    * Returns a joiner with the same behavior as this one, except automatically
    * substituting {@code nullText} for any provided null elements.
    */
   public Joiner useForNull(final String nullText) {
     checkNotNull(nullText);
     return new Joiner(this) {
       @Override CharSequence toString(Object part) {
         return (part == null) ? nullText : Joiner.this.toString(part);
       }
       @Override public Joiner useForNull(String nullText) {
         checkNotNull(nullText); // weird, just to satisfy NullPointerTester!
         // TODO: fix that?
         throw new UnsupportedOperationException("already specified useForNull");
       }
       @Override public Joiner skipNulls() {
         throw new UnsupportedOperationException("already specified useForNull");
       }
     };
   }

   /**
    * Returns a joiner with the same behavior as this joiner, except
    * automatically skipping over any provided null elements.
    */
   public Joiner skipNulls() {
     return new Joiner(this) {
       @Override public <A extends Appendable> A appendTo(
           A appendable, Iterable<?> parts) throws IOException {
         checkNotNull(appendable, "appendable");
         checkNotNull(parts, "parts");
         Iterator<?> iterator = parts.iterator();
         while (iterator.hasNext()) {
           Object part = iterator.next();
           if (part != null) {
             appendable.append(Joiner.this.toString(part));
             break;
           }
         }
         while (iterator.hasNext()) {
           Object part = iterator.next();
           if (part != null) {
             appendable.append(separator);
             appendable.append(Joiner.this.toString(part));
           }
         }
         return appendable;
       }
       @Override public Joiner useForNull(String nullText) {
         checkNotNull(nullText); // weird, just to satisfy NullPointerTester!
         throw new UnsupportedOperationException("already specified skipNulls");
       }
       @Override public MapJoiner withKeyValueSeparator(String kvs) {
         checkNotNull(kvs); // weird, just to satisfy NullPointerTester!
         throw new UnsupportedOperationException(
             "can't use .skipNulls() with maps");
       }
     };
   }

   /**
    * Returns a {@code MapJoiner} using the given key-value separator, and the
    * same configuration as this {@code Joiner} otherwise.
    */
   public MapJoiner withKeyValueSeparator(String keyValueSeparator) {
     return new MapJoiner(this, checkNotNull(keyValueSeparator));
   }

   /**
    * An object that joins map entries in the same manner as {@code Joiner} joins
    * iterables and arrays.
    */
   public static class MapJoiner {
     private Joiner joiner;
     private String keyValueSeparator;

     private MapJoiner(Joiner joiner, String keyValueSeparator) {
       this.joiner = joiner;
       this.keyValueSeparator = keyValueSeparator;
     }

     /**
      * Appends the string representation of each entry of {@code map}, using the
      * previously configured separator and key-value separator, to {@code
      * appendable}.
      */
     public <A extends Appendable> A appendTo(A appendable, Map<?, ?> map)
         throws IOException {
       checkNotNull(appendable);
       Iterator<? extends Map.Entry<?, ?>> iterator = map.entrySet().iterator();
       if (iterator.hasNext()) {
         Entry<?, ?> entry = iterator.next();
         appendable.append(joiner.toString(entry.getKey()));
         appendable.append(keyValueSeparator);
         appendable.append(joiner.toString(entry.getValue()));
         while (iterator.hasNext()) {
           appendable.append(joiner.separator);
           Entry<?, ?> e = iterator.next();
           appendable.append(joiner.toString(e.getKey()));
           appendable.append(keyValueSeparator);
           appendable.append(joiner.toString(e.getValue()));
         }
       }
       return appendable;
     }

     /**
      * Appends the string representation of each entry of {@code map}, using the
      * previously configured separator and key-value separator, to {@code
      * builder}. Identical to {@link #appendTo(Appendable, Map)}, except that it
      * does not throw {@link IOException}.
      */
     public StringBuilder appendTo(StringBuilder builder, Map<?, ?> map) {
       try {
         appendTo((Appendable) builder, map);
       } catch (IOException impossible) {
         throw new AssertionError(impossible);
       }
       return builder;
     }

     /**
      * Returns a string containing the string representation of each entry of
      * {@code map}, using the previously configured separator and key-value
      * separator.
      */
     public String join(Map<?, ?> map) {
       return appendTo(new StringBuilder(), map).toString();
     }

     /**
      * Returns a map joiner with the same behavior as this one, except
      * automatically substituting {@code nullText} for any provided null keys or
      * values.
      */
     public MapJoiner useForNull(String nullText) {
       return new MapJoiner(joiner.useForNull(nullText), keyValueSeparator);
     }
   }

   CharSequence toString(Object part) {
     return (part instanceof CharSequence)
         ? (CharSequence) part
         : part.toString();
   }

   private static Iterable<Object> iterable(
       final Object first, final Object second, final Object[] rest) {
     checkNotNull(rest);
     return new AbstractList<Object>() {
       @Override public int size() {
         return rest.length + 2;
       }
       @Override public Object get(int index) {
         switch (index) {
           case 0:
             return first;
           case 1:
             return second;
           default:
             return rest[index - 2];
         }
       }
     };
   }
 }
	/*
	* Copyright (C) 2008 Google Inc.
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package com.google.common.base;

	import com.google.common.annotations.GwtCompatible;
	import static com.google.common.base.Preconditions.checkNotNull;

	import java.io.IOException;
	import java.util.AbstractList;
	import java.util.Arrays;
	import java.util.Iterator;
	import java.util.Map;
	import java.util.Map.Entry;

	import javax.annotation.Nullable;

	/**
	* An object which joins pieces of text (specified as an array, {@link
	* Iterable}, varargs or even a {@link Map}) with a separator. It either
	* appends the results to an {@link Appendable} or returns them as a {@link
	* String}. Example: <pre> {@code
	*
	* Joiner joiner = Joiner.on("; ").skipNulls();
	* . . .
	* return joiner.join("Harry", null, "Ron", "Hermione");}</pre>
	*
	* This returns the string {@code "Harry; Ron; Hermione"}. Note that all input
	* elements are converted to strings using {@link Object#toString()} before
	* being appended.
	*
	* <p>If neither {@link #skipNulls()} nor {@link #useForNull(String)} is
	* specified, the joining methods will throw {@link NullPointerException} if any
	* given element is null.
	*
	* @author Kevin Bourrillion
	* @since 2010.01.04 <b>stable</b> (imported from Google Collections Library)
	*/
	@GwtCompatible public class Joiner {
	/**
	* Returns a joiner which automatically places {@code separator} between
	* consecutive elements.
	*/
	public static Joiner on(String separator) {
	return new Joiner(separator);
	}

	/**
	* Returns a joiner which automatically places {@code separator} between
	* consecutive elements.
	*/
	public static Joiner on(char separator) {
	return new Joiner(String.valueOf(separator));
	}

	private final String separator;

	private Joiner(String separator) {
	this.separator = checkNotNull(separator);
	}

	private Joiner(Joiner prototype) {
	this.separator = prototype.separator;
	}

	/**
	* Appends the string representation of each of {@code parts}, using the
	* previously configured separator between each, to {@code appendable}.
	*/
	public <A extends Appendable> A appendTo(A appendable, Iterable<?> parts)
	throws IOException {
	checkNotNull(appendable);
	Iterator<?> iterator = parts.iterator();
	if (iterator.hasNext()) {
	appendable.append(toString(iterator.next()));
	while (iterator.hasNext()) {
	appendable.append(separator);
	appendable.append(toString(iterator.next()));
	}
	}
	return appendable;
	}

	/**
	* Appends the string representation of each of {@code parts}, using the
	* previously configured separator between each, to {@code appendable}.
	*/
	public final <A extends Appendable> A appendTo(
	A appendable, Object[] parts) throws IOException {
	return appendTo(appendable, Arrays.asList(parts));
	}

	/**
	* Appends to {@code appendable} the string representation of each of the
	* remaining arguments.
	*/
	public final <A extends Appendable> A appendTo(A appendable,
	@Nullable Object first, @Nullable Object second, Object... rest)
	throws IOException {
	return appendTo(appendable, iterable(first, second, rest));
	}

	/**
	* Appends the string representation of each of {@code parts}, using the
	* previously configured separator between each, to {@code builder}. Identical
	* to {@link #appendTo(Appendable, Iterable)}, except that it does not throw
	* {@link IOException}.
	*/
	public final StringBuilder appendTo(StringBuilder builder, Iterable<?> parts)
	{
	try {
	appendTo((Appendable) builder, parts);
	} catch (IOException impossible) {
	throw new AssertionError(impossible);
	}
	return builder;
	}

	/**
	* Appends the string representation of each of {@code parts}, using the
	* previously configured separator between each, to {@code builder}. Identical
	* to {@link #appendTo(Appendable, Iterable)}, except that it does not throw
	* {@link IOException}.
	*/
	public final StringBuilder appendTo(StringBuilder builder, Object[] parts) {
	return appendTo(builder, Arrays.asList(parts));
	}

	/**
	* Appends to {@code builder} the string representation of each of the
	* remaining arguments. Identical to {@link #appendTo(Appendable, Object,
	* Object, Object[])}, except that it does not throw {@link IOException}.
	*/
	public final StringBuilder appendTo(StringBuilder builder,
	@Nullable Object first, @Nullable Object second, Object... rest) {
	return appendTo(builder, iterable(first, second, rest));
	}

	/**
	* Returns a string containing the string representation of each of {@code
	* parts}, using the previously configured separator between each.
	*/
	public final String join(Iterable<?> parts) {
	return appendTo(new StringBuilder(), parts).toString();
	}

	/**
	* Returns a string containing the string representation of each of {@code
	* parts}, using the previously configured separator between each.
	*/
	public final String join(Object[] parts) {
	return join(Arrays.asList(parts));
	}

	/**
	* Returns a string containing the string representation of each argument,
	* using the previously configured separator between each.
	*/
	public final String join(
	@Nullable Object first, @Nullable Object second, Object... rest) {
	return join(iterable(first, second, rest));
	}

	/**
	* Returns a joiner with the same behavior as this one, except automatically
	* substituting {@code nullText} for any provided null elements.
	*/
	public Joiner useForNull(final String nullText) {
	checkNotNull(nullText);
	return new Joiner(this) {
	@Override CharSequence toString(Object part) {
	return (part == null) ? nullText : Joiner.this.toString(part);
	}
	@Override public Joiner useForNull(String nullText) {
	checkNotNull(nullText); // weird, just to satisfy NullPointerTester!
	// TODO: fix that?
	throw new UnsupportedOperationException("already specified useForNull");
	}
	@Override public Joiner skipNulls() {
	throw new UnsupportedOperationException("already specified useForNull");
	}
	};
	}

	/**
	* Returns a joiner with the same behavior as this joiner, except
	* automatically skipping over any provided null elements.
	*/
	public Joiner skipNulls() {
	return new Joiner(this) {
	@Override public <A extends Appendable> A appendTo(
	A appendable, Iterable<?> parts) throws IOException {
	checkNotNull(appendable, "appendable");
	checkNotNull(parts, "parts");
	Iterator<?> iterator = parts.iterator();
	while (iterator.hasNext()) {
	Object part = iterator.next();
	if (part != null) {
	appendable.append(Joiner.this.toString(part));
	break;
	}
	}
	while (iterator.hasNext()) {
	Object part = iterator.next();
	if (part != null) {
	appendable.append(separator);
	appendable.append(Joiner.this.toString(part));
	}
	}
	return appendable;
	}
	@Override public Joiner useForNull(String nullText) {
	checkNotNull(nullText); // weird, just to satisfy NullPointerTester!
	throw new UnsupportedOperationException("already specified skipNulls");
	}
	@Override public MapJoiner withKeyValueSeparator(String kvs) {
	checkNotNull(kvs); // weird, just to satisfy NullPointerTester!
	throw new UnsupportedOperationException(
	"can't use .skipNulls() with maps");
	}
	};
	}

	/**
	* Returns a {@code MapJoiner} using the given key-value separator, and the
	* same configuration as this {@code Joiner} otherwise.
	*/
	public MapJoiner withKeyValueSeparator(String keyValueSeparator) {
	return new MapJoiner(this, checkNotNull(keyValueSeparator));
	}

	/**
	* An object that joins map entries in the same manner as {@code Joiner} joins
	* iterables and arrays.
	*/
	public static class MapJoiner {
	private Joiner joiner;
	private String keyValueSeparator;

	private MapJoiner(Joiner joiner, String keyValueSeparator) {
	this.joiner = joiner;
	this.keyValueSeparator = keyValueSeparator;
	}

	/**
	* Appends the string representation of each entry of {@code map}, using the
	* previously configured separator and key-value separator, to {@code
	* appendable}.
	*/
	public <A extends Appendable> A appendTo(A appendable, Map<?, ?> map)
	throws IOException {
	checkNotNull(appendable);
	Iterator<? extends Map.Entry<?, ?>> iterator = map.entrySet().iterator();
	if (iterator.hasNext()) {
	Entry<?, ?> entry = iterator.next();
	appendable.append(joiner.toString(entry.getKey()));
	appendable.append(keyValueSeparator);
	appendable.append(joiner.toString(entry.getValue()));
	while (iterator.hasNext()) {
	appendable.append(joiner.separator);
	Entry<?, ?> e = iterator.next();
	appendable.append(joiner.toString(e.getKey()));
	appendable.append(keyValueSeparator);
	appendable.append(joiner.toString(e.getValue()));
	}
	}
	return appendable;
	}

	/**
	* Appends the string representation of each entry of {@code map}, using the
	* previously configured separator and key-value separator, to {@code
	* builder}. Identical to {@link #appendTo(Appendable, Map)}, except that it
	* does not throw {@link IOException}.
	*/
	public StringBuilder appendTo(StringBuilder builder, Map<?, ?> map) {
	try {
	appendTo((Appendable) builder, map);
	} catch (IOException impossible) {
	throw new AssertionError(impossible);
	}
	return builder;
	}

	/**
	* Returns a string containing the string representation of each entry of
	* {@code map}, using the previously configured separator and key-value
	* separator.
	*/
	public String join(Map<?, ?> map) {
	return appendTo(new StringBuilder(), map).toString();
	}

	/**
	* Returns a map joiner with the same behavior as this one, except
	* automatically substituting {@code nullText} for any provided null keys or
	* values.
	*/
	public MapJoiner useForNull(String nullText) {
	return new MapJoiner(joiner.useForNull(nullText), keyValueSeparator);
	}
	}

	CharSequence toString(Object part) {
	return (part instanceof CharSequence)
	? (CharSequence) part
	: part.toString();
	}

	private static Iterable<Object> iterable(
	final Object first, final Object second, final Object[] rest) {
	checkNotNull(rest);
	return new AbstractList<Object>() {
	@Override public int size() {
	return rest.length + 2;
	}
	@Override public Object get(int index) {
	switch (index) {
	case 0:
	return first;
	case 1:
	return second;
	default:
	return rest[index - 2];
	}
	}
	};
	}
	}