InputFile Class Reference

Class for easily reading/writing files without having to worry about file type (uncompressed, gzip, bgzf) when reading. More...

`#include <InputFile.h>`

Inheritance diagram for InputFile:
[legend]
Collaboration diagram for InputFile:
[legend]

## Public Types

enum | ifileCompression { DEFAULT, UNCOMPRESSED, GZIP, BGZF }
| Compression to use when writing a file & decompression used when reading a file from stdin. More...

## Public Member Functions

| InputFile ()
| Default constructor.
| ~InputFile ()
| Destructor.
| InputFile (const char *filename, const char *mode, InputFile::ifileCompression compressionMode=InputFile::DEFAULT)
| Constructor for opening a file. More...
void | bufferReads (unsigned int bufferSize=DEFAULT_BUFFER_SIZE)
| Set the buffer size for reading from files so that bufferSize bytes are read at a time and stored until accessed by another read call. More...
void | disableBuffering ()
| Disable read buffering.
int | ifclose ()
| Close the file. More...
int | ifread (void *buffer, unsigned int size)
| Read size bytes from the file into the buffer. More...
int | readTilChar (const std::string &stopChars, std::string &stringRef)
| Read until the specified characters, returning which character was found causing the stop, -1 returned for EOF, storing the other read characters into the specified string. More...
int | readTilChar (const std::string &stopChars)
| Read until the specified characters, returning which character was found causing the stop, -1 returned for EOF, dropping all read chars. More...
int | discardLine ()
| Read until the end of the line, discarding the characters, returning -1 returned for EOF and returning 0 if the end of the line was found. More...
int | readLine (std::string &line)
| Read, appending the characters into the specified string until new line or EOF is found, returning -1 if EOF is found first and 0 if new line is found first. More...
int | readTilTab (std::string &field)
| Read, appending the characters into the specified string until tab, new line, or EOF is found, returning -1 if EOF is found first, 0 if new line is found first, or 1 if a tab is found first. More...
int | ifgetc ()
| Get a character from the file. More...
bool | ifgetline (void *voidBuffer, size_t max)
| Get a line from the file. More...
void | ifrewind ()
| Reset to the beginning of the file.
int | ifeof () const
| Check to see if we have reached the EOF. More...
unsigned int | ifwrite (const void *buffer, unsigned int size)
| Write the specified buffer into the file. More...
bool | isOpen () const
| Returns whether or not the file was successfully opened. More...
int64_t | iftell ()
| Get current position in the file. More...
bool | ifseek (int64_t offset, int origin)
| Seek to the specified offset from the origin. More...
const char * | getFileName () const
| Get the filename that is currently opened. More...
void | setAttemptRecovery (bool flag=false)
| Enable (default) or disable recovery. More...
bool | attemptRecoverySync (bool(*checkSignature)(void *data), int length)
bool | openFile (const char *filename, const char *mode, InputFile::ifileCompression compressionMode)

## Protected Member Functions

int | readFromFile (void *buffer, unsigned int size)

## Protected Attributes

FileType * | myFileTypePtr
unsigned int | myAllocatedBufferSize
char * | myFileBuffer
int | myBufferIndex
int | myCurrentBufferSize
std::string | myFileName

## Static Protected Attributes

static const unsigned int | DEFAULT_BUFFER_SIZE = 65536

## Detailed Description

Class for easily reading/writing files without having to worry about file type (uncompressed, gzip, bgzf) when reading.

It hides the low level file operations/structure from the user, allowing them to generically open and operate on a file using the same interface without knowing the file format (standard uncompressed, gzip, or bgzf). For writing, the user must specify the file type. There is a typedef IFILE which is InputFile* and setup to mimic FILE including global methods that take IFILE as a parameter.

Definition at line 36 of file InputFile.h.

## Member Enumeration Documentation

## ifileCompression

enum InputFile::ifileCompression

Compression to use when writing a file & decompression used when reading a file from stdin.

Any other read checks the file to determine how to uncompress it.

Enumerator
DEFAULT | Check the extension, if it is ".gz", treat as gzip, otherwise treat it as UNCOMPRESSED.
UNCOMPRESSED | uncompressed file.
GZIP | gzip file.
BGZF | bgzf file.

Definition at line 44 of file InputFile.h.

