Класс StringBuffer

Потокобезопасная, изменяемая последовательность символов. Буфер строк похож на String, но может быть изменён. В любой момент времени он содержит определённую последовательность символов, но длина и содержимое последовательности могут быть изменены посредством определённых вызовов методов.

Буферы строк безопасны для использования в нескольких потоках. Методы синхронизированы при необходимости, чтобы все операции над конкретным экземпляром вели себя так, как будто они происходят в определённом последовательном порядке, согласованном с порядком вызовов методов каждым из вовлечённых потоков.

Основные операции над буфером строк — это методы append и insert, которые перегружены для принятия данных любого типа. Они эффективно преобразуют заданный элемент данных в строку, а затем добавляют или вставляют символы этой строки в буфер строк. Метод append всегда добавляет эти символы в конец буфера; метод insert добавляет символы в указанную точку.

Например, если z ссылается на объект буфера строк, текущее содержимое которого "start", то вызов метода z.append("le") заставит буфер строк содержать "startle", в то время как z.insert(4, "le") изменит буфер строк на "starlet".

В общем случае, если sb ссылается на экземпляр буфера строк, то sb.append(x) имеет тот же эффект, что и sb.insert(sb.length(), x).

Всякий раз, когда происходит операция, включающая исходную последовательность (например, добавление или вставка из исходной последовательности), этот класс синхронизируется только с буфером строк, выполняющим операцию, а не с исходной последовательностью. Обратите внимание, что, хотя StringBuffer предназначен для безопасного одновременного использования из нескольких потоков, если конструктору или операциям append или insert передаётся исходная последовательность, которая совместно используется несколькими потоками, код вызывающего потока должен гарантировать, что операция имеет согласованный и неизменный вид исходной последовательности на протяжении всей операции. Это можно выполнить, например, при помощи блокировки вызывающего потока во время вызова операции, использования неизменяемой исходной последовательности или избежания совместного использования исходной последовательности между потоками.

Каждый буфер строк имеет ёмкость. Пока длина последовательности символов, содержащихся в буфере строк, не превышает ёмкость, нет необходимости выделять новый внутренний массив буфера. Если внутренний буфер переполняется, он автоматически увеличивается.

Если не указано иное, передача null аргумента в конструктор или метод в этом классе приведёт к выбрасыванию исключения NullPointerException.

Начиная с версии JDK 5, этот класс дополнен эквивалентным классом, предназначенным для использования одним потоком, StringBuilder. Класс StringBuilder обычно следует использовать вместо этого, так как он поддерживает все те же операции, но быстрее, так как не выполняет синхронизацию.

Краткое описание конструкторов

StringBuffer

public StringBuffer()

Конструирует буфер строк без символов в нем и начальной емкостью 16 символов.

StringBuffer

public StringBuffer(int capacity)

Конструирует буфер строк без символов в нем и указанной начальной емкостью.

Параметры:

capacity - начальная емкость.

Исключения:

NegativeArraySizeException - если аргумент capacity меньше 0.

StringBuffer

public StringBuffer(String str)

Конструирует буфер строк, инициализированный содержимым указанной строки. Начальная емкость буфера строк равна 16 плюс длина аргумента строки.

Параметры:

str - начальное содержимое буфера.

StringBuffer

public StringBuffer(CharSequence seq)

Параметры:

seq - последовательность для копирования.

С версии:

1.5

Краткое описание методов

length

public int length()

Возвращает длину (количество символов).

Указано в:

length в интерфейсе CharSequence

Возвращает:

длину последовательности символов, в настоящее время представляемых этим объектом

capacity

public int capacity()

Возвращает текущую емкость. Емкость — это объем памяти, доступный для вновь вставленных символов, после превышения которого произойдет выделение памяти.

Возвращает:

текущая емкость

ensureCapacity

public void ensureCapacity(int minimumCapacity)

Обеспечивает, чтобы емкость была как минимум равна указанному минимуму. Если текущая емкость меньше аргумента, то выделяется новый внутренний массив с большей емкостью. Новая емкость — это большее из:

• Аргумента minimumCapacity.
• Двойной старой емкости плюс 2.

Если аргумент minimumCapacity неположителен, этот метод не выполняет никаких действий и просто возвращается. Обратите внимание, что последующие операции с этим объектом могут уменьшить фактическую емкость ниже запрошенной здесь.

Параметры:

minimumCapacity - минимально желаемая емкость.

trimToSize

public void trimToSize()

Пытается уменьшить объем памяти, используемый для последовательности символов. Если буфер больше, чем необходимо для хранения его текущей последовательности символов, то он может быть изменен в размере, чтобы стать более эффективным с точки зрения использования памяти. Вызов этого метода может, но не обязательно, повлиять на значение, возвращаемое последующим вызовом метода capacity().

С версии:

1.5

setLength

public void setLength(int newLength)

Параметры:

newLength - новая длина

Исключения:

IndexOutOfBoundsException - если аргумент newLength отрицателен.

См. также:

length()

charAt

public char charAt(int index)

Указано в:

charAt в интерфейсе CharSequence

Параметры:

index - индекс нужного значения char.

Возвращает:

значение char по указанному индексу.

Исключения:

IndexOutOfBoundsException - если index отрицательно или больше или равно length().

См. также:

length()

codePointAt

public int codePointAt(int index)

Параметры:

index - индекс к значениям char

Возвращает:

значение кодовой точки символа по index

С версии:

1.5

codePointBefore

public int codePointBefore(int index)

Параметры:

index - индекс, следующий за кодовой точкой, которая должна быть возвращена

Возвращает:

значение кодовой точки Unicode перед заданным индексом.

С версии:

1.5

codePointCount

public int codePointCount(int beginIndex,
                          int endIndex)

Возвращает количество кодовых точек Unicode в указанном диапазоне текста этой последовательности. Диапазон текста начинается с указанного beginIndex и простирается до char по индексу endIndex - 1. Таким образом, длина (в chars) диапазона текста равна endIndex-beginIndex. Непарные суррогаты в этой последовательности считаются по одному кодовому символу каждый.

Параметры:

beginIndex - индекс к первому char диапазона текста.

endIndex - индекс после последнего char диапазона текста.

Возвращает:

количество кодовых точек Unicode в указанном диапазоне текста

С версии:

1.5

offsetByCodePoints

public int offsetByCodePoints(int index,
                              int codePointOffset)

Возвращает индекс в этой последовательности, который смещен от данного index на codePointOffset кодовых точек. Непарные суррогаты в диапазоне текста, заданном index и codePointOffset, считаются по одному кодовому символу каждый.

Параметры:

index - индекс, который нужно сместить

codePointOffset - смещение в кодовых точках

Возвращает:

индекс в этой последовательности

С версии:

1.5

getChars

public void getChars(int srcBegin,
                     int srcEnd,
                     char[] dst,
                     int dstBegin)

Символы копируются из этой последовательности в целевой массив символов dst. Первый символ для копирования находится по индексу srcBegin; последний символ для копирования находится по индексу srcEnd-1. Общее количество символов для копирования равно srcEnd-srcBegin. Символы копируются в подмассив dst, начиная с индекса dstBegin и заканчивая индексом:

dstbegin + (srcEnd-srcBegin) - 1

Параметры:

srcBegin - начать копирование с этого смещения.

srcEnd - прекратить копирование с этого смещения.

dst - массив, в который нужно скопировать данные.

dstBegin - смещение в dst.

Исключения:

IndexOutOfBoundsException - если выполняется любое из следующих условий:

• srcBegin отрицательно
• dstBegin отрицательно
• аргумент srcBegin больше аргумента srcEnd.
• srcEnd больше this.length().
• dstBegin+srcEnd-srcBegin больше dst.length

setCharAt

public void setCharAt(int index,
                      char ch)

Параметры:

index - индекс символа для изменения.

ch - новый символ.

Исключения:

IndexOutOfBoundsException - если index отрицательно или больше или равно length().

