Loading...
Searching...
No Matches
Text deltas
Delta generation and handling

Text deltas. More...

## Data Structures

struct | svn_txdelta_op_t
| A single text delta instruction. More...
struct | svn_txdelta_window_t
| An svn_txdelta_window_t object describes how to reconstruct a contiguous section of the target string (the "target view") using a specified contiguous region of the source string (the "source view"). More...

## Typedefs

typedef struct svn_txdelta_op_t | svn_txdelta_op_t
| A single text delta instruction.
typedef struct svn_txdelta_window_t | svn_txdelta_window_t
| An svn_txdelta_window_t object describes how to reconstruct a contiguous section of the target string (the "target view") using a specified contiguous region of the source string (the "source view").
typedef svn_error_t *(* | svn_txdelta_window_handler_t) (svn_txdelta_window_t *window, void *baton)
| A typedef for functions that consume a series of delta windows, for use in caller-pushes interfaces.
typedef struct svn_txdelta_stream_t | svn_txdelta_stream_t
| A delta stream — this is the hat from which we pull a series of svn_txdelta_window_t objects, which, taken in order, describe the entire target string.
typedef svn_error_t *(* | svn_txdelta_next_window_fn_t) (svn_txdelta_window_t **window, void *baton, apr_pool_t *pool)
| A typedef for a function that will set *window to the next window from a svn_txdelta_stream_t object.
typedef const unsigned char *(* | svn_txdelta_md5_digest_fn_t) (void *baton)
| A typedef for a function that will return the md5 checksum of the fulltext deltified by a svn_txdelta_stream_t object.
typedef svn_error_t *(* | svn_txdelta_stream_open_func_t) (svn_txdelta_stream_t **txdelta_stream, void *baton, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
| A typedef for a function that opens an svn_txdelta_stream_t object, allocated in result_pool.

## Enumerations

enum | svn_delta_action { svn_txdelta_source , svn_txdelta_target , svn_txdelta_new }
| Action codes for text delta instructions. More...

## Functions

svn_txdelta_window_t * | svn_txdelta_window_dup (const svn_txdelta_window_t *window, apr_pool_t *pool)
| Return a deep copy of window, allocated in pool.
svn_txdelta_window_t * | svn_txdelta_compose_windows (const svn_txdelta_window_t *window_A, const svn_txdelta_window_t *window_B, apr_pool_t *pool)
| Compose two delta windows, yielding a third, allocated in pool.
void | svn_txdelta_apply_instructions (svn_txdelta_window_t *window, const char *sbuf, char *tbuf, apr_size_t *tlen)
| Apply the instructions from window to a source view sbuf to produce a target view tbuf.
svn_error_t * | svn_txdelta_run (svn_stream_t *source, svn_stream_t *target, svn_txdelta_window_handler_t handler, void *handler_baton, svn_checksum_kind_t checksum_kind, svn_checksum_t **checksum, svn_cancel_func_t cancel_func, void *cancel_baton, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
| This function will generate delta windows that turn source into target, and pushing these windows into the handler window handler callback (passing handler_baton to each invocation).
svn_txdelta_stream_t * | svn_txdelta_stream_create (void *baton, svn_txdelta_next_window_fn_t next_window, svn_txdelta_md5_digest_fn_t md5_digest, apr_pool_t *pool)
| Create and return a generic text delta stream with baton, next_window and md5_digest.
svn_error_t * | svn_txdelta_next_window (svn_txdelta_window_t **window, svn_txdelta_stream_t *stream, apr_pool_t *pool)
| Set *window to a pointer to the next window from the delta stream stream.
const unsigned char * | svn_txdelta_md5_digest (svn_txdelta_stream_t *stream)
| Return the md5 digest for the complete fulltext deltified by stream, or `NULL` if stream has not yet returned its final `NULL` window.
void | svn_txdelta2 (svn_txdelta_stream_t **stream, svn_stream_t *source, svn_stream_t *target, svn_boolean_t calculate_checksum, apr_pool_t *pool)
| Set *stream to a pointer to a delta stream that will turn the byte string from source into the byte stream from target.
void | svn_txdelta (svn_txdelta_stream_t **stream, svn_stream_t *source, svn_stream_t *target, apr_pool_t *pool)
| Similar to svn_txdelta2 but always calculating the target checksum.
svn_stream_t * | svn_txdelta_target_push (svn_txdelta_window_handler_t handler, void *handler_baton, svn_stream_t *source, apr_pool_t *pool)
| Return a writable stream which, when fed target data, will send delta windows to handler/handler_baton which transform the data in source to the target data.
svn_error_t * | svn_txdelta_send_string (const svn_string_t *string, svn_txdelta_window_handler_t handler, void *handler_baton, apr_pool_t *pool)
| Send the contents of string to window-handler handler/baton.
svn_error_t * | svn_txdelta_send_stream (svn_stream_t *stream, svn_txdelta_window_handler_t handler, void *handler_baton, unsigned char *digest, apr_pool_t *pool)
| Send the contents of stream to window-handler handler/baton.
svn_error_t * | svn_txdelta_send_txstream (svn_txdelta_stream_t *txstream, svn_txdelta_window_handler_t handler, void *handler_baton, apr_pool_t *pool)
| Send the contents of txstream to window-handler handler/baton.
svn_error_t * | svn_txdelta_send_contents (const unsigned char *contents, apr_size_t len, svn_txdelta_window_handler_t handler, void *handler_baton, apr_pool_t *pool)
| Send the contents of length len as a txdelta against an empty source directly to window-handler handler/handler_baton.
void | svn_txdelta_apply (svn_stream_t *source, svn_stream_t *target, unsigned char *result_digest, const char *error_info, apr_pool_t *pool, svn_txdelta_window_handler_t *handler, void **handler_baton)
| Prepare to apply a text delta.
void | svn_txdelta_to_svndiff3 (svn_txdelta_window_handler_t *handler, void **handler_baton, svn_stream_t *output, int svndiff_version, int compression_level, apr_pool_t *pool)
| Prepare to produce an svndiff-format diff from text delta windows.
void | svn_txdelta_to_svndiff2 (svn_txdelta_window_handler_t *handler, void **handler_baton, svn_stream_t *output, int svndiff_version, apr_pool_t *pool)
| Similar to svn_txdelta_to_svndiff3(), but always using the SVN default compression level (SVN_DELTA_COMPRESSION_LEVEL_DEFAULT).
void | svn_txdelta_to_svndiff (svn_stream_t *output, apr_pool_t *pool, svn_txdelta_window_handler_t *handler, void **handler_baton)
| Similar to svn_txdelta_to_svndiff2, but always using svndiff version 0.
svn_stream_t * | svn_txdelta_to_svndiff_stream (svn_txdelta_stream_t *txstream, int svndiff_version, int compression_level, apr_pool_t *pool)
| Return a readable generic stream which will produce svndiff-encoded text delta from the delta stream txstream.
svn_stream_t * | svn_txdelta_parse_svndiff (svn_txdelta_window_handler_t handler, void *handler_baton, svn_boolean_t error_on_early_close, apr_pool_t *pool)
| Return a writable generic stream which will parse svndiff-format data into a text delta, invoking handler with handler_baton whenever a new window is ready.
svn_error_t * | svn_txdelta_read_svndiff_window (svn_txdelta_window_t **window, svn_stream_t *stream, int svndiff_version, apr_pool_t *pool)
| Read and parse one delta window in svndiff format from the readable stream stream and place it in *window, allocating the result in pool.
svn_error_t * | svn_txdelta_skip_svndiff_window (apr_file_t *file, int svndiff_version, apr_pool_t *pool)
| Read and skip one delta window in svndiff format from the file file.

## Detailed Description

Text deltas.

A text delta represents the difference between two strings of bytes, the source' string and the target' string. Given a source string and a target string, we can compute a text delta; given a source string and a delta, we can reconstruct the target string. However, note that deltas are not reversible: you cannot always reconstruct the source string given the target string and delta.

Since text deltas can be very large, the interface here allows us to produce and consume them in pieces. Each piece, represented by an svn_txdelta_window_t structure, describes how to produce the next section of the target string.

To compute a new text delta:

- We call svn_txdelta() on the streams we want to compare. That returns us an svn_txdelta_stream_t object.
- We then call svn_txdelta_next_window() on the stream object repeatedly. Each call returns a new svn_txdelta_window_t object, which describes the next portion of the target string. When svn_txdelta_next_window() returns zero, we are done building the target string.

## Typedef Documentation

## svn_txdelta_md5_digest_fn_t

typedef const unsigned char *(* svn_txdelta_md5_digest_fn_t) (void *baton)

A typedef for a function that will return the md5 checksum of the fulltext deltified by a svn_txdelta_stream_t object.

Will return NULL if the final null window hasn't yet been returned by the stream. The returned value will be allocated in the same pool as the stream. baton is the baton specified when the stream was created.

Since
  New in 1.4.

Definition at line 330 of file svn_delta.h.

## svn_txdelta_next_window_fn_t

typedef svn_error_t *(* svn_txdelta_next_window_fn_t) (svn_txdelta_window_t **window, void *baton, apr_pool_t *pool)

A typedef for a function that will set *window to the next window from a svn_txdelta_stream_t object.

If there are no more delta windows, NULL will be used. The returned window, if any, will be allocated in pool. baton is the baton specified when the stream was created.

Since
  New in 1.4.

Definition at line 316 of file svn_delta.h.

## svn_txdelta_stream_open_func_t

typedef svn_error_t *(* svn_txdelta_stream_open_func_t) (svn_txdelta_stream_t **txdelta_stream, void *baton, apr_pool_t *result_pool, apr_pool_t *scratch_pool)

A typedef for a function that opens an svn_txdelta_stream_t object, allocated in result_pool.

baton is provided by the caller. Any temporary allocations may be performed in scratch_pool.

Since
  New in 1.10.

Definition at line 339 of file svn_delta.h.

## svn_txdelta_stream_t

typedef struct svn_txdelta_stream_t svn_txdelta_stream_t

A delta stream — this is the hat from which we pull a series of svn_txdelta_window_t objects, which, taken in order, describe the entire target string.

This type is defined within libsvn_delta, and opaque outside that library.

Definition at line 305 of file svn_delta.h.

## svn_txdelta_window_handler_t

typedef svn_error_t *(* svn_txdelta_window_handler_t) (svn_txdelta_window_t *window, void *baton)

A typedef for functions that consume a series of delta windows, for use in caller-pushes interfaces.

Such functions will typically apply the delta windows to produce some file, or save the windows somewhere. At the end of the delta window stream, you must call this function passing zero for the window argument.

Definition at line 265 of file svn_delta.h.

## svn_txdelta_window_t

typedef struct svn_txdelta_window_t svn_txdelta_window_t

An svn_txdelta_window_t object describes how to reconstruct a contiguous section of the target string (the "target view") using a specified contiguous region of the source string (the "source view").

It contains a series of instructions which assemble the new target string text by pulling together substrings from:

- the source view,
- the previously constructed portion of the target view,
- a string of new data contained within the window structure

The source view must always slide forward from one window to the next; that is, neither the beginning nor the end of the source view may move to the left as we read from a window stream. This property allows us to apply deltas to non-seekable source streams without making a full copy of the source stream.

## Enumeration Type Documentation

## svn_delta_action

enum svn_delta_action

Action codes for text delta instructions.

Enumerator
svn_txdelta_source | Append the length bytes at offset in the source view to the target. It must be the case that 0 <= offset < offset + length <= size of source view.

svn_txdelta_target

Append the length bytes at offset in the target view, to the target.

It must be the case that 0 <= offset < current position in the target view.

However! offset + length may be beyond the end of the existing target data. "Where the heck does the text come from, then?" If you start at offset, and append length bytes one at a time, it'll work out — you're adding new bytes to the end at the same rate you're reading them from the middle. Thus, if your current target text is "abcdefgh", and you get an svn_txdelta_target instruction whose offset is 6 and whose length is 7, the resulting string is "abcdefghghghghg". This trick is actually useful in encoding long runs of consecutive characters, long runs of CR/LF pairs, etc.

svn_txdelta_new | Append the length bytes at offset in the window's new string to the target. It must be the case that 0 <= offset < offset + length <= length of new. Windows MUST use new data in ascending order with no overlap at the moment; svn_txdelta_to_svndiff() depends on this.

Definition at line 116 of file svn_delta.h.

## Function Documentation

## svn_txdelta()

void svn_txdelta | ( | svn_txdelta_stream_t ** | stream,
|  | svn_stream_t * | source,
|  | svn_stream_t * | target,
|  | apr_pool_t * | pool )

Similar to svn_txdelta2 but always calculating the target checksum.

Deprecated
  Provided for backward compatibility with the 1.7 API.

## svn_txdelta2()

void svn_txdelta2 | ( | svn_txdelta_stream_t ** | stream,
|  | svn_stream_t * | source,
|  | svn_stream_t * | target,
|  | svn_boolean_t | calculate_checksum,
|  | apr_pool_t * | pool )

Set *stream to a pointer to a delta stream that will turn the byte string from source into the byte stream from target.

source and target are both readable generic streams. When we call svn_txdelta_next_window() on *stream, it will read from source and target to gather as much data as it needs. If calculate_checksum is set, you may call svn_txdelta_md5_digest() to get an MD5 checksum for target.

Do any necessary allocation in a sub-pool of pool.

Since
  New in 1.8.

References SVN_DEPRECATED.

## svn_txdelta_apply()

void svn_txdelta_apply | ( | svn_stream_t * | source,
|  | svn_stream_t * | target,
|  | unsigned char * | result_digest,
|  | const char * | error_info,
|  | apr_pool_t * | pool,
|  | svn_txdelta_window_handler_t * | handler,
|  | void ** | handler_baton )

Prepare to apply a text delta.

source is a readable generic stream yielding the source data, target is a writable generic stream to write target data to, and allocation takes place in a sub-pool of pool. On return, *handler is set to a window handler function and *handler_baton is set to the value to pass as the baton argument to *handler.

If result_digest is non-NULL, it points to APR_MD5_DIGESTSIZE bytes of storage, and the final call to handler populates it with the MD5 digest of the resulting fulltext.

If error_info is non-NULL, it is inserted parenthetically into the error string for any error returned by svn_txdelta_apply() or *handler. (It is normally used to provide path information, since there's nothing else in the delta application's context to supply a path for error messages.)

The source stream will NOT be closed. The target stream will be closed when the window handler is given a null window to signal the end of the delta.

Note
  To avoid lifetime issues, error_info is copied into pool or a subpool thereof.

## svn_txdelta_apply_instructions()

void svn_txdelta_apply_instructions | ( | svn_txdelta_window_t * | window,
|  | const char * | sbuf,
|  | char * | tbuf,
|  | apr_size_t * | tlen )

Apply the instructions from window to a source view sbuf to produce a target view tbuf.

sbuf is assumed to have window->sview_len bytes of data and tbuf is assumed to have room for tlen bytes of output. tlen may be more than window->tview_len, so return the actual number of bytes written. sbuf is not touched and may be NULL if window contains no source-copy operations. This is purely a memory operation; nothing can go wrong as long as we have a valid window.

Since
  New in 1.4
  Since 1.9, tbuf may be NULL if *tlen is 0.

## svn_txdelta_compose_windows()

svn_txdelta_window_t * svn_txdelta_compose_windows | ( | const svn_txdelta_window_t * | window_A,
|  | const svn_txdelta_window_t * | window_B,
|  | apr_pool_t * | pool )

Compose two delta windows, yielding a third, allocated in pool.

Since
  New in 1.4

## svn_txdelta_md5_digest()

const unsigned char * svn_txdelta_md5_digest | ( | svn_txdelta_stream_t * | stream | ) |

Return the md5 digest for the complete fulltext deltified by stream, or `NULL` if stream has not yet returned its final `NULL` window.

The digest is allocated in the same memory as STREAM.

## svn_txdelta_next_window()

svn_error_t * svn_txdelta_next_window | ( | svn_txdelta_window_t ** | window,
|  | svn_txdelta_stream_t * | stream,
|  | apr_pool_t * | pool )

Set *window to a pointer to the next window from the delta stream stream.

When we have completely reconstructed the target string, set *window to zero.

The window will be allocated in pool.

## svn_txdelta_parse_svndiff()

svn_stream_t * svn_txdelta_parse_svndiff | ( | svn_txdelta_window_handler_t | handler,
|  | void * | handler_baton,
|  | svn_boolean_t | error_on_early_close,
|  | apr_pool_t * | pool )

Return a writable generic stream which will parse svndiff-format data into a text delta, invoking handler with handler_baton whenever a new window is ready.

When the caller closes this stream, this will signal completion to the window handler by invoking handler once more, passing zero for the `window` argument.

If error_on_early_close is `TRUE`, then attempt to avoid signaling completion to the window handler if the delta was incomplete. Specifically, attempting to close the stream will be successful only if the data written to the stream consisted of one or more complete windows of svndiff data and no extra bytes. Otherwise, closing the stream will not signal completion to the window handler, and will return a SVN_ERR_SVNDIFF_UNEXPECTED_END error. Note that if no data at all was written, the delta is considered incomplete.

If error_on_early_close is `FALSE`, closing the stream will signal completion to the window handler, regardless of how much data was written, and discard any pending incomplete data.

Allocate the stream in pool.

## svn_txdelta_read_svndiff_window()

svn_error_t * svn_txdelta_read_svndiff_window | ( | svn_txdelta_window_t ** | window,
|  | svn_stream_t * | stream,
|  | int | svndiff_version,
|  | apr_pool_t * | pool )

Read and parse one delta window in svndiff format from the readable stream stream and place it in *window, allocating the result in pool.

The caller must take responsibility for stripping off the four-byte 'SVN<ver>' header at the beginning of the svndiff document before reading the first window, and must provide the version number (the value of the fourth byte) to each invocation of this routine with the svndiff_version argument.

Since
  New in 1.1.

## svn_txdelta_run()

svn_error_t * svn_txdelta_run | ( | svn_stream_t * | source,
|  | svn_stream_t * | target,
|  | svn_txdelta_window_handler_t | handler,
|  | void * | handler_baton,
|  | svn_checksum_kind_t | checksum_kind,
|  | svn_checksum_t ** | checksum,
|  | svn_cancel_func_t | cancel_func,
|  | void * | cancel_baton,
|  | apr_pool_t * | result_pool,
|  | apr_pool_t * | scratch_pool )

This function will generate delta windows that turn source into target, and pushing these windows into the handler window handler callback (passing handler_baton to each invocation).

If checksum is not NULL, then a checksum (of kind checksum_kind) will be computed for the target stream, and placed into *checksum.

If cancel_func is not NULL, then it should refer to a cancellation function (along with cancel_baton).

Results (the checksum) will be allocated from result_pool, and all temporary allocations will be performed in scratch_pool.

Note: this function replaces the combination of svn_txdelta() and svn_txdelta_send_txstream().

Since
  New in 1.6.

## svn_txdelta_send_contents()

svn_error_t * svn_txdelta_send_contents | ( | const unsigned char * | contents,
|  | apr_size_t | len,
|  | svn_txdelta_window_handler_t | handler,
|  | void * | handler_baton,
|  | apr_pool_t * | pool )

Send the contents of length len as a txdelta against an empty source directly to window-handler handler/handler_baton.

All temporary allocation is performed in pool.

Since
  New in 1.8.

## svn_txdelta_send_stream()

svn_error_t * svn_txdelta_send_stream | ( | svn_stream_t * | stream,
|  | svn_txdelta_window_handler_t | handler,
|  | void * | handler_baton,
|  | unsigned char * | digest,
|  | apr_pool_t * | pool )

Send the contents of stream to window-handler handler/baton.

This is effectively a 'copy' operation, resulting in delta windows that make the target equivalent to the stream.

If digest is non-NULL, populate it with the md5 checksum for the fulltext that was deltified (digest must be at least `APR_MD5_DIGESTSIZE` bytes long).

All temporary allocation is performed in pool.

## svn_txdelta_send_string()

svn_error_t * svn_txdelta_send_string | ( | const svn_string_t * | string,
|  | svn_txdelta_window_handler_t | handler,
|  | void * | handler_baton,
|  | apr_pool_t * | pool )

Send the contents of string to window-handler handler/baton.

This is effectively a 'copy' operation, resulting in delta windows that make the target equivalent to the value of string.

All temporary allocation is performed in pool.

## svn_txdelta_send_txstream()

svn_error_t * svn_txdelta_send_txstream | ( | svn_txdelta_stream_t * | txstream,
|  | svn_txdelta_window_handler_t | handler,
|  | void * | handler_baton,
|  | apr_pool_t * | pool )

Send the contents of txstream to window-handler handler/baton.

Windows will be extracted from the stream and delivered to the handler.

All temporary allocation is performed in pool.

## svn_txdelta_skip_svndiff_window()

svn_error_t * svn_txdelta_skip_svndiff_window | ( | apr_file_t * | file,
|  | int | svndiff_version,
|  | apr_pool_t * | pool )

Read and skip one delta window in svndiff format from the file file.

pool is used for temporary allocations. The caller must take responsibility for stripping off the four-byte 'SVN<ver>' header at the beginning of the svndiff document before reading or skipping the first window, and must provide the version number (the value of the fourth byte) to each invocation of this routine with the svndiff_version argument.

Since
  New in 1.1.

## svn_txdelta_stream_create()

svn_txdelta_stream_t * svn_txdelta_stream_create | ( | void * | baton,
|  | svn_txdelta_next_window_fn_t | next_window,
|  | svn_txdelta_md5_digest_fn_t | md5_digest,
|  | apr_pool_t * | pool )

Create and return a generic text delta stream with baton, next_window and md5_digest.

Allocate the new stream in pool.

Since
  New in 1.4.

## svn_txdelta_target_push()

svn_stream_t * svn_txdelta_target_push | ( | svn_txdelta_window_handler_t | handler,
|  | void * | handler_baton,
|  | svn_stream_t * | source,
|  | apr_pool_t * | pool )

Return a writable stream which, when fed target data, will send delta windows to handler/handler_baton which transform the data in source to the target data.

As usual, the window handler will receive a NULL window to signify the end of the window stream. The stream handler functions will read data from source as necessary.

Since
  New in 1.1.

## svn_txdelta_to_svndiff()

void svn_txdelta_to_svndiff | ( | svn_stream_t * | output,
|  | apr_pool_t * | pool,
|  | svn_txdelta_window_handler_t * | handler,
|  | void ** | handler_baton )

Similar to svn_txdelta_to_svndiff2, but always using svndiff version 0.

Deprecated
  Provided for backward compatibility with the 1.3 API.

## svn_txdelta_to_svndiff2()

void svn_txdelta_to_svndiff2 | ( | svn_txdelta_window_handler_t * | handler,
|  | void ** | handler_baton,
|  | svn_stream_t * | output,
|  | int | svndiff_version,
|  | apr_pool_t * | pool )

Similar to svn_txdelta_to_svndiff3(), but always using the SVN default compression level (SVN_DELTA_COMPRESSION_LEVEL_DEFAULT).

Since
  New in 1.4.

Deprecated
  Provided for backward compatibility with the 1.6 API.

References SVN_DEPRECATED.

## svn_txdelta_to_svndiff3()

void svn_txdelta_to_svndiff3 | ( | svn_txdelta_window_handler_t * | handler,
|  | void ** | handler_baton,
|  | svn_stream_t * | output,
|  | int | svndiff_version,
|  | int | compression_level,
|  | apr_pool_t * | pool )

Prepare to produce an svndiff-format diff from text delta windows.

output is a writable generic stream to write the svndiff data to. Allocation takes place in a sub-pool of pool. On return, *handler is set to a window handler function and *handler_baton is set to the value to pass as the baton argument to *handler. The svndiff version is svndiff_version. compression_level is the zlib compression level from 0 (no compression) and 9 (maximum compression).

Since
  New in 1.7. Since 1.10, svndiff_version can be 2 for the svndiff2 format. compression_level is currently ignored if svndiff_version is set to 2.

References SVN_DEPRECATED.

## svn_txdelta_to_svndiff_stream()

svn_stream_t * svn_txdelta_to_svndiff_stream | ( | svn_txdelta_stream_t * | txstream,
|  | int | svndiff_version,
|  | int | compression_level,
|  | apr_pool_t * | pool )

Return a readable generic stream which will produce svndiff-encoded text delta from the delta stream txstream.

svndiff_version and compression_level are same as in svn_txdelta_to_svndiff3().

Allocate the stream in pool.

Since
  New in 1.10.

## svn_txdelta_window_dup()

svn_txdelta_window_t * svn_txdelta_window_dup | ( | const svn_txdelta_window_t * | window,
|  | apr_pool_t * | pool )

Return a deep copy of window, allocated in pool.

Since
  New in 1.3.