{
DEFAULT, ///< Check the extension, if it is ".gz", treat as gzip, otherwise treat it as UNCOMPRESSED.
UNCOMPRESSED, ///< uncompressed file.
GZIP, ///< gzip file.
BGZF ///< bgzf file.
};

## Constructor & Destructor Documentation

## InputFile()

InputFile::InputFile | ( | const char * | filename,
|  | const char * | mode,
|  | InputFile::ifileCompression | compressionMode = `InputFile::DEFAULT`
| ) |  |

Constructor for opening a file.

Parameters

  filename | file to open
  mode | same format as fopen: "r" for read & "w" for write.
  compressionMode | set the type of file to open for writing or for reading from stdin (when reading files, the compression type is determined by reading the file).

Definition at line 28 of file InputFile.cpp.

{
// XXX duplicate code
myAttemptRecovery = false;
myFileTypePtr = NULL;
myBufferIndex = 0;
myCurrentBufferSize = 0;
myAllocatedBufferSize = DEFAULT_BUFFER_SIZE;
myFileBuffer = new char[myAllocatedBufferSize];
myFileName.clear();
openFile(filename, mode, compressionMode);
}

## Member Function Documentation

## bufferReads()

void InputFile::bufferReads | ( | unsigned int | bufferSize = `DEFAULT_BUFFER_SIZE` | ) |

inline

Set the buffer size for reading from files so that bufferSize bytes are read at a time and stored until accessed by another read call.

This improves performance over reading the file small bits at a time. Buffering reads disables the tell call for bgzf files. Any previous values in the buffer will be deleted.

Parameters

  bufferSize | number of bytes to read/buffer at a time, turn off read buffering by setting bufferSize = 1;

Definition at line 83 of file InputFile.h.

{
// If the buffer size is the same, do nothing.
if(bufferSize == myAllocatedBufferSize)
{
return;
}
// Delete the previous buffer.
if(myFileBuffer != NULL)
{
delete[] myFileBuffer;
}
myBufferIndex = 0;
myCurrentBufferSize = 0;
// The buffer size must be at least 1 so one character can be
// read and ifgetc can just assume reading into the buffer.
if(bufferSize < 1)
{
bufferSize = 1;
}
myFileBuffer = new char[bufferSize];
myAllocatedBufferSize = bufferSize;
if(myFileTypePtr != NULL)
{
if(bufferSize == 1)
{
myFileTypePtr->setBuffered(false);
}
else
{
myFileTypePtr->setBuffered(true);
}
}
}

Referenced by disableBuffering().

## discardLine()

int InputFile::discardLine | ( |  | ) |

Read until the end of the line, discarding the characters, returning -1 returned for EOF and returning 0 if the end of the line was found.

Returns
  0 if the end of the line was found before EOF or -1 for EOF.

Definition at line 95 of file InputFile.cpp.

{
int charRead = 0;
// Loop until the character was not found in the stop characters.
while((charRead != EOF) && (charRead != '\n'))
{
charRead = ifgetc();
}
// First Check for EOF. If EOF is found, just return -1
if(charRead == EOF)
{
return(-1);
}
return(0);
}

References ifgetc().

## getFileName()

const char* InputFile::getFileName | ( |  | ) | const

inline

Get the filename that is currently opened.

Returns
  filename associated with this class

Definition at line 473 of file InputFile.h.

{
return(myFileName.c_str());
}

Referenced by SamFile::ReadBamIndex().

## ifclose()

int InputFile::ifclose | ( |  | ) |

inline

Close the file.

Returns
  status of the close (0 is success).

Definition at line 133 of file InputFile.h.

{
if (myFileTypePtr == NULL)
{
return EOF;
}
int result = myFileTypePtr->close();
delete myFileTypePtr;
myFileTypePtr = NULL;
myFileName.clear();
return result;
}

Referenced by ifclose().

## ifeof()

int InputFile::ifeof | ( |  | ) | const

inline

Check to see if we have reached the EOF.

Returns
  0 if not EOF, any other value means EOF.

Definition at line 386 of file InputFile.h.

{
// Not EOF if we are not at the end of the buffer.
if (myBufferIndex < myCurrentBufferSize)
{
// There are still available bytes in the buffer, so NOT EOF.
return false;
}
else
{
if (myFileTypePtr == NULL)
{
// No myFileTypePtr, so not eof (return 0).
return 0;
}
// exhausted our buffer, so check the file for eof.
return myFileTypePtr->eof();
}
}

