Class that provides storage for text. This is to achieve platform-transparent text handling, that can handle text storage regardless of how it's done on the platform (Mac/Window/C-style/Unicode/etc). More...

#include <ff_base.h>

Inheritance diagram for FCString:

Public Member Functions
const char *	ClassName () const override
	Returns the name of the class, for diagnostic purposes. This method MUST be overwritten in each child class.

const PDKFRAMEWORK_CLASSID	GetClassID () const override
	Returns the internal class ID for the PDK Framework class. This is implemented mostly because Lua has problems to resolve the true classes of inherited objects.

	FCString ()
	The constructor. Defaults to an empty string.

	FCString (const char *pszCString)
	Constructor version that takes a C string (Lua string) as argument. The C string can be encoded either in UTF8 or the default Windows codepage. The function tries UTF8 encoding first. If that fails, then it falls back to encoding using the default codepage. On macOS it falls back to MacRoman, but MacRoman is hardly ever used on modern macOS systems.

	FCString (const eUniChar16 *pszCString)
	Constructor version that takes a Unicode 16 string as argument.

	FCString (const _fcStringChar *pszCString)
	Constructor version that takes a the platform UTF16 type as argument.

virtual	~FCString ()
	The destructor. Deletes the string storage as well as the C-string pointer (if any).

	FCString (const FCString &src)
	Copy constructor (required for classes that allocate memory.)

FCString &	operator= (const FCString &src)
	Assignment operator (required for classes that allocate memory.)

void	AppendCharacter (eUniChar32 character)
	Appends a character to the string.

void	AppendString (const FCString *pOtherString)
	Appends another string object to the string.

void	AppendCString (const char *pOtherString)
	Appends a C-style string to the string.

void	AppendLuaString (const char *pOtherString)
	Appends a Lua string to the string. This method supports UTF-8.

void	AppendInteger (int value)
	Appends an integer value (decimal) to the string.

void	AppendFloat (double value)
	Appends an floating-point value to the string.

void	AppendEOL ()
	Appends a system-specific end-of-line string to the to the FCString object.

void	AssureEndingPathDelimiter ()
	Makes sure that the string ends with a path delimiter (backslash or slash, depending on OS). The method will not add any delimiter to empty strings.

bool	EncodeFromMacRoman ()
	Re-encodes the string to true Unicode from MacRoman.

bool	EncodeToMacRoman ()
	Re-encodes the string from true Unicode to faux MacRoman.

bool	SplitAt (int splitpointindex, FCString pFirstString, FCString pSecondString, bool includesplitposchar) const
	Splits a string into 2 substrings at a specific split point character position.

bool	SplitToPathAndFile (FCString pPathPart, FCString pFilePart) const
	Splits a fully qualified file path into path part and file part copies.

void	SetUserPath ()
	Sets the string to the user path on the running system.

void	SetUserOptionsPath ()
	Sets the string to the user options path on the running system.

void	SetPluginsFolderPath ()
	Sets the path string to Finale's root plug-in folder.

void	SetMusicFolderPath ()
	Sets the path string to Finale's music folder.

void	SetLibFolderPath ()
	Sets the path string to Finale's library folder.

void	SetBackupFolderPath ()
	Sets the path string to Finale's backup folder.

void	SetAutoSaveFolderPath ()
	Sets the path string to Finale's auto-save folder.

void	SetTemplateFolderPath ()
	Sets the path string to Finale's template folder.

void	SetTempFolderPath ()
	Sets the path string to Finale's temp folder (for temporary files).

void	SetFontAnnotationFolderPath ()
	Sets the path string to Finale's font annotation folder.

void	SetDocStylesFolderPath ()
	Sets the path string to Finale's document styles folder.

void	SetPercussionTypesFilePath ()
	Sets the full path string to Finale's percussion note types text file. This file should NEVER be modified, only read from it.

void	SetPreferencesFolderPath ()
	Sets the path string to Finale's preference folder.

void	SetRunningLuaFolderPath ()
	Sets the string to the folder for the running script file. The string is cleared if the script is run without a file. Only available for Lua clients.

void	SetRunningLuaFilePath ()
	Sets the string to the folder for the running script file. The string is cleared if the script is run without a file. Only available for Lua clients.

void	Clear ()
	Creates an empty string.

int	Compare (const FCString &value) const
	Compares string against another string.

int	CompareNoCase (const FCString &value) const
	Case insensitive version of Compare.

bool	ContainsString (const FCString &pSubString) const
	Returns true if the substring is found within the string.

bool	ContainsCString (const char *pszSubString) const
	Returns true if the substring is found within the string. C-string version.

bool	ContainsStringFrom (const FCString &pSubString, int startindex) const
	Returns true if the substring is found within the string from a certain position.

bool	ContainsCStringFrom (const char *pszSubString, int startindex) const
	Returns true if the substring is found from a certain position within the string.

int	CalcStringPos (const FCString &subString) const
	Returns the first position where a substring occurs.

int	CalcLastStringPos (const FCString &subString) const
	Returns the last position where a substring occurs.

int	CalcCStringPos (const FCString pSubString, const char pszSubString) const
	Returns the first position where a substring occurs. C-string version.

int	CalcStringPosFrom (const FCString &subString, int startindex) const
	Returns the first position where a substring occurs, from a starting point.

int	CalcCStringPosFrom (const char *pszSubString, int startindex) const
	Returns the first position where a substring occurs, from a starting point. C-string version.

void	ConvertToPascal (Str255 &pascalString)
	Converts the string contents to a Str255 pascal string.

void	_SetCFURLRefPath (CFURLRef cfurl)

bool	ContainsEnigmaTextInsert (bool only_file_info_inserts=true) const
	Returns true if the text block contains a text insert.

FCStrings *	CreateEnigmaComponents () const
	Creates a string collection that consists of the components from an Enigma text command (with correct syntax).

FCStrings *	CreateEnigmaStrings (bool include_non_commands=false) const
	Creates a string collection of every enigma text tag found in the string.

FCFontInfo *	CreateLastFontInfo () const
	Creates a FCFontInfo object with the last font information (based on the Enigma text tags) found in the string.

FCStrings *	CreateParsedStrings (const char *pszSeparators) const
	Creates a collection of strings based on the separator characters. C-style string version.

FCStrings *	CreateRows () const

bool	DeleteCodePointAt (int index)
	Removes the Unicode codepoint at the 0-based index position.

bool	DeleteCodePointsAt (int index, int count)
	Removes a range of Unicode codepoints, starting at the 0-based index position.

bool	DeleteCharacterAt (int index)
	Removes a character at the 0-based index position.

bool	DeleteCharactersAt (int index, int count)
	Removes a range of characters, starting at the 0-based index position.

void	ExtractFileExtension ()
	Removes everything except the file extension part of a file name.

int	FindFirst (const char *pszSubStr) const
	Returns the 0-based index for the first occurence of the substring.

int	FindLast (const char *pszSubStr) const
	Returns the 0-based index for the last occurence of the substring.

int	FormatCStringArgs (const char *fmt, va_list args)
	Formats a string from an args list. Supports either UTF8 or platform encoding.

int	FormatCString (const char *fmt,...)
	Formats a string using the same syntax and manner as the printf() function in C. The version of the method doesn't support Unicode UTF16, but it works with UTF8.

int	FormatString (FCString *fmt,...)
	Formats a string using the same syntax and manner as the printf() function in C. The version of the method supports Unicode on Finale 2012 and later.

void	FormatCharacterNumber (eUniChar32 character)
	Formats a 16-bit character (symbol) number to a string for presentation purposes.

const char *	GetCString () const
	Returns a C-string version of the string.

const char *	GetLuaString () const
	Returns a Lua version of the string in UTF-8 format.

const char *	GetUTF8String () const
	Returns a C-string UTF-8 version of the string.

bool	CopyToUnicodeBuffer (eUniChar16 *pBuffer, int maxbufferlen=0) const
	Copies the string to a 16-bit Unicode buffer. The buffer must be big enough to have room for an ending 0.

void *	GetNSString () const
	Returns a NSString* version of the string (on Cocoa only).

void	SetNSString (void *pNSString)
	Sets the string to a NSString* value.

int	GetInteger (int index=0) const
	Converts the decimal string contents to an integer value.

int	GetHex () const
	Converts the unsigned hexadecimal string to an integer value. The string can only contain valid hexadecimal characters.

double	GetFloat (int index=0) const
	Converts the decimal string contents to a floating point value.

eUniChar16	GetCharacterAt (int index) const
	Returns the character at the index position.

std::pair< eUniChar32, int >	GetCodePointAt (int index) const
	Returns the Unicode codepoint at the index position. If the index position points to the high surrogate, the codepoint returned actually starts at index - 1.

int	GetLength () const
	Returns the length of the string.

const char *	GetEOL () const
	Returns the platform-specific end-of-line character(s) as a C-string.

