Returns a writable buffer for appending and writes the buffer's capacity to *result_capacity.
Guarantees *result_capacity>=min_capacity. May return a pointer to the caller-owned scratch buffer which must have scratch_capacity>=min_capacity. The returned buffer is only valid until the next operation on this ByteSink.
After writing at most *result_capacity bytes, call Append() with the pointer returned from this function and the number of bytes written. Many Append() implementations will avoid copying bytes if this function returned an internal buffer.
Partial usage example: int32_t capacity; char* buffer = sink->GetAppendBuffer(..., &capacity); ... Write n bytes into buffer, with n <= capacity. sink->Append(buffer, n); In many implementations, that call to Append will avoid copying bytes.
If the ByteSink allocates or reallocates an internal buffer, it should use the desired_capacity_hint if appropriate. If a caller cannot provide a reasonable guess at the desired capacity, it should pass desired_capacity_hint=0.
If a non-scratch buffer is returned, the caller may only pass a prefix to it to Append(). That is, it is not correct to pass an interior pointer to Append().
The default implementation always returns the scratch buffer.
- Parameters:
-
min_capacity | required minimum capacity of the returned buffer; must be non-negative |
desired_capacity_hint | desired capacity of the returned buffer; must be non-negative |
scratch | default caller-owned buffer |
scratch_capacity | capacity of the scratch buffer |
result_capacity | pointer to an integer which will be set to the capacity of the returned buffer |
- Returns:
- a buffer with *result_capacity>=min_capacity
- Stable:
- ICU 4.2
Reimplemented in CheckedArrayByteSink.