ESC/Java2
© 2003,2004,2005 David Cok and Joseph Kiniry
© 2005 UCD Dublin
© 2003,2004 Radboud University Nijmegen
© 1999,2000 Compaq Computer Corporation
© 1997,1998,1999 Digital Equipment Corporation
All Rights Reserved

javafe.util
Class Location

java.lang.Object
  extended byjavafe.util.Location

public class Location
extends java.lang.Object

A location is an integer that identifies the position in a file of a particular piece of program source text. This class is never instantiated. It contains static functions for manipulating locations. Locations are produced by the CorrelatedReader class (and by this class), they are stored in ASTs, and they are passed to ErrorSet to identify the program source that caused a particular error or warning.

There are three kinds of locations.

  1. Regular locations encode the file, line, column, and offset of a character read by CorrelatedReader. A call to the getLocation() method of a CorrelatedReader object returns the regular location of the last character read from that CorrelatedReader object. The file/line/column/offset of that location can be extracted via the methods described below.
    Following emacs, line numbers begin at 1, column numbers at 0, and offsets at 1. A newline character is considered the last character on a line.
  2. Whole file locations encode just file information. They are currently used for error messages that are global to a file (eg. the error message given when a file that is expected to contain a package declaration does not have one). We expect they will also be used in ASTs produced from class files (since there is no meaningful line or column information, and offset information would not be useful in an error message).
  3. The null location is a constant that plays a similar role for locations that null plays for reference types.

Interface reviewed at Sparta Meeting 1/8/97.

See Also:
CorrelatedReader, ErrorSet

Field Summary
static int NULL
          The null location, is the constant 0.
 
Constructor Summary
private Location()
          Private constructor.
 
Method Summary
static int createFakeLoc(java.lang.String description)
          Create a fake location described by description.
static int createWholeFileLoc(GenericFile file)
          Create a whole file location corresponding to the given GenericFile.
static int inc(int loc, int n)
          Attempts to return a location n characters further to the right of loc on the same line.
static boolean isWholeFileLoc(int loc)
          Check if a location is a whole file location.
static int make(int streamId, int line, int col)
           
static GenericFile streamIdToFile(int id)
          Returns the file associated with stream id id, where id has previously been returned by toStreamId.
static int toColumn(int loc)
          Extracts the column corresponding to a location.
static GenericFile toFile(int loc)
          Extracts the file corresponding to a location.
static java.lang.String toFileLineString(int loc)
           
static java.lang.String toFileName(int loc)
          Extracts the filename corresponding to a location.
static int toLineNumber(int loc)
          Extracts the line number corresponding to a location.
static int toOffset(int loc)
          Extracts the offset corresponding to a location.
static int toStreamId(int loc)
          Returns the internal stream ID used for the stream associated with location loc.
static java.lang.String toString(int loc)
          Convert a location into a printable description suitable for use in a warning or error message.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NULL

public static final int NULL
The null location, is the constant 0.

See Also:
Constant Field Values
Constructor Detail

Location

private Location()
Private constructor. Never called.

Method Detail

isWholeFileLoc

public static boolean isWholeFileLoc(int loc)
Check if a location is a whole file location.

Precondition: loc should be a valid location (ie a regular, whole file, or dummy location).


toFile

public static GenericFile toFile(int loc)
Extracts the file corresponding to a location.

Precondition: loc should be a regular location or a whole file location.


toFileName

public static java.lang.String toFileName(int loc)
Extracts the filename corresponding to a location.

Precondition: loc should be a regular location or a whole file location.


toOffset

public static int toOffset(int loc)
Extracts the offset corresponding to a location. The first character in a stream is at offset 1.

Precondition: loc should be a regular location.


toLineNumber

public static int toLineNumber(int loc)
Extracts the line number corresponding to a location. The first line in a stream is numbered 1.

Precondition: loc should be a regular location.


toColumn

public static int toColumn(int loc)
Extracts the column corresponding to a location. The first column on each line is numbered 0.

Precondition: loc should be a regular location.


toString

public static java.lang.String toString(int loc)
Convert a location into a printable description suitable for use in a warning or error message.

Precondition: loc should be a valid location (ie a regular, whole file, or dummy location).


toFileLineString

public static java.lang.String toFileLineString(int loc)

createWholeFileLoc

public static int createWholeFileLoc(GenericFile file)
Create a whole file location corresponding to the given GenericFile. Calls to toFile on that location will return this file.


createFakeLoc

public static int createFakeLoc(java.lang.String description)
Create a fake location described by description.

This should only be used by debugging code and in places where it should never see the light of day. The resulting location is a whole-file location associated with an unopenable file with human-name description.


make

public static int make(int streamId,
                       int line,
                       int col)

inc

public static int inc(int loc,
                      int n)
Attempts to return a location n characters further to the right of loc on the same line. Returns the same location if it is not a regular location. Produces an assertion failure if that location does not exist (e.g., the line is too short.).


toStreamId

public static int toStreamId(int loc)
Returns the internal stream ID used for the stream associated with location loc.


streamIdToFile

public static GenericFile streamIdToFile(int id)
Returns the file associated with stream id id, where id has previously been returned by toStreamId.


ESC/Java2
© 2003,2004,2005 David Cok and Joseph Kiniry
© 2005 UCD Dublin
© 2003,2004 Radboud University Nijmegen
© 1999,2000 Compaq Computer Corporation
© 1997,1998,1999 Digital Equipment Corporation
All Rights Reserved

The ESC/Java2 Project Homepage