void	Insert (const char *pszString, int insertindex=0)
	Inserts a C string to the string at a specified index position.

void	InsertString (const FCString *pString, int insertindex=0)
	Inserts a string object to the string at a specified index position.

bool	IsDigit (int index) const
	Returns true if the character at the specified 0-based index position is a digit (0 through 9).

bool	IsAllDigits () const
	Returns true if all characters in the string are digits (0 through 9).

bool	IsNumber () const
	Returns true if the string is a number.

bool	IsEqualCString (const char *pszString) const
	Returns true if the string is identical with the parameter. (C-style string version.)

bool	IsEqual (const char *pszString) const
	Returns true if the string is identical with the parameter.

bool	IsEqualString (const FCString &value) const
	Returns true if the string is identical with the parameter. (FCString string version.)

bool	IsCharacter (int index, eUniChar32 character) const
	Returns true if the character at the index matches the supplied character.

bool	IsCharacters (int index, const char *pChars) const
	Returns true if the character at the index matches any of the supplied character.

bool	IsEmpty () const
	Returns true if the string is empty.

bool	IsWhitespace (int index) const
	Returns true if the character position contains a whitespace.

bool	IsEnigmaCommand () const
	Returns true if the string is an Enigma command.

bool	IsEnigmaFont () const
	Returns true if the string is an Enigma font command.

bool	IsEnigmaFileInfoTitle () const
	Returns true if the string is an "Title" Enigma command.

bool	IsEnigmaFileInfoSubtitle () const
	Returns true if the string is an "Subtitle" Enigma command.

bool	IsEnigmaFileInfoComposer () const
	Returns true if the string is an "Composer" Enigma command.

bool	IsEnigmaFileInfoArranger () const
	Returns true if the string is an "Arranger" Enigma command.

bool	IsEnigmaFileInfoLyricist () const
	Returns true if the string is an "Lyricist" Enigma command.

bool	IsEnigmaFileInfoCopyright () const
	Returns true if the string is an "Copyright" Enigma command.

bool	IsEnigmaTextInsert (bool only_file_info_inserts=true) const
	Returns true if the string is an Enigma text command with a text insert.

bool	LoadResource (int resourceID, HINSTANCE dllinstance=0)
	Windows version. Loads the resource string into the string object.

bool	LoadResource (const char resourceID, const char pszResourceFileName=NULL, const char *pszTableName=NULL)
	Mac version. Loads the resource string into the string object.

bool	MakeSubString (int startindex, int substringlength, FCString *pDestinationString)
	Creates a substring from the string.

bool	ReplaceCategoryFonts (FCCategoryDef *pCategoryDef, int fontmode, bool replacefonttag)
	Parses the raw string and changes all text tags according to a category definition.

void	SetCString (const char *pszBuffer, int maxchars=-1)
	Sets the string, using a C-string version of the string.

void	SetLuaString (const char *pszBuffer)
	Sets the string, using a Lua string version of the string (as UTF-8).

void	SetUTF8String (const char *pszBuffer)
	Sets the string, using a UTF8 C-style string.

void	SetCharacterAt (int index, eUniChar16 newcharacter)
	Sets the character at the index position.

void	SetUnicodeString (const eUniChar16 *pChar, int maxchars=-1)
	Sets the string by using a 16-bit Unicode buffer as input parameter.

void	SetInteger (int i)
	Sets the string to an integer.

void	SetHex (int number, int bitwidth)
	Sets the string to a lower-case hexadecimal number.

void	SetFloat (double f)
	Sets the string to a floating point value.

void	SetMeasurement (double value, twobyte unit)
	Sets the string to an EVPU measurement value, formatted to a specific unit.

double	GetMeasurement (_ENUMCODE(MEASUREMENTUNITS) _LUACODE(twobyte) unit) const
	Converts the string to an EVPU measurement value, based on a specific unit.

void	SetString (const FCString *pString)
	Copies a string.

FCString *	CreateCopy ()
	Creates a copy of the string object on the heap.

bool	SetCharacterUpperCase (int index)
	Sets a specific character to upper case.

void	SetCurrentTime ()
	Set the string to the current time in hh:mm:ss format.

bool	Replace (const char pszSource, const char pszReplacement)
	Replaces all occurrences of a source pattern with a replacement string.

bool	EndsWith (const char *pszString) const
	Returns true if the string ends with the parameter string.

bool	EndsWithString (const FCString *pString) const
	Returns true if the string ends with the parameter string.

bool	StartsWith (const char *pszString) const
	Returns true if the string starts with the parameter string.

bool	StartsWithString (const FCString *pString) const
	Returns true if the string starts with the parameter string.

void	ToUnicode (eUniChar16 *pBuffer, int maxsize) const
	Copies the string to a 16-bit Unicode string buffer.

void	ToLowerCase ()
	Transforms the string to lower case.

void	ToUpperCase ()
	Transforms the string to upper case.

bool	TrimEnigmaTags ()
	Removes all Enigma tag information from a string, leaving only the actual text.

bool	TrimEnigmaFontTags ()
	Removes all Enigma font tags from a string, leaving only the actual text and text insert tags, etc.

void	TrimWhitespace ()
	Trims whitespace at both ends of the string.

void	TrimLinefeed ()
	Trims linefeed characters at both ends of the string.

bool	TruncateAt (int newlength)
	Truncates the string at the indicated position.

bool	TruncateEnd (int count)
	Truncates the end of the string by a specific number of characters.

void	TruncateWidth (int maxlength, int prefixchars)
	Truncates the string by removing the middle part and inserting '...' instead.

void	DebugDump () override
	Outputs the class data/information for debugging purposes.

Public Member Functions inherited from __FCBase
virtual	~__FCBase ()
	Virtual destructor, so all inherited classes get the virtual destructor.

void	DebugMsgInt (const char *pszPrefixText, int i)
	Creates a simple Message Box for debug purposes. The text appears with the extra digit (in decimal presentation) appearing afterwards.

void	DebugMsgHex (const char *pszPrefixText, int i)
	Creates a simple Message Box for debug purposes. The text appears with the extra digit (as a hexadecimal number) appearing afterwards.

void	DebugMsgString (const char pszPrefixText, const char thestring)
	Creates a simple Message Box for debug purposes. The text appears with the extra string appearing afterwards.

void	DebugMsg (const char *pszMsg)
	Creates a simple Message Box for debug purposes with just one text string.

void	DebugOutMenuInfo (FCUI *pUI, int menuixd_horiz, int menuixd_vert) const
	Outputs the menu command info for debugging purposes.

int	DebugOutFormat (const char *fmt,...)
	Outputs debug text using C style "printf" syntax.

virtual void	DebugDataDump ()
	Outputs a memory dump of the data block in the object for debugging purposes.

virtual void	DebugDataByteArrayDump ()
	Outputs a memory dump of the data block in the object for debugging purposes, as a C++ byte array.

void	Set16BitFlag (FLAG_16 *flag, FLAG_16 flagbits, bool state)
	Sets a 16 bit flag.

void	Set32BitFlag (FLAG_32 *flag, FLAG_32 flagbits, bool state)
	Sets/resets a 32 bit flag, by using a bit mask.

bool	GetBitFlag (FLAG_32 flag, FLAG_32 flagbits) const
	Gets a state from flag bits. Returns true if any bit in the mask is set.

int	GetBitCount (FLAG_32 flag)
	Returns the total number of set bits in a 32-bit unsigned int.

void	SetSpecific32Bit (FLAG_32 *flag, int bitnumber, bool state)
	Sets/resets a single bit in a 32 bit flag, by specifying one specific bit.

void	SetUserData (void *pData)
	Sets the user data attached to the instance of an object.

void	SetUserData2 (void *pData)
	Sets the additional user data attached to the instance of an object.

void *	GetUserData () const
	Gets the user data attached to the instance of an object.

void *	GetUserData2 () const
	Gets the additional user data attached to the instance of an object.

virtual bool	IsIdentical (const __FCBase *pCompareObject) const
	Returns true if the data in the passed object is considered to be identical to the current object, otherwise false.

void	StoreXML_String (tinyxml2::XMLElement pParentNode, const char pszElementName, FCString *pStringValue)
	Helper function to store FCString objects in the XML file.

void	StoreXML_Integer (tinyxml2::XMLElement pParentNode, const char pszElementName, int value)
	Helper function to store integer objects in the XML file.

void	StoreXML_Bool (tinyxml2::XMLElement pParentNode, const char pszElementName, bool value)
	Helper function to store boolean objects in the XML file.

void	StoreXML_StringAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, FCString *pStringValue)
	Helper function to store FCString objects in the XML file, as an attribute to a node.

void	StoreXML_IntegerAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, int value)
	Helper function to store integer objects in the XML file, as an attribute to a node.

void	StoreXML_BoolAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, bool value)
	Helper function to store boolean objects in the XML file, as an attribute to a node.

