Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

text deltas

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 svn_txdelta_op_t svn_txdelta_op_t
 A single text delta instruction.

typedef 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 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.


Enumerations

enum  svn_delta_action {
  svn_txdelta_source,
  svn_txdelta_target,
  svn_txdelta_new
}

Functions

svn_txdelta_window_tsvn_txdelta_window_dup (const svn_txdelta_window_t *window, apr_pool_t *pool)
 Return a deep copy of window, allocated in pool.

svn_error_tsvn_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_txdelta (svn_txdelta_stream_t **stream, svn_stream_t *source, svn_stream_t *target, 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.

svn_stream_tsvn_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/@a handler_baton which transform the data in source to the target data.

svn_error_tsvn_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/@a baton.

svn_error_tsvn_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/@a baton.

svn_error_tsvn_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/@a 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_svndiff (svn_stream_t *output, apr_pool_t *pool, svn_txdelta_window_handler_t *handler, void **handler_baton)
 Prepare to produce an svndiff-format diff from text delta windows.

svn_stream_tsvn_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_tsvn_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_tsvn_txdelta_skip_svndiff_window (apr_file_t *file, int svndiff_version, apr_pool_t *pool)
 Skip one delta window in svndiff format in 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:


Typedef Documentation

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 201 of file svn_delta.h.

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 193 of file svn_delta.h.

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

enum svn_delta_action
 

Enumeration values:
svn_txdelta_source  Append the len bytes at offset in the source view to the target.

It must be the case that 0 <= offset < offset + len <= size of source view.

svn_txdelta_target  Append the len 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 + len 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 len 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 len 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 len bytes at offset in the window's new string to the target.

It must be the case that 0 <= offset < offset + len <= 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 82 of file svn_delta.h.


Function Documentation

void svn_txdelta svn_txdelta_stream_t **    stream,
svn_stream_t   source,
svn_stream_t   target,
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.

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

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.)

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

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_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_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.

If error_on_early_close is TRUE, attempting to close this stream before it has handled the entire svndiff data set will result in SVN_ERR_SVNDIFF_UNEXPECTED_END, else this error condition will be ignored.

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_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/@a 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_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/@a 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_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/@a baton.

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

All temporary allocation is performed in pool.

svn_error_t* svn_txdelta_skip_svndiff_window apr_file_t *    file,
int    svndiff_version,
apr_pool_t *    pool
 

Skip one delta window in svndiff format in the file file.

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 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_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/@a 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.

void svn_txdelta_to_svndiff svn_stream_t   output,
apr_pool_t *    pool,
svn_txdelta_window_handler_t   handler,
void **    handler_baton
 

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.

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.


Generated on Wed Jun 7 11:02:40 2006 for Subversion by doxygen1.2.18