Referenced by ifeof(), readLine(), and readTilTab().

## ifgetc()

int InputFile::ifgetc | ( |  | ) |

inline

Get a character from the file.

Read a character from the internal buffer, or if the end of the buffer has been reached, read from the file into the buffer and return index 0.

Returns
  character that was read or EOF.

Definition at line 324 of file InputFile.h.

{
if (myBufferIndex >= myCurrentBufferSize)
{
// at the last index, read a new buffer.
myCurrentBufferSize = readFromFile(myFileBuffer, myAllocatedBufferSize);
myBufferIndex = 0;
// If the buffer index is still greater than or equal to the
// myCurrentBufferSize, then we failed to read the file - return EOF.
// NB: This only needs to be checked when myCurrentBufferSize
// is changed. Simplify check - readFromFile returns zero on EOF
if (myCurrentBufferSize == 0)
{
return(EOF);
}
}
return(myFileBuffer[myBufferIndex++]);
}

Referenced by discardLine(), ifgetc(), ifgetline(), operator>>(), readLine(), readTilChar(), and readTilTab().

## ifgetline()

bool InputFile::ifgetline | ( | void * | voidBuffer,
|  | size_t | max
| ) |  |

inline

Get a line from the file.

Parameters

  buffer | the buffer into which data is to be placed
  max | the maximum size of the buffer, in bytes

Returns
  true if the last character read was an EOF

Definition at line 347 of file InputFile.h.

{
int ch;
char *buffer = (char *) voidBuffer;
while( (ch=ifgetc()) != '\n' && ch != EOF) {
*buffer++ = ch;
if((--max)<2)
{
// truncate the line, so drop remainder
while( (ch=ifgetc()) && ch != '\n' && ch != EOF)
{
}
break;
}
}
*buffer++ = '\0';
return ch==EOF;
}

References ifgetc().

Referenced by ifgetline().

## ifread()

int InputFile::ifread | ( | void * | buffer,
|  | unsigned int | size
| ) |  |

inline

Read size bytes from the file into the buffer.

Parameters

  buffer | pointer to memory at least size bytes big to write the data into.
  size | number of bytes to be read

Returns
  number of bytes read, if it is not equal to size, there was either an error or the end of the file was reached, use ifeof to determine which case it was.

Definition at line 153 of file InputFile.h.

{
// There are 2 cases:
// 1) There are already size available bytes in buffer.
// 2) There are not size bytes in buffer.
// Determine the number of available bytes in the buffer.
unsigned int availableBytes = myCurrentBufferSize - myBufferIndex;
int returnSize = 0;
// Case 1: There are already size available bytes in buffer.
if (size <= availableBytes)
{
// Just copy from the buffer, increment the index and return.
memcpy(buffer, myFileBuffer+myBufferIndex, size);
// Increment the buffer index.
myBufferIndex += size;
returnSize = size;
}
// Case 2: There are not size bytes in buffer.
else
{
// Check to see if there are some bytes in the buffer.
if (availableBytes > 0)
{
// Size > availableBytes > 0
// Copy the available bytes into the buffer.
memcpy(buffer, myFileBuffer+myBufferIndex, availableBytes);
}
// So far availableBytes have been copied into the read buffer.
returnSize = availableBytes;
// Increment myBufferIndex by what was read.
myBufferIndex += availableBytes;
unsigned int remainingSize = size - availableBytes;
// Check if the remaining size is more or less than the
// max buffer size.
if(remainingSize < myAllocatedBufferSize)
{
// the remaining size is not the full buffer, but read
// a full buffer worth of data anyway.
myCurrentBufferSize =
readFromFile(myFileBuffer, myAllocatedBufferSize);
// Check for an error.
if(myCurrentBufferSize <= 0)
{
// No more data was successfully read, so check to see
// if any data was copied to the return buffer at all.
if( returnSize == 0)
{
// No data has been copied at all into the
// return read buffer, so just return the value
// returned from readFromFile.
returnSize = myCurrentBufferSize;
// Otherwise, returnSize is already set to the
// available bytes that was already copied (so no
// else statement is needed).
}
// Set myBufferIndex & myCurrentBufferSize to 0.
myCurrentBufferSize = 0;
myBufferIndex = 0;
}
else
{
// Successfully read more data.
// Check to see how much was copied.
int copySize = remainingSize;
if(copySize > myCurrentBufferSize)
{
// Not the entire requested amount was read
// (either from EOF or there was a partial read due to
// an error), so set the copySize to what was read.
copySize = myCurrentBufferSize;
}
// Now copy the rest of the bytes into the buffer.
memcpy((char*)buffer+availableBytes,
myFileBuffer, copySize);
// set the buffer index to the location after what we are
// returning as read.
myBufferIndex = copySize;
returnSize += copySize;
}
}
else
{
// More remaining to be read than the max buffer size, so just
// read directly into the output buffer.
int readSize = readFromFile((char*)buffer + availableBytes,
remainingSize);
// Already used the buffer, so "clear" it.
myCurrentBufferSize = 0;
myBufferIndex = 0;
if(readSize <= 0)
{
// No more data was successfully read, so check to see
// if any data was copied to the return buffer at all.
if(returnSize == 0)
{
// No data has been copied at all into the
// return read buffer, so just return the value
// returned from readFromFile.
returnSize = readSize;
// Otherwise, returnSize is already set to the
// available bytes that was already copied (so no
// else statement is needed).
}
}
else
{
// More data was read, so increment the return count.
returnSize += readSize;
}
}
}
return(returnSize);
}