void	StoreXML_FloatAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, float value)
	Helper function to store floating point objects in the XML file, as an attribute to a node.

bool	ReadXML_String (tinyxml2::XMLElement pParentNode, const char pszElementName, FCString *pStringValue)
	Helper method to read FCString objects from the XML file.

bool	ReadXML_Integer (tinyxml2::XMLElement pParentNode, const char pszElementName, int *pValue)
	Helper method to read integer objects from the XML file.

bool	ReadXML_Bool (tinyxml2::XMLElement pParentNode, const char pszElementName, bool *pValue)
	Helper method to read boolean objects from the XML file.

bool	ReadXML_StringAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, FCString *pStringValue)
	Helper method to read FCString objects from the XML file, as an attribute to a node.

bool	ReadXML_IntegerAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, int *pValue)
	Helper method to read integer objects from the XML file, as an attribute to a node.

bool	ReadXML_BoolAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, bool *pValue)
	Helper method to read boolean objects from the XML file, as an attribute to a node.

bool	ReadXML_FloatAttribute (tinyxml2::XMLElement pNode, const char pszAttributeName, float *pValue)
	Helper method to read floating point objects from the XML file, as an attribute to a node.

Static Public Member Functions
static int	LoadIntegerResource (int resourceID, int defaultValue, HINSTANCE dllinstance=0)
	Windows version. Static method that loads an integer from a resource string.

static int	LoadIntegerResource (const char resourceID, int defaultValue, const char pszResourceFileName=NULL, const char *pszTableName=NULL)
	Mac version. Static method that loads an integer from a resource string.

Static Public Member Functions inherited from __FCBase
static void	DebugOutPtr (const char pszPrefixText, void ptr)
	Static method that outputs a line for debugging purposes. The prefix text appears with the extra ptr (in hexadeximal representation) appearing afterwards.

static void	DebugOutInt (const char *pszPrefixText, int i)
	Static method that outputs a line for debugging purposes. The text appears with the extra digit (in decimal presentation) appearing afterwards.

static void	DebugOutFloat (const char *pszPrefixText, double f)
	Static method that outputs a line for debugging purposes. The text appears with the extra float value appearing afterwards.

static void	DebugOutTag (const char *pszPrefixText, EXTAG extag)
	Static method that outputs a line for debugging purposes. The text appears with the EXTAG (in text) appearing afterwards.

static void	DebugOutHex (const char *pszPrefixText, int i)
	Static method that outputs a line for debugging purposes. The text appears with the extra digit (in hexadecimal presentation) appearing afterwards.

static void	DebugOutBin (const char *pszPrefixText, int i)
	Static method that outputs a line for debugging purposes. The text appears with the extra digit (in binary presentation) appearing afterwards.

static void	DebugOutString (const char pszPrefixText, const char thestring)
	Static method that outputs a line for debugging purposes (C string version). The text appears with the extra string appearing afterwards.

static void	DebugOutString (const char pszPrefixText, FCString pString)
	Static method that outputs a line for debugging purposes (FCString version). The text appears with the extra string appearing afterwards.

static void	DebugOutBool (const char *pszPrefixText, bool state)
	Static method that outputs a line for debugging purposes. The boolean state appears afterwards as either "TRUE" or "FALSE".

static void	DebugOutBlock (const void *pBuffer, int startoffset, int size)
	Static method that outputs a memory block for debugging purposes. Eight bytes per line will appear (as hex digits) until the whole memory block is dumped.

static void	DebugOutByteArrayBlock (const void *pBuffer, int startoffset, int size)
	Static method that outputs a memory block for debugging purposes. Eight bytes per line will appear (as hex digits) as a C++ onebyte array, until the whole memory block is dumped.

static void	DebugOut (const char *pszLine)
	Static method to output a line of text for debugging purposes.

Additional Inherited Members
Public Types inherited from __FCBase
enum	PDKFRAMEWORK_CLASSID { FCID_UNKNOWN = 0 , FCID_ACCIDENTALMOD , FCID_ACTIVELYRIC , FCID_ALLOTMENT , FCID_ARTICULATION , FCID_ARTICULATIONDEF , FCID_BACKWARDREPEAT , FCID_BASELINE , FCID_BEAMMOD , FCID_BEATCHARTELEMENT , FCID_BOOKMARK , FCID_BROKENBEAMMOD , FCID_CATEGORYDEF , FCID_CELLCLEFCHANGE , FCID_CELLFRAMEHOLD , FCID_CELLGRAPHIC , FCID_CELLTEXT , FCID_CENTERSMARTSHAPE , FCID_CHORD , FCID_CHORDPREFS , FCID_CHORDSUFFIXELEMENT , FCID_CHORUSSYLLABLE , FCID_CLEFDEF , FCID_COMPOSITETIMESIGBOTTOMELEMENT , FCID_COMPOSITETIMESIGTOPELEMENT , FCID_CROSSSTAFFMOD , FCID_CUSTOMSMARTLINEDEF , FCID_CUSTOMSTEMMOD , FCID_DISTANCEPREFS , FCID_DOTMOD , FCID_ENCLOSURE , FCID_ENDINGREPEAT , FCID_ENIGMATEXTSTYLE , FCID_ENTRYALTERMOD , FCID_EXECUTABLESHAPEDEF , FCID_EXPRESSION , FCID_FONTINFO , FCID_FONTPREFS , FCID_FREEZESYSTEM , FCID_FRETBOARDSTYLEDEF , FCID_FRETBOARDSTYLEDEFS , FCID_FRETBOARDGROUPDEF , FCID_FRETBOARDGROUPDEFS , FCID_FRETINSTRUMENTDEF , FCID_GENERALPREFS , FCID_GRIDSGUIDESPREFS , FCID_GROUP , FCID_GROUPNAMEPOSITIONPREFS , FCID_HUMANPLAYBACKPREFS , FCID_INDEPENDENTCELLDETAIL , FCID_INSTRUMENTDEF , FCID_INSTRUMENTPLAYBACKDATA , FCID_KEYMODEDEF , FCID_KEYSIGNATURE , FCID_LAYERPREFS , FCID_LYRICSBASELINE , FCID_LYRICSPREFS , FCID_MEASURE , FCID_MEASURENUMBERREGION , FCID_METATOOLASSIGNMENT , FCID_MIDIEXPRESSION , FCID_MISCDOCPREFS , FCID_MULTIMEASUREREST , FCID_MULTIMEASURERESTPREFS , FCID_MULTISTAFFINSTRUMENT , FCID_MULTISTAFFINSTRUMENTS , FCID_MUSICCHARACTERPREFS , FCID_MUSICSPACINGPREFS , FCID_NUMBER , FCID_NOTEHEADMOD , FCID_OTHERINCI , FCID_PERCUSSIONLAYOUTNOTE , FCID_PERCUSSIONSTAFF , FCID_PERFORMANCEMOD , FCID_PAGE , FCID_PAGEFORMATPREFS , FCID_PAGEGRAPHIC , FCID_PAGETEXT , FCID_PART , FCID_PARTEXTRACTPREFS , FCID_PARTSCOPEPREFS , FCID_PARTSTAFFVOICING , FCID_PERCUSSIONNOTEMOD , FCID_PIANOBRACEPREFS , FCID_PLAYBACKPREFS , FCID_RAWTEXT , FCID_REPEATPREFS , FCID_SECONDARYBEAMBREAKMOD , FCID_BEAMEXTENSIONMOD , FCID_SECTIONSYLLABLE , FCID_SEPARATEMEASURENUMBER , FCID_SEPARATEPLACEMENT , FCID_SHAPEDEF , FCID_SHAPEEXPRESSIONDEF , FCID_SLURCONTOURPREFS , FCID_SIZEPREFS , FCID_SMARTSHAPE , FCID_SMARTSHAPEENTRYMARK , FCID_SMARTSHAPEMEASUREMARK , FCID_SMARTSHAPEPREFS , FCID_STAFF , FCID_STAFFLIST , FCID_STAFFNAMEPOSITION , FCID_STAFFNAMEPOSITIONPREFS , FCID_STAFFSTYLEASSIGN , FCID_STAFFSTYLEDEF , FCID_STAFFSYSTEM , FCID_STEMCONNECTIONTABLE , FCID_STEMMOD , FCID_STRING , FCID_SYLLABLEENTRYMOD , FCID_SYSTEMSTAFF , FCID_TABLATURENOTEMOD , FCID_TEMPOELEMENT , FCID_TEXTBLOCK , FCID_TEXTEXPRESSIONDEF , FCID_TEXTREPEAT , FCID_TEXTREPEATDEF , FCID_TIEMOD , FCID_TIEPREFS , FCID_TIECONTOURPREFS , FCID_TIEPLACEMENTPREFS , FCID_TIMESIGNATURE , FCID_TUPLET , FCID_TUPLETPREFS , FCID_VERSESYLLABLE }
	Constants for the GetClassID method. More...