См. также:

length()

append

public StringBuffer append(Object obj)

Параметры:

obj - объект Object.

Возвращает:

ссылку на этот объект.

append

public StringBuffer append(String str)

Параметры:

str - строка.

Возвращает:

ссылку на этот объект.

append

public StringBuffer append(StringBuffer sb)

Параметры:

sb - буфер символов для добавления.

Возвращает:

ссылку на этот объект.

С тех пор:

1.4

append

public StringBuffer append(CharSequence s)

Определено в:

append в интерфейсе Appendable

Параметры:

s - последовательность символов для добавления.

Возвращает:

ссылку на этот объект.

С тех пор:

1.5

append

public StringBuffer append(CharSequence s,
                           int start,
                           int end)

Определено в:

append в интерфейсе Appendable

Параметры:

s - последовательность символов для добавления.

start - начальный индекс подпоследовательности для добавления.

end - конечный индекс подпоследовательности для добавления.

Возвращает:

ссылку на этот объект.

Выбрасывает:

IndexOutOfBoundsException - если start отрицательно, или start больше, чем end, или end больше, чем s.length()

С тех пор:

1.5

append

public StringBuffer append(char[] str)

Параметры:

str - символы для добавления.

Возвращает:

ссылку на этот объект.

append

public StringBuffer append(char[] str,
                           int offset,
                           int len)

Параметры:

str - символы для добавления.

offset - индекс первого символа для добавления.

len - количество символов для добавления.

Возвращает:

ссылку на этот объект.

Выбрасывает:

IndexOutOfBoundsException - если offset < 0 или len < 0 или offset+len > str.length

append

public StringBuffer append(boolean b)

Параметры:

b - значение boolean.

Возвращает:

ссылку на этот объект.

append

public StringBuffer append(char c)

Определено в:

append в интерфейсе Appendable

Параметры:

c - символ.

Возвращает:

ссылку на этот объект.

append

public StringBuffer append(int i)

Параметры:

i - целое число.

Возвращает:

ссылку на этот объект.

appendCodePoint

public StringBuffer appendCodePoint(int codePoint)

Параметры:

codePoint - код Юникода

Возвращает:

ссылку на этот объект.

С тех пор:

1.5

append

public StringBuffer append(long lng)

Параметры:

lng - целое число с плавающей точкой.

Возвращает:

ссылку на этот объект.

append

public StringBuffer append(float f)

Параметры:

f - a float.

Возвращает:

ссылку на этот объект.

append

public StringBuffer append(double d)

Параметры:

d - a double.

Возвращает:

ссылку на этот объект.

delete

public StringBuffer delete(int start,
                           int end)

Удаляет символы в подстроке этой последовательности. Подстрока начинается со значения, указанного в start, и заканчивается символом с индексом end - 1 или концом последовательности, если такого символа не существует. Если start равно end, никаких изменений не происходит.

Параметры:

start - Начальный индекс (включительно).

end - Конечный индекс (исключительно).

Возвращает:

Этот объект.

Исключения:

StringIndexOutOfBoundsException - если start отрицательно, больше чем length(), или больше чем end.

С:

1.2

deleteCharAt

public StringBuffer deleteCharAt(int index)

Параметры:

index - Индекс символа для удаления

Возвращает:

Этот объект.

Исключения:

StringIndexOutOfBoundsException - если индекс отрицателен или больше или равен length().

С:

1.2

replace

public StringBuffer replace(int start,
                            int end,
                            String str)

Заменяет символы в подстроке этой последовательности символами в указанной строке. Подстрока начинается со значения, указанного в start, и заканчивается символом с индексом end - 1 или концом последовательности, если такого символа не существует. Сначала символы в подстроке удаляются, а затем указанная строка вставляется в позицию start. (При необходимости, эта последовательность будет увеличена, чтобы вместить указанную строку.)

Параметры:

start - Начальный индекс (включительно).

end - Конечный индекс (исключительно).

str - Строка, которая заменит предыдущее содержимое.

