Add functions encode! and encode_append!

These functions encodes from one AbstractCIGAR type to another, writing into
a MemoryView, or appending to a Vector.
These functions are now the more general primitives used to build one cigar
from another.

Author: jakobnissen

AGENTS.md

@@ -6,16 +6,16 @@ This file provides guidance to AI agents when working with code in this reposito
 
 ```bash
 # Run all tests
-JULIA_TEST_FAILFAST=true julia --project -e 'using Pkg; Pkg.test()'
+JULIA_TEST_FAILFAST=true julia --project=. --startup=no -e 'using Pkg; Pkg.test()'
 
 # Run tests with specific test file
-JULIA_TEST_FAILFAST=true julia --project test/runtests.jl
+JULIA_TEST_FAILFAST=true julia --project=. --startup=no test/runtests.jl
 
 # Run Julia REPL with project activated
-julia --project
+julia --project --startup=no
 
 # Generate documentation locally
-julia --project=docs docs/make.jl
+julia --project=docs --startup=no docs/make.jl
 ```
 
 ## Architecture

Project.toml

@@ -1,6 +1,6 @@
 name = "CIGARStrings"
 uuid = "e5b51f81-6ffd-4e20-bbec-f118e37ea906"
-version = "0.1.7"
+version = "0.1.8"
 authors = ["Jakob Nybo Nissen <jakobnybonissen@gmail.com>"]
 
 [deps]

docs/src/reference.md