enum	MEASUREMENTUNITS { MEASUREMENTUNIT_DEFAULT = UNIT_DEFAULT , MEASUREMENTUNIT_EVPUS = UNIT_EVPUS , MEASUREMENTUNIT_INCHES = UNIT_INCHES , MEASUREMENTUNIT_CENTIMETERS = UNIT_CENTS , MEASUREMENTUNIT_POINTS = UNIT_POINTS , MEASUREMENTUNIT_PICAS = UNIT_PICAS , MEASUREMENTUNIT_SPACES = UNIT_SPACES , MEASUREMENTUNIT_MILLIMETERS = 100 }
	Constants for Finale's standard measurement units. More...

Protected Member Functions inherited from __FCBase
	__FCBase ()
	The constructor.

Detailed Description

Class that provides storage for text. This is to achieve platform-transparent text handling, that can handle text storage regardless of how it's done on the platform (Mac/Window/C-style/Unicode/etc).

When running on Finale 2012 and above, the FCString stores the strings as UTF16 internally.

For Finale 2011 and below, the FCString is handled as a 8-bit arrays (meaning that any foreign characters would be platform specific).

06 September 2013: a major redesign of this class to make it work better with Lua. No overloaded methods anymore (Append, Contains, etc). Instead, a suffix with the type is used ("AppendCString" etc).

Constructor & Destructor Documentation

◆ FCString() [1/2]

FCString::FCString ( )

inline

The constructor. Defaults to an empty string.

Lua-supported.

◆ FCString() [2/2]

FCString::FCString ( const char * pszCString )

inline

Constructor version that takes a C string (Lua string) as argument. The C string can be encoded either in UTF8 or the default Windows codepage. The function tries UTF8 encoding first. If that fails, then it falls back to encoding using the default codepage. On macOS it falls back to MacRoman, but MacRoman is hardly ever used on modern macOS systems.

Lua-supported (0.68).

Member Function Documentation

◆ _SetCFURLRefPath()

void FCString::_SetCFURLRefPath ( CFURLRef cfurl )

For internal use only. Converts a CFURLRef to a file path.

◆ AppendCharacter()

void FCString::AppendCharacter ( eUniChar32 character )

Appends a character to the string.

Starting with version 0.73, AppendCharacter breaks Unicode code points greater than 16-bits into their surrogate pairs and appends them both. Values below 0x10000 are added without examination (as before). This means you can add half a surrogate pair without adding the other half, but then you will end up with a malformed string.

Lua-supported.

◆ AppendCString()

void FCString::AppendCString ( const char * pOtherString )

Appends a C-style string to the string.

Lua callers should use AppendLuaString() instead.

◆ AppendEOL()

void FCString::AppendEOL ( )

inline

Appends a system-specific end-of-line string to the to the FCString object.

Lua-supported.

◆ AppendFloat()

void FCString::AppendFloat ( double value )

Appends an floating-point value to the string.

Lua-supported.

◆ AppendInteger()

void FCString::AppendInteger ( int value )

Appends an integer value (decimal) to the string.

Lua-supported.

◆ AppendLuaString()

void FCString::AppendLuaString ( const char * pOtherString )

Appends a Lua string to the string. This method supports UTF-8.

Lua-supported

Parameters

pOtherString Pointer to a UTF-8-encoded Lua string character buffer. If it is NULL, nothing will be appended.

◆ AppendString()

void FCString::AppendString ( const FCString * pOtherString )

Appends another string object to the string.

Lua-supported.

◆ AssureEndingPathDelimiter()

void FCString::AssureEndingPathDelimiter ( )

inline

Makes sure that the string ends with a path delimiter (backslash or slash, depending on OS). The method will not add any delimiter to empty strings.

Lua-supported.

◆ CalcCStringPos()

int FCString::CalcCStringPos	(	const FCString *	pSubString,
		const char *	pszSubString ) const

inline

Returns the first position where a substring occurs. C-string version.

This function is not guaranteed to work for non-ASCII characters.

Deprecated: use CalcStringPos instead.

Lua-supported (as "CalcLuaStringPos").

Parameters

pSubString	not used. Left in for backwards compatibility.
pszSubString	the C string or Lua string version of the substring.

Returns: -1 if the substring isn't found. Otherwise, the 0-based position where the substring is found.

◆ CalcCStringPosFrom()

int FCString::CalcCStringPosFrom	(	const char *	pszSubString,
		int	startindex ) const

inline

Returns the first position where a substring occurs, from a starting point. C-string version.

This function is not guaranteed to work for non-ASCII characters.

Deprecated: use CalcStringPosFrom instead.

Lua-supported (as "CalcLuaStringPosFrom").

Returns: -1 if the substring isn't found. Otherwise, the 0-based position where the substring is found.

◆ CalcLastStringPos()

int FCString::CalcLastStringPos ( const FCString & subString ) const

inline

Returns the last position where a substring occurs.

Lua-supported (0.76)

Returns: -1 if the substring isn't found. Otherwise, the 0-based position where the substring is found.

◆ CalcStringPos()

int FCString::CalcStringPos ( const FCString & subString ) const

inline

Returns the first position where a substring occurs.

Lua-supported.

Returns: -1 if the substring isn't found. Otherwise, the 0-based position where the substring is found.

◆ CalcStringPosFrom()

int FCString::CalcStringPosFrom	(	const FCString &	subString,
		int	startindex ) const

inline

Returns the first position where a substring occurs, from a starting point.

Lua-supported.

Parameters

subString	the substring to search for.
startindex	the 0-based starting index from which to search.

Returns: -1 if the substring isn't found. Otherwise, the 0-based position where the substring is found.

◆ ClassName()

const char * FCString::ClassName ( ) const

inlineoverridevirtual

Returns the name of the class, for diagnostic purposes. This method MUST be overwritten in each child class.

Lua-supported.

Implements __FCBase.

◆ Clear()

void FCString::Clear ( )

inline

Creates an empty string.

Lua-supported.

◆ Compare()

int FCString::Compare ( const FCString & value ) const

inline

Compares string against another string.

Lua-supported.

Returns: Less than 0 if the string is less than the compared string. 0 if the string is equal to the compared string. Above 0 if the compared string is less.

◆ CompareNoCase()

int FCString::CompareNoCase ( const FCString & value ) const

inline

Case insensitive version of Compare.

Lua-supported.

◆ ContainsCString()

bool FCString::ContainsCString ( const char * pszSubString ) const

inline

Returns true if the substring is found within the string. C-string version.

This function does not work correctly with Unicode code points above 255.

Deprecated: Use ContainsString instead.

Lua-supported (as "ContainsLuaString").

◆ ContainsCStringFrom()

bool FCString::ContainsCStringFrom	(	const char *	pszSubString,
		int	startindex ) const

inline

Returns true if the substring is found from a certain position within the string.

This function does not work correctly with Unicode code points above 255.

Deprecated: Use ContainsStringFrom instead.

Lua-supported (as "ContainsLuaStringFrom").

◆ ContainsEnigmaTextInsert()

bool FCString::ContainsEnigmaTextInsert ( bool only_file_info_inserts = true ) const

Returns true if the text block contains a text insert.

Lua-supported.

Parameters

only_file_info_inserts If set, the method will only return true if a text insert from the "File Info" is found in the string.

◆ ContainsString()

bool FCString::ContainsString ( const FCString & pSubString ) const

Returns true if the substring is found within the string.

Lua-supported.

◆ ContainsStringFrom()

bool FCString::ContainsStringFrom	(	const FCString &	pSubString,
		int	startindex ) const

Returns true if the substring is found within the string from a certain position.

Lua-supported.

◆ CopyToUnicodeBuffer()

bool FCString::CopyToUnicodeBuffer	(	eUniChar16 *	pBuffer,
		int	maxbufferlen = 0 ) const

Copies the string to a 16-bit Unicode buffer. The buffer must be big enough to have room for an ending 0.

Parameters

pBuffer	Pointer to the 16-bit character buffer.
maxbufferlen	Max number of 16-bit elements in the input buffer. 0 (the default) means the string is copied to the buffer without any range checking.

Returns: True on success. False on parameter errors.

◆ CreateCopy()

FCString * FCString::CreateCopy ( )

Creates a copy of the string object on the heap.

It's the caller's responsibility to delete it from the heap after use.

◆ CreateEnigmaComponents()

FCStrings * FCString::CreateEnigmaComponents ( ) const

Creates a string collection that consists of the components from an Enigma text command (with correct syntax).

It's the callers responsibility to make sure that the string really is a fully qualified Enigma string command.

Lua-supported.

Returns

NULL if the string isn't an Enigma string command. Otherwise, the string collection arranged like this:

The command (without the '^') is stored at index 0 of the string collection.
The parameters are stored at index 1 and above. The returned collection must be deleted from the heap after use.

◆ CreateEnigmaStrings()

