obitools4/autodoc/docmd/pkg/obiseq/join.md

obiseq Package: Sequence Concatenation via .Join()

The BioSequence.Join() method enables semantic concatenation of two biological sequences (e.g., DNA, RNA, or protein strings).

• Signature:

  func (sequence *BioSequence) Join(seq2 *BioSequence, inplace bool) *BioSequence
  

• Purpose:
  Combines the current sequence (sequence) with a second one (seq2), returning a new or modified BioSequence.

• Parameters:

  • seq2: The sequence to append. Must be a valid *BioSequence.
  • inplace: Boolean flag: if true, modifies the receiver in-place; otherwise, operates on a copy.

• Semantics:

  • If inplace == false, the method first creates a deep copy of the original sequence to avoid side effects.
  • It then appends seq2.Sequence() (the underlying string/byte representation) to the target sequence using an internal .Write() method.
  • The final concatenated result is returned as a *BioSequence.

• Behavioral Guarantees:

  • Pure operation: When inplace = false, the original sequences remain unaltered.
  • Chaining-friendly: Returns a pointer, enabling method chaining (e.g., seq.Join(a, false).Join(b, true)).

• Use Cases:

  • Building multi-domain proteins or gene fusions.
  • Merging fragments from sequencing reads.
  • Constructing synthetic constructs in silico.

• Assumptions:

  • BioSequence.Sequence() returns a valid string/byte slice.
  • .Write(...) handles appending correctly (e.g., no validation of biological compatibility — e.g., frame shifts are not checked).

This method supports flexible, functional-style sequence manipulation while preserving memory safety via optional in-place mutation.