String系列源码解析02 - AbstractStringBuilder详细介绍

String系列源码解析02 - AbstractStringBuilder详细介绍

类属性：

AbstractStringBuilder有两个属性value和count，value是一个char数组，用于存储字符序列；count则表示所使用的字符数组的长度。

/**
* value是一个char数组，用于字符存储
*/
char value[];

/**
* count表示所使用的字符数量
*/
int count;

构造函数：

/**
* 无参构造器对于子类的序列化是必须的
*/
AbstractStringBuilder() {
}

/**
* 构造指定容量的AbstractStringBuilder
*/
AbstractStringBuilder(int capacity) {
value = new char[capacity];
}

核心类方法：

1. ensureCapacity

public void ensureCapacity(int minimumCapacity);

确保字符数组的容量至少等于指定的最小值。如果当前字符数组容量小于最小容量参数，那么新的具有更大容量的内部数组会被分配。默认增加后的字符数组容量是：

2*原字符数组容量 + 2

这也是许多JDK中的类（比如。。。）容量扩展的增长方式。

/**
* Ensures that the capacity is at least equal to the specified minimum.
* If the current capacity is less than the argument, then a new internal
* array is allocated with greater capacity. The new capacity is the
* larger of:
* <ul>
* <li>The <code>minimumCapacity</code> argument.
* <li>Twice the old capacity, plus <code>2</code>.
* </ul>
* If the <code>minimumCapacity</code> argument is nonpositive, this
* method takes no action and simply returns.
*
* @param   minimumCapacity   期望扩展的最小容量
*/
public void ensureCapacity(int minimumCapacity) {
// 只有当minimumCapacity参数大于零的时候才执行
if (minimumCapacity > 0)
ensureCapacityInternal(minimumCapacity);
}

2. ensureCapacityInternal

该方法和ensureCapacity有相同的契约，但是它永远不会被同步。
private void ensureCapacityInternal(int minimumCapacity);

/**
* This method has the same contract as ensureCapacity, but is
* never synchronized.
*/
private void ensureCapacityInternal(int minimumCapacity) {
// 防止内存溢出
if (minimumCapacity - value.length > 0)
expandCapacity(minimumCapacity);
}

3. expandCapacity

这个方法是ensureCapacity扩展语义的具体实现，但是没有大小和同步检查。
void expandCapacity(int minimumCapacity);

/**
* This implements the expansion semantics of ensureCapacity with no
* size check or synchronization.
*/
void expandCapacity(int minimumCapacity) {
int newCapacity = value.length * 2 + 2; // 默认生成新的字符数组的容量
if (newCapacity - minimumCapacity < 0)
/*
* 默认生成新的字符数组的容量 大于 期望扩展的最小容量，
* 那么默认生成新的字符数组的容量取期望扩展的最小容量
*/
newCapacity = minimumCapacity;
if (newCapacity < 0) {
if (minimumCapacity < 0) // 内存溢出
throw new OutOfMemoryError();
newCapacity = Integer.MAX_VALUE;
}
value = Arrays.copyOf(value, newCapacity); // 使用Arrays工具类生成新的字符数组
}

4. charAt

返回这个字符序列特定索引值下的字符值（代码单元），直接返回字符数组的元素，非常简单。
public char charAt(int index) {}

/**
* Returns the <code>char</code> value in this sequence at the specified index.
* The first <code>char</code> value is at index <code>0</code>, the next at index
* <code>1</code>, and so on, as in array indexing.
* <p>
* The index argument must be greater than or equal to
* <code>0</code>, and less than the length of this sequence.
*
* <p>If the <code>char</code> value specified by the index is a
* <a href="Character.html#unicode">surrogate</a>, the surrogate
* value is returned.
*
* @param      index   the index of the desired <code>char</code> value.
* @return     the <code>char</code> value at the specified index.
* @throws     IndexOutOfBoundsException  if <code>index</code> is
*             negative or greater than or equal to <code>length()</code>.
*/
public char charAt(int index) {
// 不合法的索引值
if ((index < 0) || (index >= count))
throw new StringIndexOutOfBoundsException(index);
return value[index];
}

5. codePointAt

返回这个字符序列指定索引下的unicode代码点（Unicode code point），内部使用的是char的引用类型Character的静态方法返回unicode代码点。

补充：代码点，我译为“码位值”。每个码位值实际上代表一个真正unicode字符。即unicode字符集上的码位值。为什么要这些码位相关的方法？源自1个java的char字符并不完全等于一个unicode的字符。char采用UCS-2编码是一种淘汰的UTF-16编码，最多65536种形态，也远少于当今unicode拥有11万字符的需求。java只好对后来新增的unicode字符用2个char拼出1个unicode字符。导致String中char的数量不等于unicode字符的数量。

public int codePointAt(int index) {}

/**
* Returns the character (Unicode code point) at the specified
* index. The index refers to <code>char</code> values
* (Unicode code units) and ranges from <code>0</code> to
* {@link #length()}<code> - 1</code>.
*
* <p> If the <code>char</code> value specified at the given index
* is in the high-surrogate range, the following index is less
* than the length of this sequence, and the
* <code>char</code> value at the following index is in the
* low-surrogate range, then the supplementary code point
* corresponding to this surrogate pair is returned. Otherwise,
* the <code>char</code> value at the given index is returned.
*
* @param      index the index to the <code>char</code> values
* @return     the code point value of the character at the
*             <code>index</code>
* @exception  IndexOutOfBoundsException  if the <code>index</code>
*             argument is negative or not less than the length of this
*             sequence.
*/
public int codePointAt(int index) {
// 非法索引值
if ((index < 0) || (index >= count)) {
throw new StringIndexOutOfBoundsException(index);
}
return Character.codePointAt(value, index);
}

6. codePointBefore