FCStrings * FCString::CreateEnigmaStrings ( bool include_non_commands = false ) const

Creates a string collection of every enigma text tag found in the string.

The first Enigma tag found is at index position 0, the next at position 1, and so on.

Lua-supported.

Parameters

include_non_commands If set, the actual text in the raw string is also added as separate strings in the collection.

Returns: Pointer to the created string collection. This must be deleted from the heap after use.

◆ CreateLastFontInfo()

FCFontInfo * FCString::CreateLastFontInfo ( ) const

Creates a FCFontInfo object with the last font information (based on the Enigma text tags) found in the string.

Lua-supported.

Returns: Pointer to the created FCFontInfo object. This must be deleted from the heap after use.

◆ CreateParsedStrings()

FCStrings * FCString::CreateParsedStrings ( const char * pszSeparators ) const

Creates a collection of strings based on the separator characters. C-style string version.

The separators are never in the substrings. Each substring contains the text between separators.

Lua-supported.

Parameters

pszSeparators A string containing all the separators.

Returns: A pointer to a FCStrings object, containing all the substrings. The pointer must be disposed by the caller after use.

◆ CreateRows()

FCStrings * FCString::CreateRows ( ) const

brief Creates a collection of strings based on the newline or line feed characters.

This method support any combination of the 3 common line break methods.

Lua-supported.

Returns
A pointer to a FCStrings object, containing all the substrings. The pointer must be disposed by the caller after use.

◆ DebugDump()

void FCString::DebugDump ( )

inlineoverridevirtual

Outputs the class data/information for debugging purposes.

Accessible if PDK_FRAMEWORK_DEBUG is defined.

When child class inherit this method to output the contents of its own members, it should call the parent before providing its own output.

Reimplemented from __FCBase.

◆ DeleteCharacterAt()

bool FCString::DeleteCharacterAt ( int index )

inline

Removes a character at the 0-based index position.

This function is not safe for UTF-16 surrogate pairs. External callers should use DeleteCodePointAt instead.

Lua-supported.

Parameters

index The 0-based position in the string. -1 means the last character in the string.

Returns: True on success.

◆ DeleteCharactersAt()

bool FCString::DeleteCharactersAt	(	int	index,
		int	count )

Removes a range of characters, starting at the 0-based index position.

This function is not safe for UTF-16 surrogate pairs. External callers should use DeleteCodePointsAt instead.

Lua-supported.

Parameters

index	The 0-based character index position in the string.
count	Number of characters to remove.

Returns: True on success.

◆ DeleteCodePointAt()

bool FCString::DeleteCodePointAt ( int index )

inline

Removes the Unicode codepoint at the 0-based index position.

This function always removes the complete codepoint, even if index points to a low surrogate.

Lua-supported (0.73).

Parameters

index The 0-based position in the string. -1 means the last character in the string.

Returns: True on success. False if the string is malformed UTF16 or the index is out of range.

◆ DeleteCodePointsAt()

bool FCString::DeleteCodePointsAt	(	int	index,
		int	count )

Removes a range of Unicode codepoints, starting at the 0-based index position.

This function always removes complete codepoints, even if index points to a low surrogate and/or the count does not encompass a complete surrogate pair.

Lua-supported (0.73).

Parameters

index	The 0-based character index position in the string.
count	Number of characters to remove.

Returns: True on success. False if the string is malformed UTF16 or the index is out of range.

◆ EncodeFromMacRoman()

bool FCString::EncodeFromMacRoman ( )

Re-encodes the string to true Unicode from MacRoman.

Finale stores certain characters and strings internally as faux UTF-16 strings where the UTF-16 codepoints are actually MacRoman character codes. This if for legacy music fonts (not SMuFL) and other symbol fonts contained in MacSymbolFonts.txt. This function re-encodes the string to true Unicode. You would need to call this before displaying the string in an FCControl set to the font, for example. Otherwise the control displays incorrect glyphs for codes larger than 127.

Remarks: These legacy fonts are used on both Windows and Mac operating systems. "MacRoman" refers to the character encoding, not the operating system. Both platforms require the use of EncodeFromMacRoman and EncodeToMacRoman when displaying

Lua-supported (0.72).

Returns: true if it was re-encoded. false if there was an error.

◆ EncodeToMacRoman()

bool FCString::EncodeToMacRoman ( )

Re-encodes the string from true Unicode to faux MacRoman.

See comments at EncodeFromMacRoman. This method reverses the effect of EncodeFromMacRoman.

You would need call this after retrieving the string from an FCControl set to the font, for example. It would then be encoded in the faux Unicode format that Finale stores in the document for legacy music fonts and other MacRoman symbol fonts. You would need to do this on both Mac and Windows.

Returns: true if it was re-encoded. false if there was an error.

◆ EndsWith()

bool FCString::EndsWith ( const char * pszString ) const

Returns true if the string ends with the parameter string.

C string version

Lua-supported.

◆ EndsWithString()

bool FCString::EndsWithString ( const FCString * pString ) const

Returns true if the string ends with the parameter string.

FCString string version

Lua-supported (0.64).

◆ ExtractFileExtension()

void FCString::ExtractFileExtension ( )

inline

Removes everything except the file extension part of a file name.

If there is no file extension, an empty name is returned.

Lua-supported.

◆ FindFirst()

int FCString::FindFirst ( const char * pszSubStr ) const

inline

Returns the 0-based index for the first occurence of the substring.

Warning: This legacy function does not work for non-ASCII input characters. Use CalcStringPos instead.

Lua-supported.

Parameters

pszSubStr The substring in C-string format.

Returns: -1 if not found. Otherwise, the 0-based index.

◆ FindLast()

int FCString::FindLast ( const char * pszSubStr ) const

inline

Returns the 0-based index for the last occurence of the substring.

Warning: This legacy function does not work for non-ASCII input characters. Use CalcLastStringPos instead.

Lua-supported.

Parameters

pszSubStr The substring in C-string format.

Returns: -1 if not found. Otherwise, the 0-based index.

◆ FormatCharacterNumber()

void FCString::FormatCharacterNumber ( eUniChar32 character )

Formats a 16-bit character (symbol) number to a string for presentation purposes.

For character numbers between 0 and 255, the string will become a decimal text version of the character number. For characters above 255, the Unicode U+FFFF hexadecimal format will be used.

Lua-supported.

Parameters

character The number of the character. As of 0.73, all Unicode codepoints are supported (0..0x10FFFF).

◆ FormatCString()

int FCString::FormatCString	(	const char *	fmt,
			... )

Formats a string using the same syntax and manner as the printf() function in C. The version of the method doesn't support Unicode UTF16, but it works with UTF8.

Requires the PDK_FRAMEWORK_FORMAT define.

Parameters

fmt	A format string (C style). Additional parameters follow according to syntax of the format string.

◆ FormatCStringArgs()

int FCString::FormatCStringArgs	(	const char *	fmt,
		va_list	args )

Formats a string from an args list. Supports either UTF8 or platform encoding.

Due to a discrepancy between Standard C++ and Windows in the treatment of s and S, it is better to always do arguments with 8-bit chars, so no similar function is provided for FCString or UTF16.

Requires the PDK_FRAMEWORK_FORMAT define.

Parameters

fmt	A format string (C style). Additional parameters follow according to syntax of the format string.
args	A va_list with the args passed from another function with a ... args list

◆ FormatString()

int FCString::FormatString	(	FCString *	fmt,
			... )

Formats a string using the same syntax and manner as the printf() function in C. The version of the method supports Unicode on Finale 2012 and later.

The behavior of this function is highly platform-dependent due to a difference in how Windows and the C++ standard treat 's' and 'S'.

Requires the PDK_FRAMEWORK_FORMAT define.

Parameters

fmt	A format string (using a FCString object). Additional parameters follow according to syntax of the format string.

◆ GetCharacterAt()

eUniChar16 FCString::GetCharacterAt ( int index ) const

Returns the character at the index position.

Warning: FCString represents characters internally as UTF-16-encoded code points. If the string includes characters outside the Basic Multilingual Plane (BMP), this function could potentially return a partial character. Lua clients should use particular care with this function, because converting from indices on UTF-8 strings to indices on UTF-16 strings is not straightforward. A much safer approach for Lua would be to load the FCString into a Lua string and then use the built-in utf8 Lua library to process the string.

This is a legacy function. External callers should use GetCodePointAt.

Lua-supported.

Parameters

index The 0-based index position in the string. -1 means the last character in the string.

Returns: The character found at the index position. 0 if the index position is out of range.

◆ GetClassID()

const PDKFRAMEWORK_CLASSID FCString::GetClassID ( ) const

inlineoverridevirtual

Returns the internal class ID for the PDK Framework class. This is implemented mostly because Lua has problems to resolve the true classes of inherited objects.

This method must be overwritten by all child classes.

Lua-supported (also read-only property) (0.55).

Reimplemented from __FCBase.