Referenced by ifread().

## ifseek()

bool InputFile::ifseek | ( | int64_t | offset,
|  | int | origin
| ) |  |

inline

Seek to the specified offset from the origin.

Parameters

  offset | offset into the file to move to (must be from a tell call)
  origin | can be any of the following: Note: not all are valid for all filetypes. SEEK_SET - Beginning of file SEEK_CUR - Current position of the file pointer SEEK_END - End of file

Returns
  true on successful seek and false on a failed seek.

Definition at line 457 of file InputFile.h.

{
if (myFileTypePtr == NULL)
{
// No myFileTypePtr, so return false - could not seek.
return false;
}
// TODO - may be able to seek within the buffer if applicable.
// Reset buffering since a seek is being done.
myBufferIndex = 0;
myCurrentBufferSize = 0;
return myFileTypePtr->seek(offset, origin);
}

Referenced by ifseek().

## iftell()

int64_t InputFile::iftell | ( |  | ) |

inline

Get current position in the file.

Returns
  current position in the file, -1 indicates an error.

Definition at line 436 of file InputFile.h.

{
if (myFileTypePtr == NULL)
{
// No myFileTypePtr, so return false - could not seek.
return -1;
}
int64_t pos = myFileTypePtr->tell();
pos -= (myCurrentBufferSize - myBufferIndex);
return(pos);
}

Referenced by iftell().

## ifwrite()

unsigned int InputFile::ifwrite | ( | const void * | buffer,
|  | unsigned int | size
| ) |  |

inline

Write the specified buffer into the file.

Parameters

  buffer | buffer containing size bytes to write to the file.
  size | number of bytes to write

Returns
  number of bytes written We do not buffer the write call, so just leave this as normal.

Definition at line 411 of file InputFile.h.

{
if (myFileTypePtr == NULL)
{
// No myFileTypePtr, so return 0 - nothing written.
return 0;
}
return myFileTypePtr->write(buffer, size);
}

Referenced by ifwrite(), and operator<<().

## isOpen()

bool InputFile::isOpen | ( |  | ) | const

inline

Returns whether or not the file was successfully opened.

Returns
  true if the file is open, false if not.

Definition at line 423 of file InputFile.h.

{
// It is open if the myFileTypePtr is set and says it is open.
if ((myFileTypePtr != NULL) && myFileTypePtr->isOpen())
{
return true;
}
// File was not successfully opened.
return false;
}

Referenced by ifopen(), FastQFile::isOpen(), SamFile::IsOpen(), GlfHeader::read(), SamRecord::setBufferFromFile(), GlfHeader::write(), and SamRecord::writeRecordBuffer().

## readLine()

int InputFile::readLine | ( | std::string & | line | ) |

Read, appending the characters into the specified string until new line or EOF is found, returning -1 if EOF is found first and 0 if new line is found first.

The new line and EOF are not written into the specified string.

Parameters

  line | reference to a string that the read characters should be apppended to (does not include the new line or eof).

Returns
  0 if new line and -1 for EOF.

Definition at line 112 of file InputFile.cpp.