返回指定索引前一位的unicode代码点，具体实现同codePointAt类似。
public int codePointBefore(int index) {}

/**
* Returns the character (Unicode code point) before the specified
* index. The index refers to <code>char</code> values
* (Unicode code units) and ranges from <code>1</code> to {@link
* #length()}.
*
* <p> If the <code>char</code> value at <code>(index - 1)</code>
* is in the low-surrogate range, <code>(index - 2)</code> is not
* negative, and the <code>char</code> value at <code>(index -
* 2)</code> is in the high-surrogate range, then the
* supplementary code point value of the surrogate pair is
* returned. If the <code>char</code> value at <code>index -
* 1</code> is an unpaired low-surrogate or a high-surrogate, the
* surrogate value is returned.
*
* @param     index the index following the code point that should be returned
* @return    the Unicode code point value before the given index.
* @exception IndexOutOfBoundsException if the <code>index</code>
*            argument is less than 1 or greater than the length
*            of this sequence.
*/
public int codePointBefore(int index) {
int i = index - 1;
if ((i < 0) || (i >= count)) {
throw new StringIndexOutOfBoundsException(index);
}
return Character.codePointBefore(value, index);
}

7. codePointCount

准确计算指定索引值范围内unicode代码点的数量，注意，并不是char的数量，这与length()方法不同，length()方法计算的是代码单元的数量。

public int codePointCount(int beginIndex, int endIndex) {}

/**
* Returns the number of Unicode code points in the specified text
* range of this sequence. The text range begins at the specified
* <code>beginIndex</code> and extends to the <code>char</code> at
* index <code>endIndex - 1</code>. Thus the length (in
* <code>char</code>s) of the text range is
* <code>endIndex-beginIndex</code>. Unpaired surrogates within
* this sequence count as one code point each.
*
* @param beginIndex the index to the first <code>char</code> of
* the text range.
* @param endIndex the index after the last <code>char</code> of
* the text range.
* @return the number of Unicode code points in the specified text
* range
* @exception IndexOutOfBoundsException if the
* <code>beginIndex</code> is negative, or <code>endIndex</code>
* is larger than the length of this sequence, or
* <code>beginIndex</code> is larger than <code>endIndex</code>.
*/
public int codePointCount(int beginIndex, int endIndex) {
if (beginIndex < 0 || endIndex > count || beginIndex > endIndex) {
throw new IndexOutOfBoundsException();
}
return Character.codePointCountImpl(value, beginIndex, endIndex-beginIndex);
}

8. offsetByCodePoints

获取指定索引处的代码点偏移量，我个人的理解是根据代码单元的偏移量查找代码点的偏移量。
如果想获取i位置的代码点，则需要使用下面的方法：

String greeting = "Hello";
int index = greeting.offsetByCodePoints(0,i);
int cp = greeting.codePointAt(index);

public int offsetByCodePoints(int index, int codePointOffset) {}

/**
* Returns the index within this sequence that is offset from the
* given <code>index</code> by <code>codePointOffset</code> code
* points. Unpaired surrogates within the text range given by
* <code>index</code> and <code>codePointOffset</code> count as
* one code point each.
*
* @param index the index to be offset
* @param codePointOffset the offset in code points
* @return the index within this sequence
* @exception IndexOutOfBoundsException if <code>index</code>
*   is negative or larger then the length of this sequence,
*   or if <code>codePointOffset</code> is positive and the subsequence
*   starting with <code>index</code> has fewer than
*   <code>codePointOffset</code> code points,
*   or if <code>codePointOffset</code> is negative and the subsequence
*   before <code>index</code> has fewer than the absolute value of
*   <code>codePointOffset</code> code points.
*/
public int offsetByCodePoints(int index, int codePointOffset) {
if (index < 0 || index > count) {
throw new IndexOutOfBoundsException();
}
return Character.offsetByCodePointsImpl(value, 0, count,
index, codePointOffset);
}

9. append
附加对象（实际上是对象的字符串表示形式）
public AbstractStringBuilder append(Object obj) {}

/**
* Appends the string representation of the <code>Object</code>
* argument.
* <p>
* The argument is converted to a string as if by the method
* <code>String.valueOf</code>, and the characters of that
* string are then appended to this sequence.
*
* @param   obj   an <code>Object</code>.
* @return  a reference to this object.
*/
public AbstractStringBuilder append(Object obj) {
return append(String.valueOf(obj)); // 使用string的valueOf方法获取对象的字符串表示形式
}

10. append
附加String
public AbstractStringBuilder append(String str) {}

/**
* Appends the specified string to this character sequence.
* <p>
* The characters of the <code>String</code> argument are appended, in
* order, increasing the length of this sequence by the length of the
* argument. If <code>str</code> is <code>null</code>, then the four
* characters <code>"null"</code> are appended.
* <p>
* Let <i>n</i> be the length of this character sequence just prior to
* execution of the <code>append</code> method. Then the character at
* index <i>k</i> in the new character sequence is equal to the character
* at index <i>k</i> in the old character sequence, if <i>k</i> is less
* than <i>n</i>; otherwise, it is equal to the character at index
* <i>k-n</i> in the argument <code>str</code>.
*
* @param   str   a string.
* @return  a reference to this object.
*/
public AbstractStringBuilder append(String str) {
if (str == null) str = "null"; // 对象为null的处理方案
int len = str.length();
if (len == 0) return this; // 待附加的String长度为零时，不处理
int newCount = count + len;
if (newCount > value.length)
expandCapacity(newCount); // 如果附加后的容量大于此char数组的容量，则进行扩展
str.getChars(0, len, value, count); // 将String复制到此char数组，使用String的getChars方法
count = newCount; // 修改此char数组的count属性（所使用的字符数量）
return this;
}

未完待续。。。