home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1995 November / PCWK1195.iso / inne / win95 / sieciowe / hotja32.lzh / hotjava / classsrc / java / lang / stringbuffer.java < prev    next >
Text File  |  1995-08-11  |  14KB  |  446 lines
  1. /*
  2.  * @(#)StringBuffer.java    1.15 95/01/31  
  3.  *
  4.  * Copyright (c) 1994 Sun Microsystems, Inc. All Rights Reserved.
  5.  *
  6.  * Permission to use, copy, modify, and distribute this software
  7.  * and its documentation for NON-COMMERCIAL purposes and without
  8.  * fee is hereby granted provided that this copyright notice
  9.  * appears in all copies. Please refer to the file "copyright.html"
  10.  * for further important copyright and licensing information.
  11.  *
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
  13.  * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  14.  * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  15.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
  16.  * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  17.  * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  18.  */
  19.  
  20. package java.lang;
  21.  
  22. /**
  23.  * This class is a growable buffer for characters. It is mainly used
  24.  * to create Strings. The compiler uses it to implement the "+" operator.
  25.  * For example:
  26.  * <pre>
  27.  *    "a" + 4 + "c"
  28.  * </pre>
  29.  * is compiled to:
  30.  * <pre>
  31.  *    new StringBuffer().append("a").append(4).append("c").toString()
  32.  * </pre>
  33.  * 
  34.  * Note that toString() does not create a copy of the internal buffer. Instead
  35.  * the buffer is marked as shared. Any further changes to the buffer will
  36.  * cause a copy to be made. <p>
  37.  *
  38.  * @see        String
  39.  * @see        java.io.OutputStreamBuffer
  40.  * @version     1.15, 31 Jan 1995
  41.  * @author    Arthur van Hoff
  42.  */
  43.  
  44. public class StringBuffer {
  45.     /** The value is used for character storage. */
  46.     private char value[];
  47.  
  48.     /** The count is the number of characters in the buffer. */
  49.     private int count;
  50.  
  51.     /** A flag indicating whether the buffer is shared */
  52.     private boolean shared;
  53.  
  54.     /**
  55.      * Constructs an empty string buffer.
  56.      */
  57.     public StringBuffer() {
  58.     this(16);
  59.     }
  60.  
  61.     /**
  62.      * Constructs a string buffer with the specified initial length.
  63.      * @param length    the initial length
  64.      */
  65.     public StringBuffer(int length) {
  66.     value = new char[length];
  67.     shared = false;
  68.     }
  69.  
  70.     /**
  71.      * Constructs a string buffer with the specified initial value.
  72.      * @param str    the initial value of the buffer
  73.      */
  74.     public StringBuffer(String str) {
  75.     this(str.length() + 16);
  76.     append(str);
  77.     }
  78.  
  79.     /**
  80.      * Returns the length (character count) of the buffer.
  81.      * @return    the number of characters in the buffer
  82.      */
  83.     public int length() {
  84.     return count;
  85.     }
  86.  
  87.     /**
  88.      * Returns the current capacity of the string buffer. The capacity
  89.      * is the amount of storage available for newly inserted
  90.      * characters; beyond which an allocation will occur.
  91.      * @return the capacity of the buffer
  92.      */
  93.     public int capacity() {
  94.     return value.length;
  95.     }
  96.  
  97.     /**
  98.      * Copies the buffer value if it is shared.
  99.      */
  100.     public void copyWhenShared() {
  101.     if (shared) {
  102.         char newValue[] = new char[value.length];
  103.         System.arraycopy(value, 0, newValue, 0, count);
  104.         value = newValue;
  105.         shared = false;
  106.     }
  107.     }
  108.  
  109.     /**
  110.      * Ensures that the capacity of the buffer is at least equal to the
  111.      * specified minimum.
  112.      * @param minimumCapacity    the minimum desired capacity
  113.      */
  114.     public synchronized void ensureCapacity(int minimumCapacity) {
  115.     int maxCapacity = value.length;
  116.  
  117.     if (minimumCapacity > maxCapacity) {
  118.         int newCapacity = (maxCapacity + 1) * 2;
  119.         if (minimumCapacity > newCapacity) {
  120.         newCapacity = minimumCapacity;
  121.         }
  122.  
  123.         char newValue[] = new char[newCapacity];
  124.         System.arraycopy(value, 0, newValue, 0, count);
  125.         value = newValue;
  126.         shared = false;
  127.     }
  128.     }
  129.  
  130.     /**
  131.      * Sets the length of the string. If the length is reduced, characters
  132.      * are lost. If the length is extended, the values of the new characters
  133.      * are set to 0.
  134.      * @param newLength    the new length of the buffer
  135.      * @exception StringIndexOutOfRangeException  invalid length
  136.      */
  137.     public synchronized void setLength(int newLength) {
  138.     if (newLength < 0) {
  139.         throw new StringIndexOutOfRangeException(newLength);
  140.     }
  141.     ensureCapacity(newLength);
  142.  
  143.     if (count < newLength) {
  144.         copyWhenShared();
  145.         for (; count < newLength; count++) {
  146.         value[count] = '\0';
  147.         }
  148.     }
  149.     count = newLength;
  150.     }
  151.  
  152.     /**
  153.      * Returns the character at the specified index. An index ranges
  154.      * from 0..length()-1.
  155.      * @param index    the index of the desired character
  156.      * @return        the desired character
  157.      */
  158.     public synchronized char charAt(int index) {
  159.     if ((index < 0) || (index >= count)) {
  160.         throw new StringIndexOutOfRangeException(index);
  161.     }
  162.     return value[index];
  163.     }
  164.  
  165.     /**
  166.      * Copies the characters of the specified substring (determined by
  167.      * beginIndex and endIndex) into the character array, starting at the
  168.      * array's dstIndex location. Both scrBegin and scrEnd must be legal
  169.      * indexes into the buffer.
  170.      * @param srcBegin    begin copy at this offset in the String
  171.      * @param srcEnd    stop copying at this offset in the String
  172.      * @param dst        the array to copy the data into
  173.      * @param dstBegin    offset into dst
  174.      * @exception StringIndexOutOfRangeException Invalid index into the buffer
  175.      */
  176.     public synchronized void getChars(int srcBegin, int srcEnd, char dst[], int dstBegin) {
  177.     if ((srcBegin < 0) || (srcBegin >= count)) {
  178.         throw new StringIndexOutOfRangeException(srcBegin);
  179.     }
  180.     if ((srcEnd < 0) || (srcEnd > count)) {
  181.         throw new StringIndexOutOfRangeException(srcEnd);
  182.     }
  183.     if (srcBegin < srcEnd) {
  184.         System.arraycopy(value, srcBegin, dst, dstBegin, srcEnd - srcBegin);
  185.     }
  186.     }
  187.  
  188.     /**
  189.      * Sets the character at the index to be newCharacter.
  190.      * @param index    the index of the character
  191.      * @param ch        the new character
  192.      * @exception    ArrayIndexOutOfBoundsException Invalid index
  193.      */
  194.     public synchronized void setCharAt(int index, char ch) {
  195.     if ((index < 0) || (index >= count)) {
  196.         throw new StringIndexOutOfRangeException(index);
  197.     }
  198.     copyWhenShared();
  199.     value[index] = ch;
  200.     }
  201.  
  202.     /**
  203.      * Appends an object to the end of this buffer.
  204.      * @param obj    the object to be appended
  205.      * @return     the StringBuffer itself, NOT a new one.
  206.      */
  207.     public synchronized StringBuffer append(Object obj) {
  208.     return append(String.valueOf(obj));
  209.     }
  210.  
  211.     /**
  212.      * Appends a string to the end of this buffer.
  213.      * @param str    the string to be appended
  214.      * @return     the StringBuffer itself, NOT a new one.
  215.      */
  216.     public synchronized StringBuffer append(String str) {
  217.     if (str == null) {
  218.         str = String.valueOf(str);
  219.     }
  220.  
  221.     int len = str.length();
  222.     ensureCapacity(count + len);
  223.     copyWhenShared();
  224.     str.getChars(0, len, value, count);
  225.     count += len;
  226.     return this;
  227.     }
  228.  
  229.     /**
  230.      * Appends an array of characters to the end of this buffer.
  231.      * @param str    the characters to be appended
  232.      * @return     the StringBuffer itself, NOT a new one.
  233.      */
  234.     public synchronized StringBuffer append(char str[]) {
  235.     int len = str.length;
  236.     ensureCapacity(count + len);
  237.     copyWhenShared();
  238.     System.arraycopy(str, 0, value, count, len);
  239.     count += len;
  240.     return this;
  241.     }
  242.  
  243.     /**
  244.      * Appends a part of an array of characters to the end of this buffer.
  245.      * @param str    the characters to be appended
  246.      * @param offset    where to start
  247.      * @param len    the number of characters to add
  248.      * @return     the StringBuffer itself, NOT a new one.
  249.      */
  250.     public synchronized StringBuffer append(char str[], int offset, int len) {
  251.     ensureCapacity(count + len);
  252.     copyWhenShared();
  253.     System.arraycopy(str, offset, value, count, len);
  254.     count += len;
  255.     return this;
  256.     }
  257.  
  258.     /**
  259.      * Appends a boolean to the end of this buffer.
  260.      * @param b    the boolean to be appended
  261.      * @return     the StringBuffer itself, NOT a new one.
  262.      */
  263.     public StringBuffer append(boolean b) {
  264.     return append(String.valueOf(b));
  265.     }
  266.  
  267.     /**
  268.      * Appends an integer to the end of this buffer.
  269.      * @param i    the integer to be appended
  270.      * @return     the StringBuffer itself, NOT a new one.
  271.      */
  272.     public StringBuffer append(int i) {
  273.     return append(String.valueOf(i));
  274.     }
  275.  
  276.     /**
  277.      * Appends a long to the end of this buffer.
  278.      * @param l    the long to be appended
  279.      * @return     the StringBuffer itself, NOT a new one.
  280.      */
  281.     public StringBuffer append(long l) {
  282.     return append(String.valueOf(l));
  283.     }
  284.  
  285.     /**
  286.      * Appends a float to the end of this buffer.
  287.      * @param f    the float to be appended
  288.      * @return     the StringBuffer itself, NOT a new one.
  289.      */
  290.     public StringBuffer append(float f) {
  291.     return append(String.valueOf(f));
  292.     }
  293.  
  294.     /**
  295.      * Appends a double to the end of this buffer.
  296.      * @param d    the double to be appended
  297.      * @return     the StringBuffer itself, NOT a new one.
  298.      */
  299.     public StringBuffer append(double d) {
  300.     return append(String.valueOf(d));
  301.     }
  302.  
  303.     /**
  304.      * Appends a character to the end of this buffer.
  305.      * @param ch    the character to be appended
  306.      * @return     the StringBuffer itself, NOT a new one.
  307.      */
  308.     public synchronized StringBuffer appendChar(int ch) {
  309.     ensureCapacity(count + 1);
  310.     copyWhenShared();
  311.     value[count++] = (char)ch;
  312.     return this;
  313.     }
  314.  
  315.     /**
  316.      * Inserts an object into the string buffer.
  317.      * @param offset    the offset at which to insert
  318.      * @param obj        the object to insert
  319.      * @return         the StringBuffer itself, NOT a new one.
  320.      * @exception    ArrayIndexOutOfBoundsException Invalid offset
  321.      */
  322.     public synchronized StringBuffer insert(int offset, Object obj) {
  323.     return insert(offset, String.valueOf(obj));
  324.     }
  325.  
  326.     /**
  327.      * Inserts a string into the string buffer.
  328.      * @param offset    the offset at which to insert
  329.      * @param str        the string to insert
  330.      * @return         the StringBuffer itself, NOT a new one.
  331.      * @exception    ArrayIndexOutOfBoundsException Invalid offset
  332.      */
  333.     public synchronized StringBuffer insert(int offset, String str) {
  334.     if ((offset < 0) || (offset > count)) {
  335.         throw new ArrayIndexOutOfBoundsException();
  336.     }
  337.     int len = str.length();
  338.     ensureCapacity(count + len);
  339.     copyWhenShared();
  340.     System.arraycopy(value, offset, value, offset + len, count - offset);
  341.     str.getChars(0, len, value, offset);
  342.     count += len;
  343.     return this;
  344.     }
  345.  
  346.     /**
  347.      * Inserts an array of characters into the string buffer.
  348.      * @param offset    the offset at which to insert
  349.      * @param str        the characters to insert
  350.      * @return         the StringBuffer itself, NOT a new one.
  351.      * @exception    ArrayIndexOutOfBoundsException Invalid offset
  352.      */
  353.     public synchronized StringBuffer insert(int offset, char str[]) {
  354.     if ((offset < 0) || (offset > count)) {
  355.         throw new ArrayIndexOutOfBoundsException();
  356.     }
  357.     int len = str.length;
  358.     ensureCapacity(count + len);
  359.     copyWhenShared();
  360.     System.arraycopy(value, offset, value, offset + len, count - offset);
  361.     System.arraycopy(str, 0, value, offset, len);
  362.     count += len;
  363.     return this;
  364.     }
  365.  
  366.     /**
  367.      * Inserts a boolean into the string buffer.
  368.      * @param offset    the offset at which to insert
  369.      * @param b        the boolean to insert
  370.      * @return         the StringBuffer itself, NOT a new one.
  371.      * @exception    ArrayIndexOutOfBoundsException Invalid offset
  372.      */
  373.     public StringBuffer insert(int offset, boolean b) {
  374.     return insert(offset, String.valueOf(b));
  375.     }
  376.  
  377.     /**
  378.      * Inserts an integer into the string buffer.
  379.      * @param offset    the offset at which to insert
  380.      * @param i        the integer to insert
  381.      * @return         the StringBuffer itself, NOT a new one.
  382.      * @exception    ArrayIndexOutOfBoundsException Invalid offset
  383.      */
  384.     public StringBuffer insert(int offset, int i) {
  385.     return insert(offset, String.valueOf(i));
  386.     }
  387.  
  388.     /**
  389.      * Inserts a long into the string buffer.
  390.      * @param offset    the offset at which to insert
  391.      * @param l        the long to insert
  392.      * @return         the StringBuffer itself, NOT a new one.
  393.      * @exception    ArrayIndexOutOfBoundsException Invalid offset
  394.      */
  395.     public StringBuffer insert(int offset, long l) {
  396.     return insert(offset, String.valueOf(l));
  397.     }
  398.  
  399.     /**
  400.      * Inserts a float into the string buffer.
  401.      * @param offset    the offset at which to insert
  402.      * @param f        the float to insert
  403.      * @return         the StringBuffer itself, NOT a new one.
  404.      * @exception    ArrayIndexOutOfBoundsException Invalid offset
  405.      */
  406.     public StringBuffer insert(int offset, float f) {
  407.     return insert(offset, String.valueOf(f));
  408.     }
  409.  
  410.     /**
  411.      * Inserts a double into the string buffer.
  412.      * @param offset    the offset at which to insert
  413.      * @param d        the double to insert
  414.      * @return         the StringBuffer itself, NOT a new one.
  415.      * @exception    ArrayIndexOutOfBoundsException invalid offset
  416.      */
  417.     public StringBuffer insert(int offset, double d) {
  418.     return insert(offset, String.valueOf(d));
  419.     }
  420.  
  421.     /**
  422.      * Inserts a character into the string buffer.
  423.      * @param offset    the offset at which to insert
  424.      * @param ch        the character to insert
  425.      * @return         the StringBuffer itself, NOT a new one.
  426.      * @exception    ArrayIndexOutOfBoundsException Invalid offset
  427.      */
  428.     public synchronized StringBuffer insertChar(int offset, char ch) {
  429.     ensureCapacity(count + 1);
  430.     copyWhenShared();
  431.     System.arraycopy(value, offset, value, offset + 1, count - offset);
  432.     value[offset] = ch;
  433.     count += 1;
  434.     return this;
  435.     }
  436.  
  437.     /**
  438.      * Converts to a String
  439.      * @return the string representing the data in the buffer
  440.      */
  441.     public synchronized String toString() {
  442.     shared = true;
  443.     return new String(value, 0, count);
  444.     }
  445. }
  446.