Возвращает:

Этот объект.

Исключения:

StringIndexOutOfBoundsException - если start отрицательно, больше чем length(), или больше чем end.

С:

1.2

substring

public String substring(int start)

Возвращает новую строку, содержащую подпоследовательность символов, в настоящее время содержащуюся в этой последовательности символов. Подстрока начинается с указанного индекса и простирается до конца этой последовательности.

Параметры:

start - Начальный индекс (включительно).

Возвращает:

Новая строка.

Исключения:

StringIndexOutOfBoundsException - если start меньше нуля или больше длины этого объекта.

С:

1.2

subSequence

public CharSequence subSequence(int start,
                                int end)

sb.subSequence(begin, end)

sb.substring(begin, end)

Задано:

subSequence в интерфейсе CharSequence

Параметры:

start - начальный индекс (включительно).

end - конечный индекс (исключительно).

Возвращает:

указанная подпоследовательность.

Исключения:

IndexOutOfBoundsException - если start или end отрицательны, если end больше length(), или если start больше end

С:

1.4

substring

public String substring(int start,
                        int end)

Возвращает новую строку, содержащую подпоследовательность символов, в настоящее время содержащихся в этой последовательности. Подстрока начинается с указанного start и заканчивается символом с индексом end - 1.

Параметры:

start - Начальный индекс (включительно).

end - Конечный индекс (исключительно).

Возвращает:

Новая строка.

Исключения:

StringIndexOutOfBoundsException - если start или end отрицательны или больше length(), или start больше end.

С:

1.2

insert

public StringBuffer insert(int index,
                           char[] str,
                           int offset,
                           int len)

Вставляет строковое представление подмассива аргумента массива str в эту последовательность. Подмассив начинается с указанного offset и простирается до len char символов. Символы подмассива вставляются в эту последовательность в позиции, указанной в index. Длина этой последовательности увеличивается на len char символов.

Параметры:

index - позиция для вставки подмассива.

str - массив char.

offset - индекс первого символа в подмассиве для вставки.

len - количество символов в подмассиве для вставки.

Возвращает:

Этот объект

Исключения:

StringIndexOutOfBoundsException - если index отрицательно или больше length(), или offset или len отрицательны, или (offset+len) больше str.length.

С:

1.2

insert

public StringBuffer insert(int offset,
                           Object obj)

Параметры:

offset - смещение.

obj - an Object.

Возвращает:

ссылку на этот объект.

Исключения:

StringIndexOutOfBoundsException - если смещение некорректно.

insert

public StringBuffer insert(int offset,
                           String str)

Параметры:

offset - смещение.

str - строка.

Возвращает:

ссылку на этот объект.

Исключения:

StringIndexOutOfBoundsException - если смещение некорректно.

insert

public StringBuffer insert(int offset,
                           char[] str)

Параметры:

offset - смещение.

str - массив символов.

Возвращает:

ссылку на этот объект.

Исключения:

StringIndexOutOfBoundsException - если смещение некорректно.

insert

public StringBuffer insert(int dstOffset,
                           CharSequence s)

Параметры:

dstOffset - смещение.

s - последовательность, подлежащая вставке.

Возвращает:

ссылку на этот объект.

Исключения:

IndexOutOfBoundsException - если смещение недействительно.

С тех пор:

1.5

insert

public StringBuffer insert(int dstOffset,
                           CharSequence s,
                           int start,
                           int end)

Параметры:

dstOffset - смещение в этой последовательности.

s - последовательность, подлежащая вставке.

start - начальный индекс подпоследовательности, подлежащей вставке.

end - конечный индекс подпоследовательности, подлежащей вставке.

Возвращает:

ссылку на этот объект.

Исключения:

IndexOutOfBoundsException - если dstOffset отрицательно или больше this.length(), или start или end отрицательны, или start больше end или end больше s.length()

С тех пор:

1.5

insert

public StringBuffer insert(int offset,
                           boolean b)

Параметры:

offset - смещение.

b - логическое значение.

Возвращает:

