api: support non-traditional key signatures

Sourcecode/include/mx/api/ApiEquality.h

@@ -9,17 +9,12 @@
 #include <map>
 #include <iostream>
 
+// #define MX_DEBUG // shows traces to std::cout
+
 namespace mx
 {
     namespace api
     {
-
-///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-// All of the uglines below this point is mainly to be used in test code.  It is not expected that clients will have need of the //
-// functions defined here.  If you do wish to use the equality operator, you may want to silence the cout's that occur when two  //
-// items are found to be not-equal.  This cout stream was necessary for testing during development.                              //
-///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-
         template <typename T>
         inline bool areVectorsEqual( const std::vector<T>& lhs, const std::vector<T>& rhs )
         {
@@ -72,6 +67,7 @@ namespace mx
             return areSame( lhs, rhs );
         }
 
+#ifdef MX_DEBUG
         inline void streamComparisonUnequalMessage( const char* const inClassName, const char* const inMemberName )
         {
             std::cout << inClassName;
@@ -80,23 +76,30 @@ namespace mx
             std::cout << " members are not equal ";
             std::cout << std::endl;
         }
-
+#endif
+
+#ifdef MX_DEBUG
+    #define MX_SHOW_UNEQUAL( XtheCurrentClassName, XmxapiMemberName ) streamComparisonUnequalMessage( XtheCurrentClassName, XmxapiMemberName );
+#else
+    #define MX_SHOW_UNEQUAL( XtheCurrentClassName, XmxapiMemberName )
+#endif
+
 #define MXAPI_EQUALS_BEGIN( mxapiClassName ) \
         inline bool operator==( const mxapiClassName& lhs, const mxapiClassName& rhs ) \
         { \
             const char* const theCurrentClassName = #mxapiClassName;
-
+            
 #define MXAPI_EQUALS_MEMBER( mxapiMemberName ) \
         if( ! ( lhs.mxapiMemberName == rhs.mxapiMemberName ) ) \
         { \
-            streamComparisonUnequalMessage( theCurrentClassName, #mxapiMemberName ); \
+            MX_SHOW_UNEQUAL( theCurrentClassName, #mxapiMemberName ); \
             return false; \
         }
 
 #define MXAPI_DOUBLES_EQUALS_MEMBER( mxapiMemberName ) \
         if( std::abs( lhs.mxapiMemberName - rhs.mxapiMemberName ) > MX_API_EQUALITY_EPSILON ) \
         { \
-            streamComparisonUnequalMessage( theCurrentClassName, #mxapiMemberName ); \
+            MX_SHOW_UNEQUAL( theCurrentClassName, #mxapiMemberName ); \
             return false; \
         }
 

Sourcecode/include/mx/api/FontData.h

@@ -96,7 +96,7 @@ namespace mx
         MXAPI_EQUALS_MEMBER( weight )
         if( ! areVectorsEqual( lhs.fontFamily, rhs.fontFamily ) )
         {
-            streamComparisonUnequalMessage( "FontData", "fontFamily" );
+            MX_SHOW_UNEQUAL( "FontData", "fontFamily" );
             return false;
         }
         MXAPI_EQUALS_MEMBER( underline )

Sourcecode/include/mx/api/KeyComponent.h

@@ -0,0 +1,42 @@
+// MusicXML Class Library
+// Copyright (c) by Matthew James Briggs
+// Distributed under the MIT License
+
+#pragma once
+#include "mx/api/ApiCommon.h"
+#include "mx/api/PitchData.h"
+
+namespace mx
+{
+    namespace api
+    {
+
+        // KeyComponent is only used for non-traditional key signatures. It facilitates specifying the
+        // exact accidentals that are found in the key signature.
+        struct KeyComponent
+        {
+            // The note name that is to be altered by the key signature.
+            Step step;
+
+            // The amount that notes of this note name should be altered, in semitones.
+            int alter;
+
+            // Additional amount that notes of this note name should be altered, in cents. If alter = 1 and cents = 25.1
+            // then the note is altered by 1.251 semitones in total.
+            double cents;
+
+            // The accidental to display for this note name.
+            Accidental accidental;
+        };
+
+
+        MXAPI_EQUALS_BEGIN( KeyComponent )
+        MXAPI_EQUALS_MEMBER( step )
+        MXAPI_EQUALS_MEMBER( alter )
+        MXAPI_EQUALS_MEMBER( cents )
+        MXAPI_EQUALS_MEMBER( accidental )
+        MXAPI_EQUALS_END;
+
+        MXAPI_NOT_EQUALS_AND_VECTORS( KeyComponent );
+    }
+}

Sourcecode/include/mx/api/KeyData.h

@@ -3,72 +3,101 @@
 // Distributed under the MIT License
 
 #pragma once
+#include "mx/api/KeyComponent.h"
 
 namespace mx
 {
-	namespace api
-	{
+    namespace api
+    {
         enum class KeyMode
         {
-            // a mode value was not provided
-            unspecified,
-
-            // a mode value was provided but
-            // is not supported
-            unsupported,
-
+            unspecified, // a mode value was not provided
+            unsupported, // a mode value was provided but is not supported
             major,
             minor
-
         };
-		struct KeyData
-		{
-			// From MusicXML Specification:
-			// The fifths type represents the number of flats or sharps in a
-			// traditional key signature. Negative numbers are used for flats
-			// and positive numbers for sharps, reflecting the key's
-			// placement within the circle of fifths (hence the type name).
-			int fifths;
 
-			// From MusicXML Specification:
-			// A cancel element indicates that the old key signature should be
-			// cancelled before the new one appears. This will always happen
-			// when changing to C major or A minor and need not be specified
-			// then. The cancel value matches the fifths value of the cancelled
-			// key signature (e.g., a cancel of -2 will provide an explicit
-			// cancellation for changing from B flat major to F major). The
-			// optional location attribute indicates whether the cancellation
-			// appears relative to the new key signature.
-			int cancel;
+        // KeyData represents a key signature. It can be in one of two configurations. Either you specify
+        // 'fifths' and 'mode', or you can create a custom key signature by adding items to the customKey
+        // vector. If anything is found in the customKey vector, then fifths and mode will be ignored.
+        //
+        // Example, a traditional key signature (D Major):
+        // KeyData key;
+        // key.fifths = 2; // (i.e. 2 sharps)
+        // key.mode = KeyMode::major; // (optional)
+        //
+        // Example, a traditional key signature (G Minor):
+        // KeyData key;
+        // key.fifths = -2; // (i.e. 2 flats)
+        // key.mode = KeyMode::minor; // (optional)
+        //
+        // If you want to create a custom time signature, you can do so like this. Here we are creating a
+        // key where C's are sharp and D's are one-quarter-tone sharp. See KeyComponent for details.
+        //
+        // KeyComponent cSharp{ Step::c, 1, 0.0, Accidental::sharp };
+        // KeyComponent dQuarterTone{ Step::d, 0, 50.0, Accidental:quarterSharp };
+        // KeyData key;
+        // key.nonTraditional.push_back( cSharp );
+        // key.nonTraditional.push_back( dQuarterTone );
+        //
+        struct KeyData
+        {
+            // From MusicXML Specification:
+            // The fifths type represents the number of flats or sharps in a
+            // traditional key signature. Negative numbers are used for flats
+            // and positive numbers for sharps, reflecting the key's
+            // placement within the circle of fifths (hence the type name).
+            int fifths;
+
+            // From MusicXML Specification:
+            // A cancel element indicates that the old key signature should be
+            // cancelled before the new one appears. This will always happen
+            // when changing to C major or A minor and need not be specified
+            // then. The cancel value matches the fifths value of the cancelled
+            // key signature (e.g., a cancel of -2 will provide an explicit
+            // cancellation for changing from B flat major to F major). The
+            // optional location attribute indicates whether the cancellation
+            // appears relative to the new key signature.
+            int cancel;
 
+            // Mode specifies whether the key is major or minor. It is optional.
             KeyMode mode;
+
+            // Supports changing the key somewhere other than at the start of a measure.
             int tickTimePosition;
-            
+
             // this value is optional. -1 means unspecified. when value is
             // unspecified it means that the key signature applies to all staves
             // within the part
             int staffIndex;
-
-			// TODO support position data and/or other attribtues
-
+
+            // TODO support position data and/or other attributes
+
+            // Supports the creation of customized, non-traditional key signatures by specifying the exact note
+            // alterations. When custom is non-empty, then fifths and mode are ignored.
+            std::vector<KeyComponent> nonTraditional;
+
             KeyData()
             : fifths{ 0 }
             , cancel{ 0 }
             , mode{ KeyMode::unspecified }
             , tickTimePosition{ 0 }
             , staffIndex{ -1 }
+            , nonTraditional{}
             {
-                
+
             }
-		};
-        
+        };
+
         MXAPI_EQUALS_BEGIN( KeyData )
         MXAPI_EQUALS_MEMBER( fifths )
         MXAPI_EQUALS_MEMBER( cancel )
         MXAPI_EQUALS_MEMBER( mode )
         MXAPI_EQUALS_MEMBER( tickTimePosition )
         MXAPI_EQUALS_MEMBER( staffIndex )
+        MXAPI_EQUALS_MEMBER( nonTraditional )
         MXAPI_EQUALS_END;
+
         MXAPI_NOT_EQUALS_AND_VECTORS( KeyData );
-	}
+    }
 }

Sourcecode/include/mx/api/StaffData.h

@@ -58,7 +58,7 @@ namespace mx
         MXAPI_EQUALS_MEMBER( directions )
         if( !( voicesAreEqual( lhs.voices, rhs.voices ) ) )
         {
-            streamComparisonUnequalMessage( "StaffData", "voices" );
+            MX_SHOW_UNEQUAL( "StaffData", "voices" );
             return false;
         }
         MXAPI_EQUALS_END;

Sourcecode/private/mx/core/elements/KeyAttributes.cpp

@@ -33,7 +33,9 @@ namespace mx
         ,hasFontWeight( false )
         ,hasColor( false )
         ,hasPrintObject( false )
-        {}
+        {
+
+        }
 
 
         bool KeyAttributes::hasValues() const

Sourcecode/private/mx/impl/Converter.cpp

@@ -1804,6 +1804,34 @@ namespace mx
         {
             return findApiItem( kindMap, api::ChordKind::unspecified, value );
         }
-
+
+        mx::core::DecimalType Converter::convertToAlter( int semitones, double cents )
+        {
+            double alter = 0.0;
+            if( semitones != 0 || cents != 0.0 )
+            {
+                double microtones = 0.0;
+                if( cents != 0.0 ) {
+                    microtones = cents / 100.0;
+                }
+                alter = semitones + microtones;
+            }
+            return alter;
+        }
+
+        std::pair<int, double> Converter::convertToSemitonesAndCents( mx::core::DecimalType xmlAlter )
+        {
+            double myCents = 0.0;
+            const auto intAlter = static_cast<int>( xmlAlter );
+            const auto micro = xmlAlter - static_cast<mx::core::DecimalType> ( intAlter );
+            const auto microDistance = std::abs( micro );
+            if( microDistance >= 0.000000000001 )
+            {
+                const auto theCents = micro * 100.0;
+                const auto theNarrowCents = static_cast<decltype(mx::api::PitchData::cents)>( theCents );
+                myCents = theNarrowCents;
+            }
+            return std::make_pair( intAlter, myCents );
+        }
     }
 }

Sourcecode/private/mx/impl/Converter.h

@@ -15,6 +15,7 @@
 #include "mx/core/elements/OrnamentsChoice.h"
 #include "mx/core/elements/TechnicalChoice.h"
 #include "mx/core/Enums.h"
+#include "mx/core/Decimals.h"
 
 #include <map>
 
@@ -25,6 +26,8 @@ namespace mx
         class Converter
         {
         public:
+            // TODO - all of these functions should be static
+
             core::StepEnum convert( api::Step value ) const;
             api::Step convert( core::StepEnum value ) const;
 
@@ -114,7 +117,10 @@ namespace mx
 
             core::KindValue convert( api::ChordKind value ) const;
             api::ChordKind convert( core::KindValue value ) const;
-
+
+            static mx::core::DecimalType convertToAlter( int semitones, double cents );
+            static std::pair<int, double> convertToSemitonesAndCents( mx::core::DecimalType alter );
+
             const static std::map<core::StepEnum, api::Step> stepMap;
             const static std::map<core::NoteTypeValue, api::DurationName> durationMap;
             const static std::map<core::NoteheadValue, api::Notehead> noteheadMap;

Sourcecode/private/mx/impl/MeasureReader.cpp

@@ -454,7 +454,30 @@ namespace mx
 
                 if( keyType == core::KeyChoice::Choice::nonTraditionalKey )
                 {
-                    // TODO - support non-traditional keys
+                    api::KeyData keyData;
+                    const auto& nonTraditionalKeyParts = key.getKeyChoice()->getNonTraditionalKeySet();
+                    for( const auto& nonTraditionalKeyPart : nonTraditionalKeyParts )
+                    {
+                        api::KeyComponent keyComponent{};
+
+                        if( nonTraditionalKeyPart->getHasKeyAccidental() )
+                        {
+                            keyComponent.accidental = myConverter.convert(  nonTraditionalKeyPart->getKeyAccidental()->getValue() );
+                        }
+
+                        const auto alter = nonTraditionalKeyPart->getKeyAlter()->getValue().getValue();
+                        if( alter != 0.0 )
+                        {
+                            const auto semitoneAndCents = Converter::convertToSemitonesAndCents( alter );
+                            keyComponent.alter = semitoneAndCents.first;
+                            keyComponent.cents = semitoneAndCents.second;
+                        }
+
+                        keyComponent.step = myConverter.convert( nonTraditionalKeyPart->getKeyStep()->getValue() );
+                        keyData.nonTraditional.emplace_back( keyComponent );
+                    }
+
+                    myOutMeasureData.keys.emplace_back( std::move( keyData ) );
                     continue;
                 }