## Locator

Locator — Location information for errors, warnings and messages.

## Synopsis

                        raptor_locator;
    int                 raptor_locator_print                (raptor_locator *locator,
                                                             FILE *stream);
    int                 raptor_locator_format               (char *buffer,
                                                             size_t length,
                                                             raptor_locator *locator);
    int                 raptor_locator_line                 (raptor_locator *locator);
    int                 raptor_locator_column               (raptor_locator *locator);
    int                 raptor_locator_byte                 (raptor_locator *locator);
    const char *        raptor_locator_file                 (raptor_locator *locator);
    const char *        raptor_locator_uri                  (raptor_locator *locator);

## Description

A small structure that can be optionally filled in when errors, warnings or other messages are generated and returned to user code.

## Details

### raptor_locator

    typedef struct {
      raptor_uri *uri;
      const char *file;
      int line;
      int column;
      int byte;
    } raptor_locator;

Location information for an error, warning or information message.

raptor_uri *`uri`; | URI of location (or NULL)
const char *`file`; | Filename of location (or NULL)
int `line`; | Line number of location (or <0 for no line)
int `column`; | Column number of location (or <0 for no column)
int `byte`; | Byte number of location (or <0 for no byte)

### raptor_locator_print ()

    int                 raptor_locator_print                (raptor_locator *locator,
                                                             FILE *stream);

Print a raptor locator to a stream.

`locator` : | raptor_locator to print
`stream` : | stream to print to
Returns : | non-0 on failure

### raptor_locator_format ()

    int                 raptor_locator_format               (char *buffer,
                                                             size_t length,
                                                             raptor_locator *locator);

Format a raptor locator as a string.

If buffer is NULL or length is insufficient for the size of the locator, returns the number of additional bytes required in the buffer to write the locator.

`buffer` : | buffer to store format
`length` : | size of buffer
`locator` : | raptor_locator to format
Returns : | 0 on success, >0 if additional bytes required in buffer, <0 on failure

### raptor_locator_line ()

    int                 raptor_locator_line                 (raptor_locator *locator);

Get line number from locator.

`locator` : | locator
Returns : | integer line number, or -1 if there is no line number available

### raptor_locator_column ()

    int                 raptor_locator_column               (raptor_locator *locator);

Get column number from locator.

`locator` : | locator
Returns : | integer column number, or -1 if there is no column number available

### raptor_locator_byte ()

    int                 raptor_locator_byte                 (raptor_locator *locator);

Get the locator byte offset from locator.

`locator` : | locator
Returns : | integer byte number, or -1 if there is no byte offset available

### raptor_locator_file ()

    const char *        raptor_locator_file                 (raptor_locator *locator);

Get file name from locator.

`locator` : | locator
Returns : | string file name, or NULL if there is no filename available

### raptor_locator_uri ()

    const char *        raptor_locator_uri                  (raptor_locator *locator);

Get URI from locator.

Returns a pointer to a shared string version of the URI in the locator. This must be copied if it is needed.

`locator` : | locator
Returns : | string URI, or NULL if there is no URI available