Skip to content
Guitar Prometheus

GuitarPrometheus::Util

GuitarPrometheus::Util

Classes

Name
structGuitarPrometheus::Util::MergeResult
Outcome of a merge(...) call.

Functions

Name
juce::FilegetPersistenceRoot()
Returns the root directory where the app persists user data (profiles, preferences, autosaves, exports).
MergeResultmerge(std::vector< SongStructure::Score > sources)
Merge multiple parsed Scores into one runtime Score.
voidwriteAtomic(const juce::File & target, const std::string & contents)
Atomically write contents to target.
std::stringhashHex(const juce::Uuid & uuid, const std::array< std::uint8_t, 8 > & salt)
FNV-1a 32-bit hash of (uuid bytes
std::stringsaltToHex(const std::array< std::uint8_t, 8 > & salt)
Hex-encode an 8-byte salt as a 16-character lowercase string.

Functions Documentation

function getPersistenceRoot

juce::File getPersistenceRoot()

Returns the root directory where the app persists user data (profiles, preferences, autosaves, exports).

On macOS and Linux, the root is ~/Library/Application Support/Guitar Prometheus (macOS) or the platform-equivalent userApplicationDataDirectory child — the install is system-wide, the data is per-user.

On Windows, the root is the directory containing the running executable. Windows builds are distributed as a portable .zip so that extracting the zip anywhere — including a USB drive — produces a self-contained installation that does not touch APPDATA%.

The returned juce::File is the directory; it is created on first access by the caller (via createDirectory()) if it does not exist.

function merge

MergeResult merge(
    std::vector< SongStructure::Score > sources
)

Merge multiple parsed Scores into one runtime Score.

The first score’s divisions, tempoByMeasure, initialTempoBpm, currentScoreTempoBpm, initialTimeSignature, and initialKeySignature are canonical. Parts from later sources are appended in order. Score-level metadata is taken from sources[0] only.

Behaviour:

  • Empty input → single error in errors, no score.
  • Single input → identity (Score returned as-is).
  • Multi-input:
    • If a later score’s divisions differs from the first, emits a warning and still merges (notes from the differing score may misalign timing-wise; that’s the user’s call to manage).
    • If a later score’s initialTimeSignature or initialKeySignature differs, emits a warning.
    • Score-part-id collisions (two scores both having P1) are resolved with a suffix dedupe (P1 → P1_b → P1_c), and a warning lists each collision.

The merged Score is purely runtime — addMusicXmlToProject doesn’t persist the merged-in XML payloads to the .gpproj blob in v1 of this feature (see [ProjectStore.h]’s caveat). F11.6 will add the persistence path via a manifest schema bump.

function writeAtomic

void writeAtomic(
    const juce::File & target,
    const std::string & contents
)

Atomically write contents to target.

Internally writes to target.tmp first, flushes, then renames over target. The parent directory is created if missing. On stream-open failure, no file is written.

function hashHex

std::string hashHex(
    const juce::Uuid & uuid,
    const std::array< std::uint8_t, 8 > & salt
)

FNV-1a 32-bit hash of (uuid bytes || salt bytes), formatted as 6 lowercase hex chars.

Not cryptographic — used only to disambiguate filenames that share the same slugified name. Two profiles with identical names get different hashes because their UUIDs and salts differ.

function saltToHex

std::string saltToHex(
    const std::array< std::uint8_t, 8 > & salt
)

Hex-encode an 8-byte salt as a 16-character lowercase string.

Used in the JSON schema for round-tripping the salt through serialization.

Updated on 2026-05-29 at 07:39:52 +0000