Coverage Summary for Class: CharEscaperBuilder (com.google.common.escape)

1 /*
2  * Copyright (C) 2006 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.escape;
16 
17 import static com.google.common.base.Preconditions.checkNotNull;
18 
19 import com.google.common.annotations.Beta;
20 import com.google.common.annotations.GwtCompatible;
21 import com.google.errorprone.annotations.CanIgnoreReturnValue;
22 import java.util.HashMap;
23 import java.util.Map;
24 import java.util.Map.Entry;
25 import javax.annotation.CheckForNull;
26 import org.checkerframework.checker.nullness.qual.Nullable;
27 
28 /**
29  * Simple helper class to build a "sparse" array of objects based on the indexes that were added to
30  * it. The array will be from 0 to the maximum index given. All non-set indexes will contain null
31  * (so it's not really a sparse array, just a pseudo sparse array). The builder can also return a
32  * CharEscaper based on the generated array.
33  *
34  * @author Sven Mawson
35  * @since 15.0
36  */
37 @Beta
38 @GwtCompatible
39 @ElementTypesAreNonnullByDefault
40 public final class CharEscaperBuilder {
41   /**
42    * Simple decorator that turns an array of replacement char[]s into a CharEscaper, this results in
43    * a very fast escape method.
44    */
45   private static class CharArrayDecorator extends CharEscaper {
46     private final char[] @Nullable [] replacements;
47     private final int replaceLength;
48 
49     CharArrayDecorator(char[] @Nullable [] replacements) {
50       this.replacements = replacements;
51       this.replaceLength = replacements.length;
52     }
53 
54     /*
55      * Overriding escape method to be slightly faster for this decorator. We test the replacements
56      * array directly, saving a method call.
57      */
58     @Override
59     public String escape(String s) {
60       int slen = s.length();
61       for (int index = 0; index < slen; index++) {
62         char c = s.charAt(index);
63         if (c < replacements.length && replacements[c] != null) {
64           return escapeSlow(s, index);
65         }
66       }
67       return s;
68     }
69 
70     @Override
71     @CheckForNull
72     protected char[] escape(char c) {
73       return c < replaceLength ? replacements[c] : null;
74     }
75   }
76 
77   // Replacement mappings.
78   private final Map<Character, String> map;
79 
80   // The highest index we've seen so far.
81   private int max = -1;
82 
83   /** Construct a new sparse array builder. */
84   public CharEscaperBuilder() {
85     this.map = new HashMap<>();
86   }
87 
88   /** Add a new mapping from an index to an object to the escaping. */
89   @CanIgnoreReturnValue
90   public CharEscaperBuilder addEscape(char c, String r) {
91     map.put(c, checkNotNull(r));
92     if (c > max) {
93       max = c;
94     }
95     return this;
96   }
97 
98   /** Add multiple mappings at once for a particular index. */
99   @CanIgnoreReturnValue
100   public CharEscaperBuilder addEscapes(char[] cs, String r) {
101     checkNotNull(r);
102     for (char c : cs) {
103       addEscape(c, r);
104     }
105     return this;
106   }
107 
108   /**
109    * Convert this builder into an array of char[]s where the maximum index is the value of the
110    * highest character that has been seen. The array will be sparse in the sense that any unseen
111    * index will default to null.
112    *
113    * @return a "sparse" array that holds the replacement mappings.
114    */
115   public char[] @Nullable [] toArray() {
116     char[][] result = new char[max + 1][];
117     for (Entry<Character, String> entry : map.entrySet()) {
118       result[entry.getKey()] = entry.getValue().toCharArray();
119     }
120     return result;
121   }
122 
123   /**
124    * Convert this builder into a char escaper which is just a decorator around the underlying array
125    * of replacement char[]s.
126    *
127    * @return an escaper that escapes based on the underlying array.
128    */
129   public Escaper toEscaper() {
130     return new CharArrayDecorator(toArray());
131   }
132 }