@@ -22,6 +22,8 @@ CIGARStrings.try_parse
 
 ```@docs
 unsafe_switch_memory
+encode!
+encode_append!
 OP_M
 OP_I
 OP_D

src/CIGARStrings.jl

@@ -7,7 +7,8 @@ export CIGAR,
     aln_to_query, aln_to_ref, Translation, count_matches,
     BAMCIGAR, AbstractCIGAR, cigar_view!, ref, query, aln, pos_to_pos,
     unsafe_switch_memory, is_compatible,
-    normalize, unsafe_normalize, normalize!
+    normalize, unsafe_normalize, normalize!,
+    encode!, encode_append!
 
 public CIGARError, CIGARErrorType, Errors, try_parse, outside, pos, gap,
     TranslationKind, PositionMapper
@@ -268,6 +269,166 @@ Base.eltype(::Type{<:AbstractCIGAR}) = CIGARElement
 include("bytecigar.jl")
 include("bamcigar.jl")
 
+"""
+    encode!(
+            mem::MutableMemoryView{UInt8},
+            ::Type{T <: AbstractCIGAR},
+            cigar::AbstractCIGAR
+        )::T
+
+Encode `cigar` as type `T` into the beginning of `mem`,
+and return the result as a new `T` backed by `mem`.
+
+Throw a `BoundsError` if `mem` is too short to contain the whole encoding.
+
+!!! warning
+    Since the first bytes of `mem` are used to back the newly created cigar,
+    mutating `mem` after this function is being called will invalidate
+    the created cigar.
+
+# Examples
+```jldoctest
+julia> c = CIGAR("3S5M1D19X2I6M3H");
+
+julia> mem = MemoryView(zeros(UInt8, 60));
+
+julia> bc = encode!(mem, BAMCIGAR, c)
+BAMCIGAR(CIGAR("3S5M1D19X2I6M3H"))
+
+julia> n_bytes = length(MemoryView(bc));
+
+julia> ImmutableMemoryView(mem)[1:n_bytes] === MemoryView(bc)
+true
+```
+"""
+function encode!(mem::MutableMemoryView{UInt8}, ::Type{BAMCIGAR}, cigar::BAMCIGAR)
+    src_mem = MemoryView(cigar)
+    @boundscheck checkbounds(mem, eachindex(src_mem))
+    @inbounds copyto!(mem, src_mem)
+    dst = @inbounds ImmutableMemoryView(mem)[eachindex(src_mem)]
+    return BAMCIGAR(unsafe, dst, cigar.aln_len, cigar.ref_len, cigar.query_len)
+end
+
+function encode!(mem::MutableMemoryView{UInt8}, ::Type{CIGAR}, cigar::CIGAR)
+    src_mem = MemoryView(cigar)
+    @boundscheck checkbounds(mem, eachindex(src_mem))
+    @inbounds copyto!(mem, src_mem)
+    dst = @inbounds ImmutableMemoryView(mem)[eachindex(src_mem)]
+    return CIGAR(unsafe, dst, cigar.n_ops, cigar.aln_len, cigar.ref_len, cigar.query_len)
+end
+
+function encode!(mem::MutableMemoryView{UInt8}, ::Type{BAMCIGAR}, cigar::CIGAR)
+    nbytes = 4 * length(cigar)
+    @boundscheck checkbounds(mem, 1:nbytes)
+    mem = @inbounds mem[1:nbytes]
+    GC.@preserve mem begin
+        ptr = Ptr{UInt32}(pointer(mem))
+        for element in cigar
+            u = htol(getfield(element, :x))
+            unsafe_store!(ptr, u)
+            ptr += 4
+        end
+    end
+    return BAMCIGAR(unsafe, ImmutableMemoryView(mem), cigar.aln_len, cigar.ref_len, cigar.query_len)
+end
+
+function encode!(mem::MutableMemoryView{UInt8}, ::Type{CIGAR}, cigar::BAMCIGAR)
+    len = 0
+    for element in cigar
+        n = element.len % UInt32
+        n_digits = 0
+        while !iszero(n)
+            (n, r) = divrem(n, UInt32(10))
+            mem[len += 1] = r + 0x30
+            n_digits += 1
+        end
+        if n_digits > 1
+            @inbounds for digit in 1:(n_digits >>> 1)
+                a = len - n_digits + digit
+                b = len - digit + 1
+                mem[a], mem[b] = mem[b], mem[a]
+            end
+        end
+        shift = (7 * (getfield(element, :x) & 0x0f)) & 63
+        byte = ((CIGAR_BYTE_LUT >> shift) % UInt8) & 0x7f
+        mem[len += 1] = byte
+    end
+    result_mem = @inbounds ImmutableMemoryView(mem)[1:len]
+    return CIGAR(unsafe, result_mem, length(cigar) % UInt32, cigar.aln_len, cigar.ref_len, cigar.query_len)
+end
+
+"""
+    encode_append!(
+            v::Vector{UInt8},
+            ::Type{T <: AbstractCIGAR},
+            cigar::AbstractCIGAR
+        )::T
+
+Encode `cigar` as type `T` by appending its representation to `v`,
+and return the result as a new `T` backed by `v`'s memory.
+
+!!! warning
+    Since the returned cigar will use `v` as backing memory,
+    mutating `v` after this function has been called will invalidate
+    the created cigar.
+
+# Examples
+```jldoctest
+julia> c = CIGAR("3S5M1D19X2I6M3H");
+
+julia> v = UInt8[1, 2, 3, 4];
+
+julia> bc = encode_append!(v, BAMCIGAR, c)
+BAMCIGAR(CIGAR("3S5M1D19X2I6M3H"))
+
+julia> v[1:4] == 1:4 # unchanged
+true
+
+julia> MemoryView(bc) === ImmutableMemoryView(v)[5:end]
+true
+```
+"""
+function encode_append!(v::Vector{UInt8}, ::Type{T}, cigar::T) where {T <: Union{CIGAR, BAMCIGAR}}
+    src_mem = MemoryView(cigar)
+    old_len = length(v)
+    resize!(v, old_len + length(src_mem))
+    dst_mem = @inbounds MemoryView(v)[(old_len + 1):end]
+    return @inbounds encode!(dst_mem, T, cigar)
+end
+
+function encode_append!(v::Vector{UInt8}, ::Type{BAMCIGAR}, cigar::CIGAR)
+    old_len = length(v)
+    resize!(v, old_len + 4 * length(cigar))
+    dst_mem = @inbounds MemoryView(v)[(old_len + 1):end]
+    return @inbounds encode!(dst_mem, BAMCIGAR, cigar)
+end
+
+function encode_append!(v::Vector{UInt8}, ::Type{CIGAR}, cigar::BAMCIGAR)
+    old_len = length(v)
+    sizehint!(v, old_len + 2 * length(cigar); shrink = false)
+    for element in cigar
+        n = element.len % UInt32
+        n_digits = 0
+        while !iszero(n)
+            (n, r) = divrem(n, UInt32(10))
+            push!(v, r + 0x30)
+            n_digits += 1
+        end
+        if n_digits > 1
+            len = length(v)
+            @inbounds for digit in 1:(n_digits >>> 1)
+                a = len - n_digits + digit
+                b = len - digit + 1
+                v[a], v[b] = v[b], v[a]
+            end
+        end
+        shift = (7 * (getfield(element, :x) & 0x0f)) & 63
+        push!(v, ((CIGAR_BYTE_LUT >> shift) % UInt8) & 0x7f)
+    end
+    result_mem = @inbounds ImmutableMemoryView(v)[(old_len + 1):end]
+    return CIGAR(unsafe, result_mem, length(cigar) % UInt32, cigar.aln_len, cigar.ref_len, cigar.query_len)
+end
+
 const CONSUMES = let
     x = UInt32(0)
     for query in [OP_M, OP_I, OP_S, OP_H, OP_Eq, OP_X] # not PDN
@@ -528,12 +689,12 @@ function normalize end
 """
     normalize!(cigar::T, mem::MutableMemoryView{UInt8})::T where {T <: AbstractCIGAR}
 
-Same as [`normalize`](@ref), but uses allocaiton of `mem` instead of allocating
+Same as [`normalize`](@ref), but uses allocation of `mem` instead of allocating
 a new array.
 
 Throws a `BoundsError` if `mem` cannot hold the normalized cigar.
 A cigar after normalization is guaranteed to use at most as much memory
-as cigar before normalization, so if `length(mem) ≥ length(MemoryViews(cigar))`,
+as cigar before normalization, so if `length(mem) ≥ length(MemoryView(cigar))`,
 a `BoundsError` cannot happen.
 
 !!! warning

src/bamcigar.jl

@@ -74,23 +74,18 @@ end
     end
 end
 
-CIGAR(x::BAMCIGAR) = CIGAR(x, UInt8[])
-function CIGAR(x::BAMCIGAR, v::Vector{UInt8})
-    return CIGAR(
-        unsafe,
-        cigar_view!(v, x),
-        length(x) % UInt32,
-        x.aln_len,
-        x.ref_len,
-        x.query_len,
-    )
-end
+CIGAR(x::BAMCIGAR) = encode_append!(UInt8[], CIGAR, x)
+
+@deprecate CIGAR(x::BAMCIGAR, v::Vector{UInt8}) encode_append!(empty!(v), CIGAR, x)
 
 MemoryViews.MemoryView(x::BAMCIGAR) = x.mem
 
 """
     cigar_view!(v::Vector{UInt8}, x::BAMCIGAR)::ImmutableMemoryView{UInt8}
 
+!!! warning
+    This function is DEPRECATED in favor of `encode_append!`
+
 Write the ASCII (i.e. `CIGAR`) representation `x` into `v`,
 emptying `v`'s original content.
 A memory view of `v` is returned:
@@ -110,42 +105,20 @@ julia> String(mem_view) == string(CIGAR(bc))
 true
 ```
 """
-function cigar_view!(v::Vector{UInt8}, x::BAMCIGAR)
-    # Sizehint to minimum size to reduce further reallocations
-    sizehint!(v, 2 * length(x); shrink=false)
-    empty!(v)
-    for element in x
-        n = element.len % UInt32
-        n_digits = 0
-        while !iszero(n)
-            (n, r) = divrem(n, UInt32(10))
-            push!(v, r + 0x30)
-            n_digits += 1
-        end
-        if n_digits > 1
-            @inbounds for i in 1:(n_digits >>> 1)
-                a = lastindex(v) - i + 1
-                b = lastindex(v) - n_digits + i
-                v[a], v[b] = v[b], v[a]
-            end
-        end
-        shift = (7 * (getfield(element, :x) & 0x0f)) & 63
-        byte = ((CIGAR_BYTE_LUT >> shift) % UInt8) & 0x7f
-        push!(v, byte)
-    end
-    return ImmutableMemoryView(v)
-end
+function cigar_view! end
 
-BAMCIGAR(x::CIGAR) = BAMCIGAR(x, UInt8[])
+@deprecate cigar_view!(v::Vector{UInt8}, x::BAMCIGAR) MemoryView(encode_append!(empty!(v), CIGAR, x))
 
-function BAMCIGAR(x::CIGAR, v::Vector{UInt8})
-    resize!(v, 4 * length(x))
-    return @inbounds BAMCIGAR(MemoryView(v), x)
-end
+BAMCIGAR(x::CIGAR) = encode_append!(UInt8[], BAMCIGAR, x)
+
+@deprecate BAMCIGAR(x::CIGAR, v::Vector{UInt8}) encode_append!(empty!(v), BAMCIGAR, x)
 
 """
     BAMCIGAR(mem::MutableMemoryView{UInt8}, x::CIGAR)::BAMCIGAR
 
