//
// Copyright (c) 2006, Brian Frank and Andy Frank
// Licensed under the Academic Free License version 3.0
//
// History:
//   4 Jan 06  Brian Frank  Creation
//

**
** StrBuf is a mutable sequence of Int characters.
**
final class StrBuf
{

//////////////////////////////////////////////////////////////////////////
// Construction
//////////////////////////////////////////////////////////////////////////

  **
  ** Create with initial capacity (defaults to 16).
  **
  new make(Int capacity := 16)

//////////////////////////////////////////////////////////////////////////
// Methods
//////////////////////////////////////////////////////////////////////////

  **
  ** Return if size() == 0.
  **
  Bool isEmpty()

  **
  ** Return the number of characters in the buffer.
  **
  Int size()

  **
  ** The number of characters this buffer can hold without
  ** allocating more memory.
  **
  Int capacity

  **
  ** Get the character at the zero based index as a Unicode code point.
  ** Negative indexes may be used to access from the end of the string buffer.
  ** This method is accessed via the [] operator.
  **
  @Operator Int get(Int index)

  **
  ** Return a substring based on the specified range.  Negative indexes
  ** may be used to access from the end of the string buffer.  This method
  ** is accessed via the [] operator.  Throw IndexErr if range illegal.
  **
  ** Examples:
  **   "abcd"[0..2]   => "abc"
  **   "abcd"[3..3]   => "d"
  **   "abcd"[-2..-1] => "cd"
  **   "abcd"[0..<2]  => "ab"
  **   "abcd"[1..-2]  => "bc"
  **   "abcd"[4..-1]  => ""
  **
  @Operator Str getRange(Range range)

  **
  ** Replace the existing character at index in this buffer.
  ** Negative indexes may be used to access from the end of
  ** the string buffer.  This method is accessed via the []
  ** operator.  Return this.
  **
  @Operator This set(Int index, Int ch)

  **
  ** Add x.toStr to the end of this buffer.  If x is null then
  ** the string "null" is inserted.  Return this.
  **
  This add(Obj? x)

  **
  ** Optimized implementation for add(ch.toChar).  Return this.
  **
  This addChar(Int ch)

  **
  ** Add a substring of the given string to the buffer.  Return this.
  **
  This addRange(Str s, Range r)

  **
  ** Add x.toStr to the end of the buffer.  If the buffer is not
  ** empty, then first add the specified separator which defaults
  ** to a space if not specified.  Return this.
  **
  This join(Obj? x, Str sep := " ")

  **
  ** Insert x.toStr into this buffer at the specified index.
  ** If x is null then the string "null" is inserted.  Negative
  ** indexes may be used to access from the end of the string
  ** buffer.  Throw IndexErr if index is out of range.  Return
  ** this.
  **
  This insert(Int index, Obj? x)

  **
  ** Remove the char at the specified index.  A negative index may be
  ** used to access an index from the end of the list.  Size is decremented
  ** by 1.  Return this.  Throw IndexErr if index is out of range.
  **
  This remove(Int index)

  **
  ** Remove a range of indices from this buffer.  Negative indexes
  ** may be used to access from the end of the list.  Throw IndexErr
  ** if range illegal.  Return this.
  **
  This removeRange(Range r)

  **
  ** Replaces a range of indices from this buffer with the specified string.
  ** Negative indexes may be used to access from the end of the buffer.
  ** Throw IndexErr if range illegal.  Return this.
  **
  This replaceRange(Range r, Str str)

  **
  ** Reverse the contents of this string buffer.  Return this.
  **
  This reverse()

  **
  ** Clear the contents of the string buffer so that it
  ** has a size of zero.  Return this.
  **
  This clear()

//////////////////////////////////////////////////////////////////////////
// Conversion
//////////////////////////////////////////////////////////////////////////

  **
  ** Return the current buffer contents as a Str.
  **
  override Str toStr()

  **
  ** Create an output stream to append characters to this string
  ** buffer.  The output stream is designed to write character data,
  ** attempts to do binary writes will throw UnsupportedErr.
  **
  OutStream out()

}