◆ GetCodePointAt()

std::pair< eUniChar32, int > FCString::GetCodePointAt ( int index ) const

Returns the Unicode codepoint at the index position. If the index position points to the high surrogate, the codepoint returned actually starts at index - 1.

External callers should use this function instead of GetCharacterAt wherever possible.

Lua-supported (0.73)

Parameters

index The 0-based index position in the string. -1 means the last character in the string.

Returns: first: the Unicode codepoint (valued from 0 to 0x10FFFF); second: the next 0-based codepoint index in the string.

◆ GetCString()

const char * FCString::GetCString ( ) const

Returns a C-string version of the string.

Returns: Pointer to a C-string version of the string. This pointer is permanent until GetCString is called again, or until the string object is destroyed.

◆ GetEOL()

const char * FCString::GetEOL ( ) const

Returns the platform-specific end-of-line character(s) as a C-string.

On Windows, it returns carriage return+new line. On OS X, it returns new line.

Lua-supported (also as read-only property)

◆ GetFloat()

double FCString::GetFloat ( int index = 0 ) const

Converts the decimal string contents to a floating point value.

This method supports both "." and "," as the decimal point.

Lua-supported.

Parameters

index Optional index start position in the string.

Returns: The floating point value. 0 if the string isn't a decimal digit string or if the index is incorrect.

◆ GetHex()

int FCString::GetHex ( ) const

Converts the unsigned hexadecimal string to an integer value. The string can only contain valid hexadecimal characters.

Lua-supported.

Returns: -1 if the string contains illegal characters. Otherwise a non-negative value.

◆ GetInteger()

int FCString::GetInteger ( int index = 0 ) const

Converts the decimal string contents to an integer value.

Lua-supported.

Parameters

index Optional index start position in the string. (As of version 0.73, it is optional on Lua as well.)

Returns: The integer value. 0 if the string isn't a decimal digit string or if the index is incorrect.

◆ GetLength()

int FCString::GetLength ( ) const

inline

Returns the length of the string.

Lua-supported.

◆ GetLuaString()

const char * FCString::GetLuaString ( ) const

Returns a Lua version of the string in UTF-8 format.

Lua-supported (also as property).

Returns: Pointer to a Lua version of the string in UTF-8 format. This pointer is permanent until GetLuaString is called again, or until the string object is destroyed.

◆ GetMeasurement()

double FCString::GetMeasurement ( _ENUMCODE(MEASUREMENTUNITS) _LUACODE(twobyte) unit ) const

Converts the string to an EVPU measurement value, based on a specific unit.

In C++, PDK_FRAMEWORK_PREFS must be defined to enable this method.

Lua-supported.

Parameters

unit	Any of the MEASUREMENTUNIT_ constants, such as MEASUREMENTUNIT_DEFAULT.

Returns: 0 on error. Otherwise, the value.

◆ GetNSString()

void * FCString::GetNSString ( ) const

Returns a NSString* version of the string (on Cocoa only).

The returned NSString* object should NOT be released - it's retained/released with the object.

Each time this method is referenced, a new object is created and the old object is released.

◆ Insert()

void FCString::Insert	(	const char *	pszString,
		int	insertindex = 0 )

Inserts a C string to the string at a specified index position.

Deprecated: Use InsertString instead.

Lua-supported.

Parameters

pszString	C string to insert.
insertindex	0-based position where the string should be inserted.

◆ InsertString()

void FCString::InsertString	(	const FCString *	pString,
		int	insertindex = 0 )

Inserts a string object to the string at a specified index position.

Beginning with version 0.73, this function is safe for UTF-16. If insertindex splits a surrogate pair, the input string is inserted at the next Unicode character boundary after insertindex.

Lua-supported.

Parameters

pString	String object to insert.
insertindex	0-based position where the string should be inserted.

◆ IsAllDigits()

bool FCString::IsAllDigits ( ) const

Returns true if all characters in the string are digits (0 through 9).

Lua-supported.

◆ IsCharacter()

bool FCString::IsCharacter	(	int	index,
		eUniChar32	character ) const

Returns true if the character at the index matches the supplied character.

Lua-supported.

Parameters

index	The 0-based index to the position in the string. This method is "index safe", so if the index is out of range false will be returned.
character	The character to check for match. As of version 0.73, this value can be any Unicode code point from 0..0x10FFFF

Returns: True if the character match at the position. False if the character doesn't match, or if the index is out of range.

◆ IsCharacters()

bool FCString::IsCharacters	(	int	index,
		const char *	pChars ) const

Returns true if the character at the index matches any of the supplied character.

Lua-supported.

Parameters

index	The 0-based index to the position in the string. This method is "index safe", so if the index is out of range false will be returned.
pChars	The pointer to the C-style string with characters to check for match.

Returns: True if any of the characters match at the position. False if the characters don't match, or if the index is out of range.

◆ IsDigit()

bool FCString::IsDigit ( int index ) const

Returns true if the character at the specified 0-based index position is a digit (0 through 9).

Lua-supported.

Parameters

index The 0-based index. -1 means last character in string.

◆ IsEmpty()

bool FCString::IsEmpty ( ) const

inline

Returns true if the string is empty.

Lua-supported.

◆ IsEnigmaCommand()

bool FCString::IsEnigmaCommand ( ) const

inline

Returns true if the string is an Enigma command.

Lua-supported.

◆ IsEnigmaFileInfoArranger()

bool FCString::IsEnigmaFileInfoArranger ( ) const

Returns true if the string is an "Arranger" Enigma command.

Lua-supported.

◆ IsEnigmaFileInfoComposer()

bool FCString::IsEnigmaFileInfoComposer ( ) const

Returns true if the string is an "Composer" Enigma command.

Lua-supported.

◆ IsEnigmaFileInfoCopyright()

bool FCString::IsEnigmaFileInfoCopyright ( ) const

Returns true if the string is an "Copyright" Enigma command.

Lua-supported.

◆ IsEnigmaFileInfoLyricist()

bool FCString::IsEnigmaFileInfoLyricist ( ) const

Returns true if the string is an "Lyricist" Enigma command.

Lua-supported.

◆ IsEnigmaFileInfoSubtitle()

bool FCString::IsEnigmaFileInfoSubtitle ( ) const

Returns true if the string is an "Subtitle" Enigma command.

Lua-supported.

◆ IsEnigmaFileInfoTitle()

bool FCString::IsEnigmaFileInfoTitle ( ) const

Returns true if the string is an "Title" Enigma command.

Lua-supported.

◆ IsEnigmaFont()

bool FCString::IsEnigmaFont ( ) const

Returns true if the string is an Enigma font command.

Lua-supported.

◆ IsEnigmaTextInsert()

bool FCString::IsEnigmaTextInsert ( bool only_file_info_inserts = true ) const

Returns true if the string is an Enigma text command with a text insert.

Lua-supported.

◆ IsEqual()

bool FCString::IsEqual ( const char * pszString ) const

inline

Returns true if the string is identical with the parameter.

As of version 0.73, you should pass UTF8-encoded strings to this function.

Lua-supported.

◆ IsEqualCString()

bool FCString::IsEqualCString ( const char * pszString ) const

Returns true if the string is identical with the parameter. (C-style string version.)

Deprecated: Use IsEqual or IsEqualString instead.

◆ IsEqualString()

bool FCString::IsEqualString ( const FCString & value ) const

inline

Returns true if the string is identical with the parameter. (FCString string version.)

Lua-supported.

◆ IsNumber()

bool FCString::IsNumber ( ) const

Returns true if the string is a number.

The syntax requirements are:

String might start with a negative minus at the first position
String might consist of one decimal dot
The rest of the string must be digits

Lua-supported.

Returns: Empty strings returns false. Otherwise true, if the number syntax is correct.

◆ IsWhitespace()

bool FCString::IsWhitespace ( int index ) const

Returns true if the character position contains a whitespace.

Lua-supported.

Returns: False on error (if index is out of range) or if the index position contains a non-whitespace.

◆ LoadIntegerResource() [1/2]

static int FCString::LoadIntegerResource	(	const char *	resourceID,
		int	defaultValue,
		const char *	pszResourceFileName = NULL,
		const char *	pszTableName = NULL )

static

Mac version. Static method that loads an integer from a resource string.

Parameters

resourceID	The localization string in the .strings file.
defaultValue	The value to return if the resource is not found is not convertible to an integer, or has a value of zero.
pszResourceFileName	The optional C string pointer to the resource file name. This defaults to NULL, which means that the previous resource should be used. The first call to this method must contain a valid string for the bundle ID of the plug-in, or whichever bundle contains the resource.
pszTableName	The optional table name within the bundle, which is the .strings file without extension. This defaults to NULL, which means the table name that has been set in earlier calls will be used.

Returns: True if the resource was correctly loaded. If the resource string wasn't loaded, the string will contain "Resource String Error".

