1 files changed, 75 insertions, 0 deletions
diff --git a/txr.1 b/txr.1
index 5f3dc45f..54c9cee3 100644
--- a/txr.1
+++ b/txr.1
@@ -30515,6 +30515,81 @@ The following equivalence holds:
   (buf-binary-width b)  <-->  (width (uint-buf b))
 .brev
 
+.coNP Function @ buf-xor-pattern
+.synb
+.mets (buf-xor-pattern < buf << pat )
+.syne
+.desc
+The
+.code buf-xor-pattern
+function calculates a new buffer of the same size as
+.metn buf ,
+whose contents are the result of an exclusive "or" operation between
+.meta buf
+and
+.metn pat .
+
+The
+.meta pat
+argument may be an integer or a buffer.
+
+If
+.meta pat
+is a negative integer, it specifies a left-aligned operation.
+In this case, the pattern is specified by the positive integer
+which is the additive inverse of the negative integer.  If
+.meta pat
+is a buffer, the operation is always right-aligned.
+
+Left-aligned means that the the first byte of the buffer
+corresponds with the first byte of the pattern. Right
+aligned means that the last bytes of the buffer and pattern
+correspond.
+
+An integer is turned into a pattern by dividing the integer's
+binary representation into octets, in a big-endian orientation.
+For instance the integer
+.code #x3FEDA
+is turned into the octets , given in hexadecimal:
+.codn 03 ,
+.code FE
+and
+.codn DA .
+The pattern has only as many bytes are are required to
+represent the integer value. Thus a value in the range
+0 to 255 specifies a one-byte pattern, a value in the
+range 256 to 65535 a two-byte pattern and so forth.
+
+If the pattern has fewer bytes than
+.meta buf
+then it is repeated. Any repetition of the pattern
+which doesn't fit into the buffer length is truncated
+on the opposite side of the alignment mode: truncated
+on the left under right alignment and vice versa.
+
+.TP* Examples
+
+.verb
+  ;; empty input buffer maps to empty output buffer
+  (buf-xor-pattern #b'' 0) -> #b''
+
+  ;; right-aligned three-byte pattern
+  (buf-xor-pattern #b'00000000000000' #xcafe13)
+  -->  #b'13cafe13cafe13' 
+
+  ;; left-aligned three-byte pattern
+  (buf-xor-pattern #b'00000000000000' #x-cafe13)
+  -->  #b'cafe13cafe13ca' 
+
+  ;; one-byte pattern
+  (buf-xor-pattern #b'aa5500' 255)
+  -->  #b'55aaff'
+
+  ;; buffer pattern
+  (buf-xor-pattern #b'ff550000ff' #b'ff00')
+  --> #b'ffaa00ffff'
+.brev
+
 .coNP Functions @ buf-compress and @ buf-decompress
 .synb
 .mets (buf-compress < buf <> [ level ])