Re: icu api proposal: read-only UnicodeString::getBuffer & releaseBuffer

[Markus S. <mar...@jt...>]

Andy brought up very good questions that I could not answer, so he and Mark and I had a long discussion to figure out what semantics make sense for getBuffer/releaseBuffer.
This is what we came up with. We feel that this is useful, consistent, and implementable.

There will be three functions, not four. In detail:

* UChar *getBuffer(int32_t minCapacity);
* void releaseBuffer(int32_t newLength=-1);

When you call getBuffer(minCapacity) then
- you get a pointer to the internal buffer, with at least minCapacity UChars
- minCapacity=-1 will default to the current capacity
- you can read from and write to the buffer
- the length of the UnicodeString will be set to 0 and
  it will behave in read APIs like any 0-length string
- write access will be disallowed;
  any write API calls on this UnicodeString will have no effect
- the previous contents of the string will still be in the buffer;
  if you want to use that, then you should call length() before getBuffer()
- a getBuffer() call on an empty (length 0) string will return NULL
- a nested getBuffer() call is not allowed;
  it will also return NULL and will not further modify the state of the string
- you must call releaseBuffer(newLength) before and in order to
  return to normal UnicodeString operation

When you call releaseBuffer(newLength) then
- it will set the string length to newLength, at most to the capacity
- if newLength==-1 then it will set the length according to the
  first NUL in the buffer, or to the capacity if there is no NUL
- releaseBuffer() must be called if and only if a getBuffer() is "open"
- after calling releaseBuffer() the UnicodeString is back to normal operation

* const UChar *getBuffer(void) const;
* Drop the second releaseBuffer(), the one that was to match the const-getBuffer().

The const-getBuffer() can be called at any time on a valid UnicodeString,
even during an open write-getBuffer().
It returns NULL if the string is empty or bogus.
It can be called as many times as desired.
The pointer that it returns will remain valid until the UnicodeString object is modified,
at which time the pointer is semantically invalidated and must not be used any more.


markus