segment.go

// Copyright 2026 Joshua Jones <joshua.jones.software@gmail.com>
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package hl7

import "bytes"

// Segment represents a single HL7 segment (e.g., MSH, PID, OBX).
// It holds a slice into the parent message's byte buffer and scans
// for field boundaries on each access rather than caching parsed results.
type Segment struct {
	raw    []byte
	delims Delimiters
}

// Type returns the 3-character segment identifier (e.g., "MSH", "PID").
// Returns an empty string if the segment raw data is too short.
func (s *Segment) Type() string {
	if len(s.raw) < 3 {
		return ""
	}
	return string(s.raw[0:3])
}

// Field returns the field at the given 1-based index.
// Field(0) returns the segment type as a field.
//
// For MSH segments, field numbering follows the HL7 convention:
//   - Field(1) returns the field separator character itself
//   - Field(2) returns the encoding characters
//   - Field(3+) returns normal fields
//
// Returns an empty Field if the index is out of range.
func (s *Segment) Field(index int) Field {
	if index < 0 || len(s.raw) < 3 {
		return Field{Value: Value{delims: s.delims}}
	}

	// Field 0: segment type.
	if index == 0 {
		return Field{Value: Value{raw: s.raw[0:3], delims: s.delims}}
	}

	if isHeaderSeg(s.raw) {
		return s.mshField(index)
	}
	return s.normalField(index)
}

// isHeaderSeg reports whether raw is an MSH, BHS, or FHS segment.
// All three segment types share the same encoding-character layout:
// position 3 is the field separator and positions 4-7 are the four
// encoding characters. Field numbering follows HL7 convention:
// field 1 = the separator itself, field 2 = encoding chars, field 3+ = normal fields.
func isHeaderSeg(raw []byte) bool {
	if len(raw) < 3 {
		return false
	}
	return (raw[0] == 'M' && raw[1] == 'S' && raw[2] == 'H') ||
		(raw[0] == 'B' && raw[1] == 'H' && raw[2] == 'S') ||
		(raw[0] == 'F' && raw[1] == 'H' && raw[2] == 'S')
}

// mshField handles the MSH segment's special field structure.
func (s *Segment) mshField(index int) Field {
	raw := s.raw

	// Field 1: field separator character.
	if index == 1 {
		if len(raw) < 4 {
			return Field{Value: Value{delims: s.delims}}
		}
		return Field{Value: Value{raw: raw[3:4], delims: s.delims}}
	}

	// Find end of MSH-2 (encoding characters — everything until next field separator).
	if len(raw) < 5 {
		return Field{Value: Value{delims: s.delims}}
	}
	raw = raw[4:]
	encEnd := bytes.IndexByte(raw, s.delims.Field)
	if encEnd == -1 {
		encEnd = len(raw)
	}

	// Field 2: encoding characters.
	if index == 2 {
		return Field{Value: Value{raw: raw[:encEnd], delims: s.delims}}
	}

	// Field 3+: normal fields after encoding chars.
	if encEnd >= len(raw) {
		return Field{Value: Value{delims: s.delims}}
	}
	remaining := raw[encEnd+1:]
	slice := nthSlice(remaining, s.delims.Field, index-3)
	if slice == nil {
		return Field{Value: Value{delims: s.delims}}
	}
	return Field{Value: Value{raw: slice, delims: s.delims}}
}

// normalField handles all non-MSH segments.
func (s *Segment) normalField(index int) Field {
	raw := s.raw
	if len(raw) < 4 || raw[3] != s.delims.Field {
		return Field{Value: Value{delims: s.delims}}
	}
	slice := nthSlice(raw[4:], s.delims.Field, index-1)
	if slice == nil {
		return Field{Value: Value{delims: s.delims}}
	}
	return Field{Value: Value{raw: slice, delims: s.delims}}
}

// FieldCount returns the number of fields, including the segment type at index 0.
func (s *Segment) FieldCount() int {
	raw := s.raw
	if len(raw) < 3 {
		return 0
	}

	if isHeaderSeg(raw) {
		return s.mshFieldCount()
	}
	return s.normalFieldCount()
}

func (s *Segment) mshFieldCount() int {
	raw := s.raw
	n := 1 // Field 0: segment type

	if len(raw) < 4 {
		return n
	}
	n++ // Field 1: separator

	if len(raw) < 5 {
		return n
	}
	n++ // Field 2: encoding chars

	// Find end of encoding chars.
	raw = raw[4:]
	encEnd := bytes.IndexByte(raw, s.delims.Field)
	if encEnd == -1 {
		return n
	}

	// Count remaining fields.
	remaining := raw[encEnd+1:]
	n += countDelimited(remaining, s.delims.Field)
	return n
}

func (s *Segment) normalFieldCount() int {
	raw := s.raw
	n := 1 // Field 0: segment type

	if len(raw) < 4 || raw[3] != s.delims.Field {
		return n
	}

	n += countDelimited(raw[4:], s.delims.Field)
	return n
}

// Raw returns the raw bytes of this segment.
func (s *Segment) Raw() []byte {
	return s.raw
}