◆ LoadIntegerResource() [2/2]

int FCString::LoadIntegerResource	(	int	resourceID,
		int	defaultValue,
		HINSTANCE	dllinstance = 0 )

static

Windows version. Static method that loads an integer from a resource string.

Parameters

resourceID	The resource number.
defaultValue	The value to return if the resource is not found is not convertible to an integer, or has a value of zero.
dllinstance	The DLL instance handle to the plug-in (where the resources are located).

Returns: True if the resource was correctly loaded. If the resource string wasn't loaded, the string will contain "Resource String Error".

◆ LoadResource() [1/2]

bool FCString::LoadResource	(	const char *	resourceID,
		const char *	pszResourceFileName = NULL,
		const char *	pszTableName = NULL )

Mac version. Loads the resource string into the string object.

Parameters

resourceID	The localization string in the .strings file.
pszResourceFileName	The optional C string pointer to the resource file name. This defaults to NULL, which means that the previous resource should be used. The first call to this method must contain a valid string for the bundle ID of the plug-in, or whichever bundle contains the resource.
pszTableName	The optional table name within the bundle, which is the .strings file without extension. This defaults to NULL, which means the table name that has been set in earlier calls will be used.

Returns: True if the resource was correctly loaded. If the resource string wasn't loaded, the string will contain "Resource String Error".

◆ LoadResource() [2/2]

bool FCString::LoadResource	(	int	resourceID,
		HINSTANCE	dllinstance = 0 )

Windows version. Loads the resource string into the string object.

Parameters

resourceID	The resource number.
dllinstance	The DLL instance handle to the plug-in (where the resources are located).

Returns: True if the resource was correctly loaded. If the resource string wasn't loaded, the string will contain "Resource String Error".

◆ MakeSubString()

bool FCString::MakeSubString	(	int	startindex,
		int	substringlength,
		FCString *	pDestinationString )

Creates a substring from the string.

Remarks: FCString represents characters internally as UTF-16-encoded code points. If the string includes characters outside the Basic Multilingual Plane (BMP), this function extends the range implied by startindex and substringlength on either end as need to include both surrogate pairs of code points outside the BMP. That means the length of the output string could be greater than substringlength.

Warning: Lua clients should use particular care with this function, because converting from indices on UTF-8 strings to indices on UTF-16 strings is not straightforward. An alternative approach for Lua would be to load the FCString into a Lua string and then use the built-in utf8 Lua library to process the string. The approach you choose should be dictated by the specific requirments of your program.

Lua-supported.

Parameters

startindex	The 0-based index where the string should start.
substringlength	The length. If the length extends beyond the source string, the substring will end at that point.
pDestinationString	The destination string where the result will be put. It can be the same as the source object.

Returns: True on success. False on bad index or malformed UTF-16 encoding.

◆ Replace()

bool FCString::Replace	(	const char *	pszSource,
		const char *	pszReplacement )

Replaces all occurrences of a source pattern with a replacement string.

As of version 0.73, the source and replacement strings should be UTF8-encoded, and the function supports source and replacement strings that contain any Unicode code points.

Lua-supported.

Parameters

pszSource	The source string in C-string format.
pszReplacement	The replacement in C-string format.

Returns: Returns true if replacements were made.

◆ ReplaceCategoryFonts()

bool FCString::ReplaceCategoryFonts	(	FCCategoryDef *	pCategoryDef,
		int	fontmode,
		bool	replacefonttag )

Parses the raw string and changes all text tags according to a category definition.

The category tags are changed according to this:

^font(Font0,0) tags are changed to the category's music font.
^fontTxt tags are changed to the category's text font.
^fontMus tags are changed to the category's music font.
^fontNum tags are changed to the category's number font.

The tags are case sensitive.

The PDK_FRAMEWORK_ENIGMASTRINGS define must be declared for this method to compile.

Lua-supported.

Parameters

pCategoryDef	Pointer to the category definition object.
fontmode	Any of the CATEGORYMODE_ constants, found in the FCCategoryDef class. If set to anything else than CATEGORYMODE_NONE, the fonts ^font tag will be replaced with the font of the category type.
replacefonttag	Only used if the fontmode parameter is set to to something other than CATEGORYMODE_NONE. If true, the ^font tag will be replaced with category's Enigma tag (such as ^fontMus, ^fontTxt, ^fontNum). In false, the ^font tag will still be used.

Returns: True if the string object has been changed. False if no changes were made. Please note that if the category object doesn't support a required font style, false will be returned.

◆ SetAutoSaveFolderPath()

void FCString::SetAutoSaveFolderPath ( )

inline

Sets the path string to Finale's auto-save folder.

On the Mac, the string is in POSIX format.

Lua-supported.

◆ SetBackupFolderPath()

void FCString::SetBackupFolderPath ( )

inline

Sets the path string to Finale's backup folder.

On the Mac, the string is in POSIX format.

Lua-supported.

◆ SetCharacterAt()

void FCString::SetCharacterAt	(	int	index,
		eUniChar16	newcharacter )

Sets the character at the index position.

Warning: FCString represents characters internally as UTF-16-encoded code points. If the string includes characters outside the Basic Multilingual Plane (BMP), this function could corrupt the encoding. Lua clients should use particular care with this function, because converting from indices on UTF-8 strings to indices on UTF-16 strings is not straightforward. A much safer approach for Lua would be to load the FCString into a Lua string and then use the built-in utf8 Lua library to process the string.; InsertString and (as of 0.73) AppendCharacter are both safe for modifying strings containing Unicode code points outside the BMP. SetCharacterAt is not safe.

Lua-supported.

Parameters

index	The 0-based index position in the string.
newcharacter	The character to e put at the index position.

◆ SetCharacterUpperCase()

bool FCString::SetCharacterUpperCase ( int index )

Sets a specific character to upper case.

When running on Finale 2012 and above, this method supports Unicode.

Lua-supported.

Parameters

index The 0-based index within the string.

◆ SetCString()

void FCString::SetCString	(	const char *	pszBuffer,
		int	maxchars = -1 )

Sets the string, using a C-string version of the string.

Parameters

pszBuffer	Pointer to a C-string character buffer. If it's NULL, an empty string will be created.
maxchars	Maximum number of characters. The default is -1, meaning a NULL-terminated string of any length.

◆ SetCurrentTime()

void FCString::SetCurrentTime ( )

inline

Set the string to the current time in hh:mm:ss format.

Lua-supported.

◆ SetDocStylesFolderPath()

void FCString::SetDocStylesFolderPath ( )

inline

Sets the path string to Finale's document styles folder.

On the Mac, the string is in POSIX format.

Lua-supported.

◆ SetFontAnnotationFolderPath()

void FCString::SetFontAnnotationFolderPath ( )

inline

Sets the path string to Finale's font annotation folder.

On the Mac, the string is in POSIX format.

Lua-supported.

◆ SetHex()

void FCString::SetHex	(	int	number,
		int	bitwidth )

Sets the string to a lower-case hexadecimal number.

Lua-supported.

Parameters

number	The number that should be converted to a hexadeximal value.
bitwidth	The bit width of output string. The values 8, 16, 32, 64 are valid as bit width specifiers. Use 0 to not pad the number to a specified bit width.

◆ SetInteger()

void FCString::SetInteger ( int i )

Sets the string to an integer.

Lua-supported.

◆ SetLibFolderPath()

void FCString::SetLibFolderPath ( )

inline

Sets the path string to Finale's library folder.

On the Mac, the string is in POSIX format.

Lua-supported.

◆ SetLuaString()

void FCString::SetLuaString ( const char * pszBuffer )

inline

Sets the string, using a Lua string version of the string (as UTF-8).

Lua-supported (also as property).

Parameters

pszBuffer Pointer to a UTF-8 Lua string character buffer. If it's NULL, an empty string will be created.

◆ SetMeasurement()

void FCString::SetMeasurement	(	double	value,
		twobyte	unit )

Sets the string to an EVPU measurement value, formatted to a specific unit.

In C++, PDK_FRAMEWORK_PREFS must be defined to enable this method.

Lua-supported.

Parameters

value	The value in EVPUs. The measurement can be using decimals.
unit	Any of the MEASUREMENTUNIT_ constants, such as MEASUREMENTUNIT_DEFAULT.

◆ SetMusicFolderPath()

void FCString::SetMusicFolderPath ( )

inline

Sets the path string to Finale's music folder.

On the Mac, the string is in POSIX format.

Lua-supported.

◆ SetPercussionTypesFilePath()

void FCString::SetPercussionTypesFilePath ( )

inline

Sets the full path string to Finale's percussion note types text file. This file should NEVER be modified, only read from it.

On the Mac, the file path string is in POSIX format.

Lua-supported.

◆ SetPluginsFolderPath()

void FCString::SetPluginsFolderPath ( )

inline

Sets the path string to Finale's root plug-in folder.

On the Mac, the string is in POSIX format.