{
int charRead = 0;
while(!ifeof())
{
charRead = ifgetc();
if(charRead == EOF)
{
return(-1);
}
if(charRead == '\n')
{
return(0);
}
line += charRead;
}
// Should never get here.
return(-1);
}

References ifeof(), and ifgetc().

## readTilChar() [1/2]

int InputFile::readTilChar | ( | const std::string & | stopChars | ) |

Read until the specified characters, returning which character was found causing the stop, -1 returned for EOF, dropping all read chars.

Note: If stopChars is just '
', discardLine is faster.

Parameters

  stopChars | characters to stop reading when they are hit.

Returns
  index of the character in stopChars that caused it to stop reading or -1 for EOF.

Definition at line 73 of file InputFile.cpp.

{
int charRead = 0;
size_t pos = std::string::npos;
// Loop until the character was not found in the stop characters.
while(pos == std::string::npos)
{
charRead = ifgetc();
// First Check for EOF. If EOF is found, just return -1
if(charRead == EOF)
{
return(-1);
}
// Try to find the character in the stopChars.
pos = stopChars.find(charRead);
}
return(pos);
}

References ifgetc().

## readTilChar() [2/2]

int InputFile::readTilChar | ( | const std::string & | stopChars,
|  | std::string & | stringRef
| ) |  |

Read until the specified characters, returning which character was found causing the stop, -1 returned for EOF, storing the other read characters into the specified string.

Note: If stopChars is just '
', readLine is faster and if stopChars is just '
' and '\t', readTilTab is faster.

Parameters

  stopChars | characters to stop reading when they are hit.
  stringRef | reference to a string that the read characters should be apppended to (does not include the stopchar).

Returns
  index of the character in stopChars that caused it to stop reading or -1 for EOF.

Definition at line 44 of file InputFile.cpp.

{
int charRead = 0;
size_t pos = std::string::npos;
// Loop until the character was not found in the stop characters.
while(pos == std::string::npos)
{
charRead = ifgetc();
// First Check for EOF. If EOF is found, just return -1
if(charRead == EOF)
{
return(-1);
}
// Try to find the character in the stopChars.
pos = stopChars.find(charRead);
if(pos == std::string::npos)
{
// Didn't find a stop character and it is not an EOF,
// so add it to the string.
stringRef += charRead;
}
}
return(pos);
}

References ifgetc().

## readTilTab()

int InputFile::readTilTab | ( | std::string & | field | ) |

Read, appending the characters into the specified string until tab, new line, or EOF is found, returning -1 if EOF is found first, 0 if new line is found first, or 1 if a tab is found first.

The tab, new line, and EOF are not written into the specified string.

Parameters

  field | reference to a string that the read characters should be apppended to (does not include the tab, new line, or eof).

Returns
  1 if tab is found, 0 if new line, and -1 for EOF.

Definition at line 133 of file InputFile.cpp.

{
int charRead = 0;
while(!ifeof())
{
charRead = ifgetc();
if(charRead == EOF)
{
return(-1);
}
if(charRead == '\n')
{
return(0);
}
if(charRead == '\t')
{
return(1);
}
field += charRead;
}
return(-1);
}

References ifeof(), and ifgetc().

## setAttemptRecovery()

void InputFile::setAttemptRecovery | ( | bool | flag = `false` | ) |

inline

Enable (default) or disable recovery.

When true, we can attach a myFileTypePtr that implements a recovery capable decompressor. This requires that the caller be able to catch the exception XXX "blah blah blah".

Definition at line 485 of file InputFile.h.

{
myAttemptRecovery = flag;
}

Referenced by SamFile::OpenForRead().

The documentation for this class was generated from the following files:

- general/InputFile.h
- general/InputFile.cpp

InputFile::DEFAULT
Check the extension, if it is ".gz", treat as gzip, otherwise treat it as UNCOMPRESSED.
Definition: InputFile.h:45
InputFile::GZIP
gzip file.
Definition: InputFile.h:47
InputFile::UNCOMPRESSED
uncompressed file.
Definition: InputFile.h:46
InputFile::ifeof
int ifeof() const
Check to see if we have reached the EOF.
Definition: InputFile.h:386
InputFile::ifgetc
int ifgetc()
Get a character from the file.
Definition: InputFile.h:324
BGZF
Definition: bgzf.h:44