Here are examples of how to access data in a Humdrum score using the
humlib classes:
[Close all]
[Open all]
Reading/Writing
Read Humdrum data from a file, string or istream.
```cpp
HumdrumFile infile;
infile.read(char* filename);
infile.read(string filename);
```
To read content from a char* or string:
```cpp
infile.parse(stringstream content);
infile.parse(istream content);
infile.read(std::cin);
infile.parse(char* content);
infile.parse(string content);
```
See also the tutorial and the
reference manual for more details
about reading Humdrum data.
Data access
Access a particular token.
Access the token in the second field of the fourth line (`12e` in
the above example). This can be done in two ways: either address
the HumdrumLine by the [] operator of HumdrumFile and then the data
files with
HumdrumLine::token, or access
the HumdrumToken directly
from the
HumdrumFile::token function
directly from the
HumdrumFile class,
giving the line and field index as arguments.
```cpp
infile[3].token(1); // 12e
infile.token(3, 1); // 12e
```
example data
Get token string contents.
HumdrumTokens inherit from std::string, so the text of the token
can be accessed in several ways:
```cpp
(std::string)infile.token(3, 1); // "12e"
infile.token(3, 1).c_str(); // "12e"
```
example data
Get starting token in track/spine.
Get the first token in the second spine/track (second `**kern`
token on the first line):
```cpp
infile.getTrackStart(2);
```
example data
Note that this will return a pointer rather than a reference to the token.
Structural information
Total number of HumdrumLines in a HumdrumFile.
```cpp
infile.getLineCount(); // 12
```
example data
Total number of token fields on a HumdrumLine.
```cpp
infile[3].getTokenCount(); // 2
infile[3].getFieldCount(); // 2
```
example data
Get the track number for a token
```cpp
infile[3].getTrack(1); // 2 = second track in file.
```
example data
The "1" is the field number for the second token on the 4th line,
which is in the second track of the file.
Get the sub-track number for a token.
```cpp
infile[3].getSubtrack(1); // 0
```
In this case the spine has not split, so the sub-track assignment
is 0. If there were a spine split, then the sub-track count would
start at 1 for the first token on the line in a track, the next
token in the spine would be sub-track 2, and so on.
example data
Get the number of tokens which following next in track/spine.
Ask the starting token how many tokens precede/follow the starting
token in the second spine:
```cpp
HumdrumToken* tok = infile.getTrackStart(2);
tok->getNextTokenCount(); // 1 token following in the spine
tok->getPreviousTokenCount(); // 0 tokens preceding in the spine
tok->getNextToken(); // returns pointer to `*M3/4`, using default value of 0 for argument.
tok->getPreviousToken(); // returns NULL
```
example data
The HumdrumToken::getNextTokenCount() function will return 0 for
the last token in a spine/track (which always must be the characters
`*-` (start-minus) which is the data terminator token.
Timing information
Token durations
To access the parsed duration of the token, use the
HumdrumToken::getDuration function. The return value of getDuration()
is a "HumNum" which is a rational number, or fraction, consisting
of an integer numerator and denominator. The HumNum::getFloat()
function will return the duration as a double:
```cpp
infile.token(3, 1).getDuration(); // 1/3 for "12e"
infile.token(3, 1).getDuration().getFloat(); // 0.3333 for "12e"
```
example data
HumdrumLines also possess duration
```cpp
infile[4].getDuration(); // 1/6 (1/6th of a quarter note)
infile[4].getDuration().getFloat(); // 0.166667
```
example data
HumdrumFiles also possess duration.
```cpp
infile.getDuration(); // 3 (one measure of 3/4)
```
example data
Ticks per quarter note
When converting Humdrum files into MIDI, MuseData, MusicXML or
SKINI, the function
HumdrumFileBase::tpq (ticks per
quarter note) will return the minimum number of fractional time
units necessary to describe all rhythms in the file as integer durations.
```cpp
infile.tpq(); // 6 = minimum time unit is a triplet 16th note
```
example data
In the case of the musical example further above, the smallest
duration is a triplet eighth note, but the minimum time unit between
both parts is a triplet sixteenth note when considering the
polyrhythmic interaction between the parts.
Token/line/score durations in ticks per quarter note.
Durations can be expressed in ticks by giving the tpq value as an
argument to the duration functions:
```cpp
int tpq = infile.tpq(); // 6 ticks per quarter note
infile.token(3, 1).getDuration(tpq).toInteger(); // 2 ticks for a triplet 8th note
infile[3].getDuration(tpq).toInteger(); // 1 tick for a triplet 16th note
infile.getDuration(tpq).toInteger(); // 18 ticks for 3 quarter notes
```
example data