+!!! warning
+    This function is DEPRECATED. Use `encode!(mem, BAMCIGAR, x)`
+
 Construct a `BAMCIGAR` equal to `x`, using the memory `mem`.
 After calling this, `mem` may not be mutated, and is considered
 owned by the resulting `BAMCIGAR`.
@@ -165,30 +138,16 @@ julia> parent(MemoryView(cigar)) === parent(mem)
 true
 ```
 """
-function BAMCIGAR(mem::MutableMemoryView{UInt8}, x::CIGAR)
-    @boundscheck if length(mem) < 4 * length(x)
-        throw(BoundsError(mem, 4 * length(x)))
-    end
-    mem = @inbounds mem[1:(4 * length(x))]
-    i = 1
-    for element in x
-        u = getfield(element, :x)
-        for _ in 1:4
-            @inbounds mem[i] = u % UInt8
-            i += 1
-            u >>= 8
-        end
-    end
-    return BAMCIGAR(
-        unsafe,
-        ImmutableMemoryView(mem),
-        x.aln_len,
-        x.ref_len,
-        x.query_len
-    )
-end
+BAMCIGAR(::MutableMemoryView{UInt8}, ::CIGAR)
 
-Base.print(io::IO, x::BAMCIGAR) = (write(io, cigar_view!(UInt8[], x)); nothing)
+@deprecate BAMCIGAR(mem::MutableMemoryView{UInt8}, x::CIGAR) encode!(mem, BAMCIGAR, x)
+
+function Base.print(io::IO, x::BAMCIGAR)
+    v = UInt8[]
+    encode_append!(v, CIGAR, x)
+    write(io, v)
+    return nothing
+end
 
 function try_parse(::Type{BAMCIGAR}, x)::Union{CIGARError, BAMCIGAR}
     mem = ImmutableMemoryView(x)::ImmutableMemoryView{UInt8}