19.5 Location accessors

Accessor function: Marpa_Earleme marpa_r_current_earleme (Marpa_Recognizer r)

Successful iff input has started. If input has not started, returns soft failure.

Return value: On success, the current earleme, which is always non-negative. On soft failure, -1. Never returns a hard failure.

Accessor function: Marpa_Earleme marpa_r_earleme ( Marpa_Recognizer r, Marpa_Earley_Set_ID set_id)

On success, returns the earleme of the Earley set with ID set_id. The ID of an Earley set ID is also called its ordinal. In the default, token-stream model, Earley set ID and earleme are always equal, but this is not the case in other input models.

Hard fails if there is no Earley set whose ID is set_id. This hard failure is fully recoverable. If set_id was negative, the error code of the hard failure is MARPA_ERR_INVALID_LOCATION. If set_id is greater than the ordinal of the latest Earley set, the error code of the hard failure is MARPA_ERR_NO_EARLEY_SET_AT_LOCATION.

Techniques for performing the inverse operation (conversion of an earleme to an Earley set ID) are described in the section on advanced input models. See Converting earleme to Earley set ID.

Return value: On success, the earleme corresponding to Earley set set_id, which is always non-negative. On hard failure, -2. The hard failures with error codes MARPA_ERR_INVALID_LOCATION and MARPA_ERR_NO_EARLEY_SET_AT_LOCATION are fully recoverable.

Accessor function: int marpa_r_earley_set_value ( Marpa_Recognizer r, Marpa_Earley_Set_ID earley_set)

On success, returns the “integer value” of earley_set. For more about the integer value of an Earley set, see marpa_r_earley_set_values().

Return value: On success, returns the the integer value of earley_set, and sets the error code to MARPA_ERR_NONE. On hard failure, returns -2, and sets the error code to the error code of the hard failure, which will never be MARPA_ERR_NONE. Note that -2 is a valid “integer value” for an Earley set, so that when -2 is returned, the error code is the only way to distinguish success from failure. The error code can be determined using marpa_g_error(). See marpa_g_error().

Mutator function: int marpa_r_earley_set_values ( Marpa_Recognizer r, Marpa_Earley_Set_ID earley_set, int* p_value, void** p_pvalue )

On success, does the following:

• If p_value is non-zero, sets the location pointed to by p_value to the integer value of the Earley set with ID earley_set.
• If p_pvalue is non-zero, sets the location pointed to by p_pvalue to the pointer value of the Earley set with ID earley_set.

The “value” and “pointer” of an Earley set are an arbitrary integer and an arbitrary pointer. Libmarpa never examines them and the application is free to use them for its own purposes. In an application with a codepoint-per-earleme input model, for example, the integer value of the Earley set can used to store the current codepoint. In a traditional token-per-earleme input model, the integer and pointer values could be used to track the string value of the token – the pointer could point to the start of the string, and the integer could indicate its length. See The codepoint-per-earleme model.

The Earley set integer value defaults to -1, and the pointer value defaults to NULL. The Earley set value and pointer can be set using the marpa_r_latest_earley_set_values_set() method. See marpa_r_latest_earley_set_values_set().

Return value: On success, returns a non-negative integer. On hard failure, returns -2.

Accessor function: unsigned int marpa_r_furthest_earleme (Marpa_Recognizer r)

Return value: The furthest earleme. Always succeeds.

Accessor function: Marpa_Earley_Set_ID marpa_r_latest_earley_set (Marpa_Recognizer r)

Returns the Earley set ID of the latest Earley set. The ID of an Earley set ID is also called its ordinal. Applications that want the value of the latest earleme can convert this value using the marpa_r_earleme() method. See marpa_r_earleme().

Return value: The ID of the latest Earley set. Always succeeds.

Mutator function: int marpa_r_latest_earley_set_value_set ( Marpa_Recognizer r, int value)

Sets the “integer value” of the latest Earley set to value. For more about the integer value of an Earley set, see marpa_r_earley_set_values().

Return value: On success, returns the newly set integer value of the latest earley set, and sets the error code to MARPA_ERR_NONE. On hard failure, returns -2, and sets the error code to the error code of the hard failure, which will never be MARPA_ERR_NONE. Note that -2 is a valid “integer value” for an Earley set, so that when -2 is returned, the error code is the only way to distinguish success from failure. The error code can be determined using marpa_g_error(). See marpa_g_error().

Mutator function: int marpa_r_latest_earley_set_values_set ( Marpa_Recognizer r, int value, void* pvalue)

Sets the integer and pointer value of the latest Earley set. For more about the “integer value” and “pointer value” of an Earley set, see marpa_r_earley_set_values().

Return value: On success, returns a non-negative integer. On hard failure, returns -2.