Lua-supported.

◆ SetPreferencesFolderPath()

void FCString::SetPreferencesFolderPath ( )

inline

Sets the path string to Finale's preference folder.

On the Mac, the string is in POSIX format.

Lua-supported.

◆ SetRunningLuaFilePath()

void FCString::SetRunningLuaFilePath ( )

Sets the string to the folder for the running script file. The string is cleared if the script is run without a file. Only available for Lua clients.

Please note that this method always sets to the main script file. Calling the method from any sub-scripts (using "require" or similar) will still point to the main script file.

It is recommended to use finenv.RunningLuaFilePath() instead with RGP Lua rather than this function. However, as of version 0.66, this function is fully compatible with RGP Lua, and you can use it safely with scripts that need to be compatible with both RGP Lua and JW Lua.

Lua-supported.

◆ SetRunningLuaFolderPath()

void FCString::SetRunningLuaFolderPath ( )

Sets the string to the folder for the running script file. The string is cleared if the script is run without a file. Only available for Lua clients.

It is recommended to use finenv.RunningLuaFolderPath() with RGP Lua rather than this function. However, as of version 0.66, this function is fully compatible with RGP Lua, and you can use it safely with scripts that need to be compatible with both RGP Lua and JW Lua.

Lua-supported.

◆ SetString()

void FCString::SetString ( const FCString * pString )

Copies a string.

Lua-supported.

Parameters

pString Another string (of the FCString class).

◆ SetTempFolderPath()

void FCString::SetTempFolderPath ( )

inline

Sets the path string to Finale's temp folder (for temporary files).

On the Mac, the string is in POSIX format.

Lua-supported.

◆ SetTemplateFolderPath()

void FCString::SetTemplateFolderPath ( )

inline

Sets the path string to Finale's template folder.

On the Mac, the string is in POSIX format.

Lua-supported.

◆ SetUnicodeString()

void FCString::SetUnicodeString	(	const eUniChar16 *	pChar,
		int	maxchars = -1 )

Sets the string by using a 16-bit Unicode buffer as input parameter.

Parameters

[in]	pChar	The Unicode buffer to copy from.
[in]	maxchars	The maximum characters to copy. -1 (the default) means that it's NULL-terminated of any length.

◆ SetUserOptionsPath()

void FCString::SetUserOptionsPath ( )

Sets the string to the user options path on the running system.

On Windows, this typically is Username/Roaming.
On OSX, it's usually ~/Library/Preferences.

Lua-supported.

◆ SetUserPath()

void FCString::SetUserPath ( )

Sets the string to the user path on the running system.

Lua-supported (0.68).

◆ SplitAt()

bool FCString::SplitAt	(	int	splitpointindex,
		FCString *	pFirstString,
		FCString *	pSecondString,
		bool	includesplitposchar ) const

inline

Splits a string into 2 substrings at a specific split point character position.

Lua-supported.

Parameters

splitpointindex	The 0-based index position where the split should be. This cannot be at a position that extends beyond the string length. If this value is -1, the first string will be empty and the second will equal the contents of the source string.
pFirstString	Pointer to the FCString object that should contain the first substring, before the splitpoint. Can be NULL if the substring isn't needed. It cannot be identical to the calling object, if both substring objects are used. Also, it can't identical to the second string.
pSecondString	Pointer to the FCString object that should contain the first substring, after the splitpoint. Can be NULL if it isn't needed. It cannot be identical to the calling object, if both substring objects are used. Also, it can't identical to the first string.
includesplitposchar	true - include the character at the split position as the ending character of the first substring. false - don't include the character at the split position.

Returns: True on success. False on invalid splitpointindex.

◆ SplitToPathAndFile()

bool FCString::SplitToPathAndFile	(	FCString *	pPathPart,
		FCString *	pFilePart ) const

inline

Splits a fully qualified file path into path part and file part copies.

On the Mac, this has to be a POSIX string.

Lua-supported.

Parameters

pPathPart	Pointer to the object that should contain the path. Can be NULL if it isn't needed.
pFilePart	Pointer to the object that should contain the path. Can be NULL if it isn't needed.

Returns: true on success

◆ StartsWith()

bool FCString::StartsWith ( const char * pszString ) const

Returns true if the string starts with the parameter string.

C string version (which is the "default" version in this case).

Lua-supported.

◆ StartsWithString()

bool FCString::StartsWithString ( const FCString * pString ) const

Returns true if the string starts with the parameter string.

FCString string version

Lua-supported.

◆ ToLowerCase()

void FCString::ToLowerCase ( )

Transforms the string to lower case.

When running on Finale 2012 and above, this method supports Unicode.

Lua-supported.

◆ ToUpperCase()

void FCString::ToUpperCase ( )

Transforms the string to upper case.

When running on Finale 2012 and above, this method supports Unicode.

Lua-supported.

◆ TrimEnigmaFontTags()

bool FCString::TrimEnigmaFontTags ( )

Removes all Enigma font tags from a string, leaving only the actual text and text insert tags, etc.

These tags are removed:

^font
^Font
^fontMus
^fontTxt
^fontNum
^nfx
^size

Lua-supported.

Returns: True if any tags were removed. False if the string was untouched.

◆ TrimEnigmaTags()

bool FCString::TrimEnigmaTags ( )

Removes all Enigma tag information from a string, leaving only the actual text.

Lua-supported.

Returns: True if any tags were removed. False if the string was untouched.

◆ TrimLinefeed()

void FCString::TrimLinefeed ( )

Trims linefeed characters at both ends of the string.

Both CR and LF are trimmed. Other whitespace is not trimmed.

Lua-supported.

◆ TrimWhitespace()

void FCString::TrimWhitespace ( )

Trims whitespace at both ends of the string.

Space, Tab, CR and LF are trimmed

Lua-supported.

◆ TruncateAt()

bool FCString::TruncateAt ( int newlength )

inline

Truncates the string at the indicated position.

Lua-supported.

Parameters

[in] newlength The new length of the string.

Returns: True on success. False if the string length already is small enough or newlength is invalid

◆ TruncateEnd()

bool FCString::TruncateEnd ( int count )

inline

Truncates the end of the string by a specific number of characters.

Lua-supported.

Parameters

[in] count The number of characters that should be removed from the end of the string.

Returns: True on success. False on parameter error, or of the string is too short to be fully truncated.

◆ TruncateWidth()

void FCString::TruncateWidth	(	int	maxlength,
		int	prefixchars )

inline

Truncates the string by removing the middle part and inserting '...' instead.

Lua-supported.

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ FCString() [1/2]

◆ FCString() [2/2]

Member Function Documentation

◆ _SetCFURLRefPath()

◆ AppendCharacter()

◆ AppendCString()

◆ AppendEOL()

◆ AppendFloat()

◆ AppendInteger()

◆ AppendLuaString()

◆ AppendString()

◆ AssureEndingPathDelimiter()

◆ CalcCStringPos()

◆ CalcCStringPosFrom()

◆ CalcLastStringPos()

◆ CalcStringPos()

◆ CalcStringPosFrom()

◆ ClassName()

◆ Clear()

◆ Compare()

◆ CompareNoCase()

◆ ContainsCString()

◆ ContainsCStringFrom()

◆ ContainsEnigmaTextInsert()

◆ ContainsString()

◆ ContainsStringFrom()

◆ CopyToUnicodeBuffer()

◆ CreateCopy()

◆ CreateEnigmaComponents()

◆ CreateEnigmaStrings()

◆ CreateLastFontInfo()

◆ CreateParsedStrings()

◆ CreateRows()

◆ DebugDump()

◆ DeleteCharacterAt()

◆ DeleteCharactersAt()

◆ DeleteCodePointAt()

◆ DeleteCodePointsAt()

◆ EncodeFromMacRoman()

◆ EncodeToMacRoman()

◆ EndsWith()

◆ EndsWithString()

◆ ExtractFileExtension()

◆ FindFirst()

◆ FindLast()

◆ FormatCharacterNumber()

◆ FormatCString()

◆ FormatCStringArgs()

◆ FormatString()

◆ GetCharacterAt()

◆ GetClassID()

◆ GetCodePointAt()

◆ GetCString()

◆ GetEOL()

◆ GetFloat()

◆ GetHex()

◆ GetInteger()

◆ GetLength()

◆ GetLuaString()

◆ GetMeasurement()

◆ GetNSString()

◆ Insert()

◆ InsertString()

◆ IsAllDigits()

◆ IsCharacter()

◆ IsCharacters()

◆ IsDigit()

◆ IsEmpty()

◆ IsEnigmaCommand()

◆ IsEnigmaFileInfoArranger()

◆ IsEnigmaFileInfoComposer()

◆ IsEnigmaFileInfoCopyright()

◆ IsEnigmaFileInfoLyricist()

◆ IsEnigmaFileInfoSubtitle()

◆ IsEnigmaFileInfoTitle()