ссылку на этот объект.

Исключения:

StringIndexOutOfBoundsException - если смещение недействительно.

insert

public StringBuffer insert(int offset,
                           char c)

Параметры:

offset - смещение.

c - символ.

Возвращает:

ссылку на этот объект.

Исключения:

IndexOutOfBoundsException - если смещение недействительно.

insert

public StringBuffer insert(int offset,
                           int i)

Параметры:

offset - смещение.

i - целое число.

Возвращает:

ссылку на этот объект.

Исключения:

StringIndexOutOfBoundsException - если смещение недействительно.

insert

public StringBuffer insert(int offset,
                           long l)

Параметры:

offset - смещение.

l - целое число с длинной.

Возвращает:

ссылку на этот объект.

Исключения:

StringIndexOutOfBoundsException - если смещение недействительно.

insert

public StringBuffer insert(int offset,
                           float f)

Параметры:

offset - смещение.

f - число с плавающей точкой.

Возвращает:

ссылку на этот объект.

Исключения:

StringIndexOutOfBoundsException - если смещение недействительно.

insert

public StringBuffer insert(int offset,
                           double d)

Параметры:

offset - смещение.

d - число с плавающей точкой двойной точности.

Возвращает:

ссылку на этот объект.

Исключения:

StringIndexOutOfBoundsException - если смещение недействительно.

indexOf

public int indexOf(String str)

Возвращает индекс в этой строке первого вхождения указанной подстроки. Возвращаемое целое число — это наименьшее значение k, для которого:

this.toString().startsWith(str, <i>k</i>)

Параметры:

str - любая строка.

Возвращает:

если строковый аргумент встречается в качестве подстроки в этом объекте, то возвращается индекс первого символа первой такой подстроки; если он не встречается в качестве подстроки, возвращается -1.

С тех пор:

1.4

indexOf

public int indexOf(String str,
                   int fromIndex)

Возвращает индекс в этой строке первого вхождения указанной подстроки, начиная с указанного индекса. Возвращаемое целое число — это наименьшее значение k для которого:

k >= Math.min(fromIndex, this.length()) &&
                   this.toString().startsWith(str, k)

Параметры:

str - подстрока, для которой необходимо выполнить поиск.

fromIndex - индекс, с которого необходимо начать поиск.

Возвращает:

индекс в этой строке первого вхождения указанной подстроки, начиная с указанного индекса.

С тех пор:

1.4

lastIndexOf

public int lastIndexOf(String str)

Возвращает индекс в этой строке правого вхождения указанной подстроки. Правейшая пустая строка "" считается имеющей индекс this.length(). Возвращаемый индекс — это наибольшее значение k, для которого

this.toString().startsWith(str, k)

Параметры:

str - подстрока для поиска.

Возвращает:

если строковый аргумент встречается один или несколько раз в качестве подстроки в этом объекте, то возвращается индекс первого символа последней такой подстроки. Если он не встречается в качестве подстроки, возвращается -1.

С тех пор:

1.4

public int lastIndexOf(String str,
                       int fromIndex)

Возвращает индекс последнего вхождения указанной подстроки в этой строке. Возвращаемое целое число — это наибольшее значение k, такое что:

k <= Math.min(fromIndex, this.length()) &&
                   this.toString().startsWith(str, k)

Параметры:

str - подстрока, которую нужно найти.

fromIndex - индекс, с которого нужно начать поиск.

Возвращает:

индекс последнего вхождения указанной подстроки в этой последовательности.

С:

1.4

reverse

public StringBuffer reverse()

Возвращает:

ссылка на этот объект.

С:

JDK1.0.2

toString

public String toString()

Возвращает строку, представляющую данные в этой последовательности. Создаётся и инициализируется новый String объект, содержащий последовательность символов, в настоящее время представленную этим объектом. Затем возвращается этот String объект. Последующие изменения в этой последовательности не влияют на содержимое String.

Определено в:

toString в интерфейсе CharSequence

Возвращает:

строковое представление этой последовательности символов.