ajfile.c

Section: Outfile Constructors

All constructors return a new open file by pointer. It is the responsibility of the user to first destroy any previous file pointer. The target pointer does not need to be initialised to NULL, but it is good programming practice to do so anyway.

To replace or reuse an existing file, see instead the File Assignments and File Modifiers functions.

The range of constructors is provided to allow flexibility in how applications can open files to read various kinds of data.

Functions: ajOutfileNew

Function ajOutfileNew

Creates a new formatted output file object with a specified name.

'stdout' and 'stderr' are special names for standard output and standard error respectively.

Synopsis

Prototype

AjPOutfile ajOutfileNew (
      const AjPStr name
);

Type Name Read/Write Description

const AjPStr name Input File name.

AjPOutfile RETURN New output file object.

Type	Name	Read/Write	Description
const AjPStr	name	Input	File name.
AjPOutfile		RETURN	New output file object.

Input

name:

(Input)

File name.

Returns

AjPOutfile:

New output file object.

Description

Creates a new formatted output file object with a specified name.

'stdout' and 'stderr' are special names for standard output and standard error respectively.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: Directory Constructors

All constructors return a directory object by pointer. It is the responsibility of the user to first destroy any previous directory pointer. The target pointer does not need to be initialised to NULL, but it is good programming practice to do so anyway.

To replace or reuse an existing file, see instead the File Assignments and File Modifiers functions.

The range of constructors is provided to allow flexibility in how applications can open files to read various kinds of data.

Functions: ajDirNew ajDirNewS ajDirNewSS ajDiroutNew ajDiroutNewS ajDiroutNewSS ajDirName ajDirExt

Function ajDirNew

Creates a new directory object.

Synopsis

Prototype

AjPDir ajDirNew (
      const AjPStr name
);

Type Name Read/Write Description

const AjPStr name Input Directory name

AjPDir RETURN New directory object.

Type	Name	Read/Write	Description
const AjPStr	name	Input	Directory name
AjPDir		RETURN	New directory object.

Input

name:

(Input)

Directory name

Returns

AjPDir:

New directory object.

Description

Creates a new directory object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajDirNewS

Creates a new directory object.

Synopsis

Prototype

AjPDir ajDirNewS (
      const AjPStr name,
      const AjPStr ext
);

Type Name Read/Write Description

const AjPStr name Input Directory name

const AjPStr ext Input File extension

AjPDir RETURN New directory object.

Type	Name	Read/Write	Description
const AjPStr	name	Input	Directory name
const AjPStr	ext	Input	File extension
AjPDir		RETURN	New directory object.

Input

name:	(Input)	Directory name
ext:	(Input)	File extension

Returns

AjPDir:

New directory object.

Description

Creates a new directory object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajDirNewSS

Creates a new directory object.

Synopsis

Prototype

AjPDir ajDirNewSS (
      const AjPStr name,
      const AjPStr prefix,
      const AjPStr ext
);

Type Name Read/Write Description

const AjPStr name Input Directory name

const AjPStr prefix Input Filename prefix

const AjPStr ext Input Filename extension

AjPDir RETURN New directory object.

Type	Name	Read/Write	Description
const AjPStr	name	Input	Directory name
const AjPStr	prefix	Input	Filename prefix
const AjPStr	ext	Input	Filename extension
AjPDir		RETURN	New directory object.

Input

name:	(Input)	Directory name
prefix:	(Input)	Filename prefix
ext:	(Input)	Filename extension

Returns

AjPDir:

New directory object.

Description

Creates a new directory object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajDiroutNew

Creates a new directory output object.

Synopsis

Prototype

AjPDir ajDiroutNew (
      const AjPStr name
);

Type Name Read/Write Description

const AjPStr name Input Directory name

AjPDir RETURN New directory object.

Type	Name	Read/Write	Description
const AjPStr	name	Input	Directory name
AjPDir		RETURN	New directory object.

Input

name:

(Input)

Directory name

Returns

AjPDir:

New directory object.

Description

Creates a new directory output object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajDiroutNewS

Creates a new directory output object.

Synopsis

Prototype

AjPDir ajDiroutNewS (
      const AjPStr name,
      const AjPStr ext
);

Type Name Read/Write Description

const AjPStr name Input Directory name

const AjPStr ext Input File extension

AjPDir RETURN New directory object.

Type	Name	Read/Write	Description
const AjPStr	name	Input	Directory name
const AjPStr	ext	Input	File extension
AjPDir		RETURN	New directory object.

Input

name:	(Input)	Directory name
ext:	(Input)	File extension

Returns

AjPDir:

New directory object.

Description

Creates a new directory output object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajDiroutNewSS

Creates a new directory output object.

Synopsis

Prototype

AjPDir ajDiroutNewSS (
      const AjPStr name,
      const AjPStr prefix,
      const AjPStr ext
);

Type Name Read/Write Description

const AjPStr name Input Directory name

const AjPStr prefix Input Filename prefix

const AjPStr ext Input File extension

AjPDir RETURN New directory object.

Type	Name	Read/Write	Description
const AjPStr	name	Input	Directory name
const AjPStr	prefix	Input	Filename prefix
const AjPStr	ext	Input	File extension
AjPDir		RETURN	New directory object.

Input

name:	(Input)	Directory name
prefix:	(Input)	Filename prefix
ext:	(Input)	File extension

Returns

AjPDir:

New directory object.

Description

Creates a new directory output object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajDirName

Returns the name of a directory object

Synopsis

Prototype

AjPStr ajDirName (
      const AjPDir thys
);

Type Name Read/Write Description

const AjPDir thys Input Directory object.

AjPStr RETURN Directory name

Type	Name	Read/Write	Description
const AjPDir	thys	Input	Directory object.
AjPStr		RETURN	Directory name

Input

thys:

(Input)

Directory object.

Returns

AjPStr:

Directory name

Description

Returns the name of a directory object

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajDirExt

Returns the extension of a directory object

Synopsis

Prototype

AjPStr ajDirExt (
      const AjPDir thys
);

Type Name Read/Write Description

const AjPDir thys Input Directory object.

AjPStr RETURN Directory name

Type	Name	Read/Write	Description
const AjPDir	thys	Input	Directory object.
AjPStr		RETURN	Directory name

Input

thys:

(Input)

Directory object.

Returns

AjPStr:

Directory name

Description

Returns the extension of a directory object

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: File Constructors

To replace or reuse an existing file, see instead the File Assignments and File Modifiers functions.

The range of constructors is provided to allow flexibility in how applications can open files to read various kinds of data.

Functions: ajFileNew ajFileNewInPipe ajFileNewIn ajFileNewInC ajFileNewInList ajFileNewApp ajFileNewOut ajFileNewOutC ajFileNewOutD ajFileNewOutDir ajFileSetDir ajFileHasDir ajFileNewF

Function ajFileNew

Creates a new file object.

Synopsis

Prototype

AjPFile ajFileNew (
      void
);

Type Name Read/Write Description

AjPFile RETURN New file object.

Type	Name	Read/Write	Description
AjPFile		RETURN	New file object.

Returns

AjPFile:

New file object.

Description

Creates a new file object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewInPipe

Creates a new file object to read the output from a command.

Synopsis

Prototype

AjPFile ajFileNewInPipe (
      const AjPStr name
);

Type Name Read/Write Description

const AjPStr name Input Command string.

AjPFile RETURN New file object.

Type	Name	Read/Write	Description
const AjPStr	name	Input	Command string.
AjPFile		RETURN	New file object.

Input

name:

(Input)

Command string.

Returns

AjPFile:

New file object.

Description

Creates a new file object to read the output from a command.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewIn

Creates a new file object to read a named file.

If the filename ends with a pipe character then a pipe is opened using ajFileNewInPipe.

Synopsis

Prototype

AjPFile ajFileNewIn (
      const AjPStr name
);

Type Name Read/Write Description

const AjPStr name Input File name.

AjPFile RETURN New file object.

Type	Name	Read/Write	Description
const AjPStr	name	Input	File name.
AjPFile		RETURN	New file object.

Input

name:

(Input)

File name.

Returns

AjPFile:

New file object.

Description

Creates a new file object to read a named file.

If the filename ends with a pipe character then a pipe is opened using ajFileNewInPipe.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewInC

Creates a new file object to read a named file.

If the filename begins with a pipe character then a pipe is opened using ajFileNewInPipe.

Synopsis

Prototype

AjPFile ajFileNewInC (
      const char* name
);

Type Name Read/Write Description

const char* name Input File name.

AjPFile RETURN New file object.

Type	Name	Read/Write	Description
const char*	name	Input	File name.
AjPFile		RETURN	New file object.

Input

name:

(Input)

File name.

Returns

AjPFile:

New file object.

Description

Creates a new file object to read a named file.

If the filename begins with a pipe character then a pipe is opened using ajFileNewInPipe.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewInList

Creates a new file object with a list of input files.

Synopsis

Prototype

AjPFile ajFileNewInList (
      AjPList list
);

Type Name Read/Write Description

AjPList list Modify List of input filenames as strings.

AjPFile RETURN New file object.

Type	Name	Read/Write	Description
AjPList	list	Modify	List of input filenames as strings.
AjPFile		RETURN	New file object.

Input & Output

list:

(Modify)

List of input filenames as strings.

Returns

AjPFile:

New file object.

Description

Creates a new file object with a list of input files.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewApp

Creates an output file object with a specified name. The file is opened for append so it either appends to an existing file or opens a new one.

Synopsis

Prototype

AjPFile ajFileNewApp (
      const AjPStr name
);

Type Name Read/Write Description

const AjPStr name Input File name.

AjPFile RETURN New file object.

Type	Name	Read/Write	Description
const AjPStr	name	Input	File name.
AjPFile		RETURN	New file object.

Input

name:

(Input)

File name.

Returns

AjPFile:

New file object.

Description

Creates an output file object with a specified name. The file is opened for append so it either appends to an existing file or opens a new one.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewOut

Creates a new output file object with a specified name.

'stdout' and 'stderr' are special names for standard output and standard error respectively.

Synopsis

Prototype

AjPFile ajFileNewOut (
      const AjPStr name
);

Type Name Read/Write Description

const AjPStr name Input File name.

AjPFile RETURN New file object.

Type	Name	Read/Write	Description
const AjPStr	name	Input	File name.
AjPFile		RETURN	New file object.

Input

name:

(Input)

File name.

Returns

AjPFile:

New file object.

Description

Creates a new output file object with a specified name.

'stdout' and 'stderr' are special names for standard output and standard error respectively.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewOutC

Creates a new output file object with a specified name.

'stdout' and 'stderr' are special names for standard output and standard error respectively.

Synopsis

Prototype

AjPFile ajFileNewOutC (
      const char* name
);

Type Name Read/Write Description

const char* name Input File name.

AjPFile RETURN New file object.

Type	Name	Read/Write	Description
const char*	name	Input	File name.
AjPFile		RETURN	New file object.

Input

name:

(Input)

File name.

Returns

AjPFile:

New file object.

Description

Creates a new output file object with a specified name.

'stdout' and 'stderr' are special names for standard output and standard error respectively.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewOutD

Creates a new output file object with a specified directory and name.

'stdout' and 'stderr' are special names for standard output and standard error respectively.

If the filename already has a directory specified, the "dir" argument is ignored.

Synopsis

Prototype

AjPFile ajFileNewOutD (
      const AjPStr dir,
      const AjPStr name
);

Type Name Read/Write Description

const AjPStr dir Input Directory (optional, can be empty or NULL).

const AjPStr name Input File name.

AjPFile RETURN New file object.

Input

dir:	(Input)	Directory (optional, can be empty or NULL).
name:	(Input)	File name.

Returns

AjPFile:

New file object.

Description

Creates a new output file object with a specified directory and name.

'stdout' and 'stderr' are special names for standard output and standard error respectively.

If the filename already has a directory specified, the "dir" argument is ignored.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewOutDir

Creates a new output file object with a specified directory and name. Uses the default extension (if any) specified for the directory.

'stdout' and 'stderr' are special names for standard output and standard error respectively.

If the filename already has a directory specified, the "dir" argument is ignored.

Synopsis

Prototype

AjPFile ajFileNewOutDir (
      const AjPDir dir,
      const AjPStr name
);

Type Name Read/Write Description

const AjPDir dir Input Directory (optional, can be empty or NULL).

const AjPStr name Input File name.

AjPFile RETURN New file object.

Input

dir:	(Input)	Directory (optional, can be empty or NULL).
name:	(Input)	File name.

Returns

AjPFile:

New file object.

Description

Creates a new output file object with a specified directory and name. Uses the default extension (if any) specified for the directory.

'stdout' and 'stderr' are special names for standard output and standard error respectively.

If the filename already has a directory specified, the "dir" argument is ignored.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileSetDir

Adds a default directory to a filename. If the filename already has a directory, then this is left unchanged.

'stdout' and 'stderr' are special names for standard output and standard error respectively which need no directory.

Synopsis

Prototype

AjBool ajFileSetDir (
      AjPStr* pname,
      const AjPStr dir
);

Type Name Read/Write Description

AjPStr* pname Modify File name, returned with directory prefix

const AjPStr dir Input Directory (optional, can be empty or NULL).

AjBool RETURN ajTrue if the filename was changed

Input

dir:

(Input)

Directory (optional, can be empty or NULL).

Input & Output

pname:

(Modify)

File name, returned with directory prefix

Returns

AjBool:

ajTrue if the filename was changed

Description

Adds a default directory to a filename. If the filename already has a directory, then this is left unchanged.

'stdout' and 'stderr' are special names for standard output and standard error respectively which need no directory.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileHasDir

Tests whether a filename includes a directory specification.

Synopsis

Prototype

AjBool ajFileHasDir (
      const AjPStr name
);

Type Name Read/Write Description

const AjPStr name Input File name.

AjBool RETURN ajTrue if directory filename syntax was found

Input

name:

(Input)

File name.

Returns

AjBool:

ajTrue if directory filename syntax was found

Description

Tests whether a filename includes a directory specification.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewF

Creates a new file object from an open C file.

Synopsis

Prototype

AjPFile ajFileNewF (
      FILE* file
);

Type Name Read/Write Description

FILE* file Modify C file.

AjPFile RETURN New file object.

Input & Output

file:

(Modify)

C file.

Returns

AjPFile:

New file object.

Description

Creates a new file object from an open C file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: Outfile Destructors

Destruction is achieved by closing the file.

Unlike ANSI C, there are tests to ensure a file is not closed twice.

Functions: ajOutfileClose ajOutfileDel

Function ajOutfileClose

Close and free an outfile object.

Synopsis

Prototype

void ajOutfileClose (
      AjPOutfile* pthis
);

Type Name Read/Write Description

AjPOutfile* pthis Delete Output file.

void RETURN

Output

pthis:

(Delete)

Output file.

Returns

void:

No return value

Description

Close and free an outfile object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajOutfileDel

Close and free an outfile object.

Synopsis

Prototype

void ajOutfileDel (
      AjPOutfile* pthis
);

Type Name Read/Write Description

AjPOutfile* pthis Delete Output file.

void RETURN

Output

pthis:

(Delete)

Output file.

Returns

void:

No return value

Description

Close and free an outfile object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: Directory Destructors

Destruction is achieved by deleting the object.

Functions: ajDirDel ajDiroutDel

Function ajDirDel

Close and free a directory object.

Synopsis

Prototype

void ajDirDel (
      AjPDir* pthis
);

Type Name Read/Write Description

AjPDir* pthis Delete Directory object.

void RETURN

Output

pthis:

(Delete)

Directory object.

Returns

void:

No return value

Description

Close and free a directory object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajDiroutDel

Close and free a directory object.

Synopsis

Prototype

void ajDiroutDel (
      AjPDir* pthis
);

Type Name Read/Write Description

AjPDir* pthis Delete Directory object.

void RETURN

Output

pthis:

(Delete)

Directory object.

Returns

void:

No return value

Description

Close and free a directory object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: File Destructors

Destruction is achieved by closing the file.

Unlike ANSI C, there are tests to ensure a file is not closed twice.

Functions: ajFileClose ajFileOutClose

Function ajFileClose

Close and free a file object.

Synopsis

Prototype

void ajFileClose (
      AjPFile* pthis
);

Type Name Read/Write Description

AjPFile* pthis Delete File.

void RETURN

Output

pthis:

(Delete)

File.

Returns

void:

No return value

Description

Close and free a file object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileOutClose

Closes and deletes an output file object.

Synopsis

Prototype

void ajFileOutClose (
      AjPFile* pthis
);

Type Name Read/Write Description

AjPFile* pthis Delete Output file.

void RETURN

Output

pthis:

(Delete)

Output file.

Returns

void:

No return value

Description

Closes and deletes an output file object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: File Assignments

These functions overwrite the file provided as the first argument

Functions: ajFileDataNew ajFileDataNewC ajFileDataDirNew ajFileDataDirNewC

Function ajFileDataNew

Returns an allocated AjFileInNew pointer (AjPFile) if file exists a) in . b) in ./.embossdata c) ~/ d) ~/.embossdata e) $DATA

Synopsis

Prototype

void ajFileDataNew (
      const AjPStr tfile,
      AjPFile* fnew
);

Type Name Read/Write Description

const AjPStr tfile Input Filename in AjStr.

AjPFile* fnew Output file pointer.

void RETURN

Input

tfile:

(Input)

Filename in AjStr.

Output

fnew:

(Output)

file pointer.

Returns

void:

No return value

Description

Returns an allocated AjFileInNew pointer (AjPFile) if file exists a) in . b) in ./.embossdata c) ~/ d) ~/.embossdata e) $DATA

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileDataNewC

Returns an allocated AjFileInNew pointer (AjPFile) if file exists a) in . b) in ./.embossdata c) ~/ d) ~/.embossdata e) $DATA

Synopsis

Prototype

void ajFileDataNewC (
      const char* s,
      AjPFile* f
);

Type Name Read/Write Description

const char* s Input Filename.

AjPFile* f Output file pointer.

void RETURN

Input

(Input)

Filename.

Output

(Output)

file pointer.

Returns

void:

No return value

Description

Returns an allocated AjFileInNew pointer (AjPFile) if file exists a) in . b) in ./.embossdata c) ~/ d) ~/.embossdata e) $DATA

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileDataDirNew

Returns an allocated AjFileInNew pointer (AjPFile) if file exists in the EMBOSS/data/(dir) directory, or is found in the usual directories by ajFileDataNew

Synopsis

Prototype

void ajFileDataDirNew (
      const AjPStr tfile,
      const AjPStr dir,
      AjPFile* fnew
);

Type Name Read/Write Description

const AjPStr tfile Input Filename in AjStr.

const AjPStr dir Input Data directory name in AjStr.

AjPFile* fnew Output file pointer.

void RETURN

Input

tfile:	(Input)	Filename in AjStr.
dir:	(Input)	Data directory name in AjStr.

Output

fnew:

(Output)

file pointer.

Returns

void:

No return value

Description

Returns an allocated AjFileInNew pointer (AjPFile) if file exists in the EMBOSS/data/(dir) directory, or is found in the usual directories by ajFileDataNew

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileDataDirNewC

Returns an allocated AjFileInNew pointer (AjPFile) if file exists in the EMBOSS/data/(dir) directory, or is found in the usual directories by ajFileDataNew

Synopsis

Prototype

void ajFileDataDirNewC (
      const char* s,
      const char* d,
      AjPFile* f
);

Type Name Read/Write Description

const char* s Input Filename

const char* d Input Data directory name.

AjPFile* f Output file pointer.

void RETURN

Input

s:	(Input)	Filename
d:	(Input)	Data directory name.

Output

(Output)

file pointer.

Returns

void:

No return value

Description

Returns an allocated AjFileInNew pointer (AjPFile) if file exists in the EMBOSS/data/(dir) directory, or is found in the usual directories by ajFileDataNew

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: File Modifiers

These functions use the contents of a file object and update them.

Functions: ajFileSeek ajFileRead ajFileReadUint ajFileWrite ajFileNext ajFileReopen ajFileReadLine ajFileGetsTrimL ajFileGetsTrim ajFileGets ajFileGetsL ajFileUnbuffer ajFileReadAppend ajFileOutHeader ajFileNameShorten ajFileNameTrim ajFileDataNewWrite

Function ajFileSeek

Sets the current position in an open file.

Resets the end-of-file flag End for cases where end-of-file was reached and then we seek back somewhere in the file.

Synopsis

Prototype

ajint ajFileSeek (
      AjPFile thys,
      ajlong offset,
      ajint wherefrom
);

Type Name Read/Write Description

AjPFile thys Modify File.

ajlong offset Input Offset

ajint wherefrom Input Start of offset, as defined for 'fseek'.

ajint RETURN Result of 'fseek'

Input

offset:	(Input)	Offset
wherefrom:	(Input)	Start of offset, as defined for 'fseek'.

Input & Output

thys:

(Modify)

File.

Returns

ajint:

Result of 'fseek'

Description

Sets the current position in an open file.

Resets the end-of-file flag End for cases where end-of-file was reached and then we seek back somewhere in the file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileRead

Binary read from an input file object using the C 'fread' function.

Synopsis

Prototype

size_t ajFileRead (
      void* ptr,
      size_t element_size,
      size_t count,
      AjPFile thys
);

Type Name Read/Write Description

void* ptr Output Buffer for output.

size_t element_size Input Number of bytes per element.

size_t count Input Number of elements to read.

AjPFile thys Modify Input file.

size_t RETURN Return value from 'fread'

Input

element_size:	(Input)	Number of bytes per element.
count:	(Input)	Number of elements to read.

Output

ptr:

(Output)

Buffer for output.

Input & Output

thys:

(Modify)

Input file.

Returns

size_t:

Return value from 'fread'

Description

Binary read from an input file object using the C 'fread' function.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileReadUint

Binary read of an unsigned integer from an input file object using the C 'fread' function. Converts from a specified endianism.

Synopsis

Prototype

ajuint ajFileReadUint (
      AjPFile thys,
      AjBool Bigendian
);

Type Name Read/Write Description

AjPFile thys Modify Input file.

AjBool Bigendian Input Big endian or not.

ajuint RETURN Converted integer value

Input

Bigendian:

(Input)

Big endian or not.

Input & Output

thys:

(Modify)

Input file.

Returns

ajuint:

Converted integer value

Description

Binary read of an unsigned integer from an input file object using the C 'fread' function. Converts from a specified endianism.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileWrite

Binary write to an output file object using the C 'fwrite' function.

Synopsis

Prototype

size_t ajFileWrite (
      AjPFile thys,
      const void* ptr,
      size_t element_size,
      size_t count
);

Type Name Read/Write Description

AjPFile thys Modify Output file.

const void* ptr Input Buffer for output.

size_t element_size Input Number of bytes per element.

size_t count Input Number of elements to write.

size_t RETURN Return value from 'fwrite'

Input

ptr:	(Input)	Buffer for output.
element_size:	(Input)	Number of bytes per element.
count:	(Input)	Number of elements to write.

Input & Output

thys:

(Modify)

Output file.

Returns

size_t:

Return value from 'fwrite'

Description

Binary write to an output file object using the C 'fwrite' function.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNext

Given a file object that includes a list of input files, closes the current input file and opens the next one.

Synopsis

Prototype

AjBool ajFileNext (
      AjPFile thys
);

Type Name Read/Write Description

AjPFile thys Modify File object.

AjBool RETURN ajTrue on success.

Input & Output

thys:

(Modify)

File object.

Returns

AjBool:

ajTrue on success.

Description

Given a file object that includes a list of input files, closes the current input file and opens the next one.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileReopen

Reopens a file with a new name.

Synopsis

Prototype

FILE* ajFileReopen (
      AjPFile thys,
      const AjPStr name
);

Type Name Read/Write Description

AjPFile thys Modify Input file.

const AjPStr name Input name of file.

FILE* RETURN copy of file pointer

Input

name:

(Input)

name of file.

Input & Output

thys:

(Modify)

Input file.

Returns

FILE*:

copy of file pointer

Description

Reopens a file with a new name.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileReadLine

Reads a line from the input file, removing any trailing newline.

Synopsis

Prototype

AjBool ajFileReadLine (
      AjPFile thys,
      AjPStr* pdest
);

Type Name Read/Write Description

AjPFile thys Modify Input file.

AjPStr* pdest Output Buffer to hold the current line.

AjBool RETURN ajTrue on success.

Output

pdest:

(Output)

Buffer to hold the current line.

Input & Output

thys:

(Modify)

Input file.

Returns

AjBool:

ajTrue on success.

Description

Reads a line from the input file, removing any trailing newline.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileGetsTrimL

Reads a line from a file and removes any trailing newline.

Synopsis

Prototype

AjBool ajFileGetsTrimL (
      AjPFile thys,
      AjPStr* pdest,
      ajlong* fpos
);

Type Name Read/Write Description

AjPFile thys Modify Input file.

AjPStr* pdest Output Buffer to hold the current line.

ajlong* fpos Output File position before the read.

AjBool RETURN ajTrue on success.

Output

pdest:	(Output)	Buffer to hold the current line.
fpos:	(Output)	File position before the read.

Input & Output

thys:

(Modify)

Input file.

Returns

AjBool:

ajTrue on success.

Description

Reads a line from a file and removes any trailing newline.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileGetsTrim

Reads a line from a file and removes any trailing newline.

Synopsis

Prototype

AjBool ajFileGetsTrim (
      AjPFile thys,
      AjPStr* pdest
);

Type Name Read/Write Description

AjPFile thys Modify Input file.

AjPStr* pdest Output Buffer to hold the current line.

AjBool RETURN ajTrue on success.

Output

pdest:

(Output)

Buffer to hold the current line.

Input & Output

thys:

(Modify)

Input file.

Returns

AjBool:

ajTrue on success.

Description

Reads a line from a file and removes any trailing newline.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileGets

Reads a line from a file and returns the initial file position.

Synopsis

Prototype

AjBool ajFileGets (
      AjPFile thys,
      AjPStr* pdest
);

Type Name Read/Write Description

AjPFile thys Modify Input file.

AjPStr* pdest Output Buffer to hold the current line.

AjBool RETURN ajTrue on success.

Output

pdest:

(Output)

Buffer to hold the current line.

Input & Output

thys:

(Modify)

Input file.

Returns

AjBool:

ajTrue on success.

Description

Reads a line from a file and returns the initial file position.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileGetsL

Reads a line from a file.

Synopsis

Prototype

AjBool ajFileGetsL (
      AjPFile thys,
      AjPStr* pdest,
      ajlong* fpos
);

Output

pdest:	(Output)	Buffer to hold the current line.
fpos:	(Output)	File position before the read.

Input & Output

thys:

(Modify)

Input file.

Returns

AjBool:

ajTrue on success.

Description

Reads a line from a file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileUnbuffer

Turns off system buffering of an output file, for example to allow debug output to appear even in the event of a program abort.

Synopsis

Prototype

void ajFileUnbuffer (
      AjPFile thys
);

Type Name Read/Write Description

AjPFile thys Modify File object.

void RETURN

Input & Output

thys:

(Modify)

File object.

Returns

void:

No return value

Description

Turns off system buffering of an output file, for example to allow debug output to appear even in the event of a program abort.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileReadAppend

Reads a record from a file and appends it to the user supplied buffer.

Synopsis

Prototype

AjBool ajFileReadAppend (
      AjPFile thys,
      AjPStr* pbuff
);

Type Name Read/Write Description

AjPFile thys Modify Input file.

AjPStr* pbuff Output Buffer to hold results.

AjBool RETURN ajTrue on success.

Output

pbuff:

(Output)

Buffer to hold results.

Input & Output

thys:

(Modify)

Input file.

Returns

AjBool:

ajTrue on success.

Description

Reads a record from a file and appends it to the user supplied buffer.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileOutHeader

Writes a header record to the output file.

Synopsis

Prototype

void ajFileOutHeader (
      AjPFile thys
);

Type Name Read/Write Description

AjPFile thys Modify Output file.

void RETURN

Input & Output

thys:

(Modify)

Output file.

Returns

void:

No return value

Description

Writes a header record to the output file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNameShorten

Truncates a filename to a basic file name.

Synopsis

Prototype

AjBool ajFileNameShorten (
      AjPStr* fname
);

Type Name Read/Write Description

AjPStr* fname Modify File name

AjBool RETURN ajTrue on success, and returns a filename. ajFalse on failure, and returns an empty string.

Input & Output

fname:

(Modify)

File name

Returns

AjBool:

ajTrue on success, and returns a filename. ajFalse on failure, and returns an empty string.

Description

Truncates a filename to a basic file name.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNameTrim

Truncates a filename to a basic file name.extension

Synopsis

Prototype

AjBool ajFileNameTrim (
      AjPStr* fname
);

Type Name Read/Write Description

AjPStr* fname Modify File name

AjBool RETURN ajTrue on success, and returns a filename. ajFalse on failure, and returns an empty string.

Input & Output

fname:

(Modify)

File name

Returns

AjBool:

ajTrue on success, and returns a filename. ajFalse on failure, and returns an empty string.

Description

Truncates a filename to a basic file name.extension

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileDataNewWrite

Returns an allocated AjFileNewOut pointer (AjPFile) to a file in the emboss_DATA area

Synopsis

Prototype

void ajFileDataNewWrite (
      const AjPStr tfile,
      AjPFile* fnew
);

Type Name Read/Write Description

const AjPStr tfile Input Filename in AjStr.

AjPFile* fnew Output file pointer.

void RETURN

Input

tfile:

(Input)

Filename in AjStr.

Output

fnew:

(Output)

file pointer.

Returns

void:

No return value

Description

Returns an allocated AjFileNewOut pointer (AjPFile) to a file in the emboss_DATA area

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: File Operators

These functions use the contents of a file object but do not make any changes.

Functions: ajFileDir ajFileDirPath ajFileGetwd ajFileDirUp ajFileDirFix ajFileExit ajFilePathData ajFileTrace

Function ajFileDir

Checks that a string is a valid existing directory, and appends a trailing '/' if it is missing.

Synopsis

Prototype

AjBool ajFileDir (
      AjPStr* dir
);

Type Name Read/Write Description

AjPStr* dir Modify Directory path

AjBool RETURN true if a valid directory.

Input & Output

dir:

(Modify)

Directory path

Returns

AjBool:

true if a valid directory.

Description

Checks that a string is a valid existing directory, and appends a trailing '/' if it is missing.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileDirPath

Checks that a string is a valid directory, and makes sure it has the full path definition.

Synopsis

Prototype

AjBool ajFileDirPath (
      AjPStr* dir
);

Type Name Read/Write Description

AjPStr* dir Modify Directory path

AjBool RETURN true if a valid directory.

Input & Output

dir:

(Modify)

Directory path

Returns

AjBool:

true if a valid directory.

Description

Checks that a string is a valid directory, and makes sure it has the full path definition.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileGetwd

Returns the current directory

Synopsis

Prototype

AjBool ajFileGetwd (
      AjPStr* dir
);

Type Name Read/Write Description

AjPStr* dir Output Directory name.

AjBool RETURN ajTrue on success.

Output

dir:

(Output)

Directory name.

Returns

AjBool:

ajTrue on success.

Description

Returns the current directory

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileDirUp

Changes directory name to one level up

Synopsis

Prototype

AjBool ajFileDirUp (
      AjPStr* dir
);

Type Name Read/Write Description

AjPStr* dir Modify Directory name.

AjBool RETURN ajTrue on success.

Input & Output

dir:

(Modify)

Directory name.

Returns

AjBool:

ajTrue on success.

Description

Changes directory name to one level up

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileDirFix

If the directory name has no trailing slash (on Unix) then one is added. This is why the directory name must be writeable.

Synopsis

Prototype

void ajFileDirFix (
      AjPStr* dir
);

Type Name Read/Write Description

AjPStr* dir Modify Directory name.

void RETURN

Input & Output

dir:

(Modify)

Directory name.

Returns

void:

No return value

Description

If the directory name has no trailing slash (on Unix) then one is added. This is why the directory name must be writeable.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileExit

Prints a summary of file usage with debug calls

Synopsis

Prototype

void ajFileExit (
      void
);

Type Name Read/Write Description

void RETURN

Returns

void:

No return value

Description

Prints a summary of file usage with debug calls

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFilePathData

Get the path to the active data directory

Synopsis

Prototype

AjBool ajFilePathData (
      AjPStr* Ppath
);

Type Name Read/Write Description

AjPStr* Ppath Modify path.

AjBool RETURN True if the data directory is found

Input & Output

Ppath:

(Modify)

path.

Returns

AjBool:

True if the data directory is found

Description

Get the path to the active data directory

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileTrace

Writes debug messages to trace the contents of a file object.

Synopsis

Prototype

void ajFileTrace (
      const AjPFile thys
);

Type Name Read/Write Description

const AjPFile thys Input File.

void RETURN

Input

thys:

(Input)

File.

Returns

void:

No return value

Description

Writes debug messages to trace the contents of a file object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: Outfile Casts

These functions examine the contents of an outfile object and return some derived information. Some of them provide access to the internal components of a file object. They are provided for programming convenience but should be used with caution.

Functions: ajOutfileFile ajOutfileFp ajOutfileFormat

Function ajOutfileFile

Returns the AjPFile for an AjPOutfile object

Synopsis

Prototype

AjPFile ajOutfileFile (
      const AjPOutfile thys
);

Type Name Read/Write Description

const AjPOutfile thys Input Outfile object

AjPFile RETURN AjPFile object

Input

thys:

(Input)

Outfile object

Returns

AjPFile:

AjPFile object

Description

Returns the AjPFile for an AjPOutfile object

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajOutfileFp

Returns the C FILE* for an AjPOutfile object

Synopsis

Prototype

FILE* ajOutfileFp (
      const AjPOutfile thys
);

Type Name Read/Write Description

const AjPOutfile thys Input Outfile object

FILE* RETURN C file pointer

Input

thys:

(Input)

Outfile object

Returns

FILE*:

C file pointer

Description

Returns the C FILE* for an AjPOutfile object

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajOutfileFormat

Returns the C FILE* for an AjPOutfile object

Synopsis

Prototype

AjPStr ajOutfileFormat (
      const AjPOutfile thys
);

Type Name Read/Write Description

const AjPOutfile thys Input Outfile object

AjPStr RETURN Format name

Input

thys:

(Input)

Outfile object

Returns

AjPStr:

Format name

Description

Returns the C FILE* for an AjPOutfile object

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: File Casts

These functions examine the contents of a file object and return some derived information. Some of them provide access to the internal components of a file object. They are provided for programming convenience but should be used with caution.

Functions: ajFileBuffSize ajFileName ajFileNameS ajFileGetApp ajFileGetName ajFileStat ajFileNameValid ajFileLength ajFileTell MAJFILETELL ajFileStdout ajFileStderr ajFileStdin ajFileRedirectStderr ajFileRedirectStdin ajFileRedirectStdout ajFileFp ajFileEof

Function ajFileBuffSize

Returns the standard record buffer size for a file

Synopsis

Prototype

ajint ajFileBuffSize (
      void
);

Type Name Read/Write Description

ajint RETURN File record buffer size

Returns

ajint:

File record buffer size

Description

Returns the standard record buffer size for a file

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileName

Returns the file name for a file object. The filename returned is a pointer to the real string internally, so the user must take care not to change it and cannot trust the value if the file object is deleted.

Synopsis

Prototype

const char* ajFileName (
      const AjPFile thys
);

Type Name Read/Write Description

const AjPFile thys Input File.

const char* RETURN Filename as a C character string.

Input

thys:

(Input)

File.

Returns

const char*:

Filename as a C character string.

Description

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNameS

Synopsis

Prototype

const AjPStr ajFileNameS (
      const AjPFile thys
);

Type Name Read/Write Description

const AjPFile thys Input File.

const AjPStr RETURN Filename.

Input

thys:

(Input)

File.

Returns

const AjPStr:

Filename.

Description

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileGetApp

Returns the App element for a file object. The App element is True if the file was opened for appending to, False otherwise.

Synopsis

Prototype

AjBool ajFileGetApp (
      const AjPFile thys
);

Type Name Read/Write Description

const AjPFile thys Input File.

AjBool RETURN App element, True if if file was opened for appending to, False otherwise.

Input

thys:

(Input)

File.

Returns

AjBool:

App element, True if if file was opened for appending to, False otherwise.

Description

Returns the App element for a file object. The App element is True if the file was opened for appending to, False otherwise.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileGetName

Synopsis

Prototype

AjPStr ajFileGetName (
      const AjPFile thys
);

Type Name Read/Write Description

const AjPFile thys Input File.

AjPStr RETURN Filename as a C character string.

Input

thys:

(Input)

File.

Returns

AjPStr:

Filename as a C character string.

Description

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileStat

Returns true if file exists and is read or write or executable by the user as determined by AJ_FILE_R AJ_FILE_W AJ_FILE_X file modes

Synopsis

Prototype

AjBool ajFileStat (
      const AjPStr fname,
      ajint mode
);

Type Name Read/Write Description

const AjPStr fname Input Filename.

ajint mode Input file mode.

AjBool RETURN ajTrue on success

Input

fname:	(Input)	Filename.
mode:	(Input)	file mode.

Returns

AjBool:

ajTrue on success

Description

Returns true if file exists and is read or write or executable by the user as determined by AJ_FILE_R AJ_FILE_W AJ_FILE_X file modes

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNameValid

Returns true if file exists and is readable by the user

Synopsis

Prototype

AjBool ajFileNameValid (
      const AjPStr fname
);

Type Name Read/Write Description

const AjPStr fname Input Filename.

AjBool RETURN ajTrue on success

Input

fname:

(Input)

Filename.

Returns

AjBool:

ajTrue on success

Description

Returns true if file exists and is readable by the user

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileLength

Returns the length of a file

Synopsis

Prototype

ajlong ajFileLength (
      const AjPStr fname
);

Type Name Read/Write Description

const AjPStr fname Input Filename.

ajlong RETURN length or -1 if file doesn't exist

Input

fname:

(Input)

Filename.

Returns

ajlong:

length or -1 if file doesn't exist

Description

Returns the length of a file

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileTell

Returns the current position in an open file.

Synopsis

Prototype

ajlong ajFileTell (
      const AjPFile thys
);

Type Name Read/Write Description

const AjPFile thys Input File.

ajlong RETURN Result of 'ftell'

Input

thys:

(Input)

File.

Returns

ajlong:

Result of 'ftell'

Description

Returns the current position in an open file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Macro MAJFILETELL

Returns the current position in an open file object

A macro version of {ajFileTell} available in case it is needed for speed.

Input

thys:

(Input)

Source file

Returns

ajlong:

Current file position

Description

Returns the current position in an open file object

A macro version of {ajFileTell} available in case it is needed for speed.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileStdout

Tests whether a file object is really stdout.

Synopsis

Prototype

AjBool ajFileStdout (
      const AjPFile file
);

Type Name Read/Write Description

const AjPFile file Input File object.

AjBool RETURN ajTrue if the file matches stdout.

Input

file:

(Input)

File object.

Returns

AjBool:

ajTrue if the file matches stdout.

Description

Tests whether a file object is really stdout.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileStderr

Tests whether a file object is really stderr.

Synopsis

Prototype

AjBool ajFileStderr (
      const AjPFile file
);

Type Name Read/Write Description

const AjPFile file Input File object.

AjBool RETURN ajTrue if the file matches stderr.

Input

file:

(Input)

File object.

Returns

AjBool:

ajTrue if the file matches stderr.

Description

Tests whether a file object is really stderr.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileStdin

Tests whether a file object is really stdin.

Synopsis

Prototype

AjBool ajFileStdin (
      const AjPFile file
);

Type Name Read/Write Description

const AjPFile file Input File object.

AjBool RETURN ajTrue if the file matches stdin.

Input

file:

(Input)

File object.

Returns

AjBool:

ajTrue if the file matches stdin.

Description

Tests whether a file object is really stdin.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileRedirectStderr

Tests whether stderr is in use by an internal file

Synopsis

Prototype

AjBool ajFileRedirectStderr (
      void
);

Type Name Read/Write Description

AjBool RETURN ajTrue if the file matches stderr.

Returns

AjBool:

ajTrue if the file matches stderr.

Description

Tests whether stderr is in use by an internal file

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileRedirectStdin

Tests whether stdin is in use by an internal file

Synopsis

Prototype

AjBool ajFileRedirectStdin (
      void
);

Type Name Read/Write Description

AjBool RETURN ajTrue if the file matches stdin.

Returns

AjBool:

ajTrue if the file matches stdin.

Description

Tests whether stdin is in use by an internal file

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileRedirectStdout

Tests whether stdout is in use by an internal file

Synopsis

Prototype

AjBool ajFileRedirectStdout (
      void
);

Type Name Read/Write Description

AjBool RETURN ajTrue if the file matches stdout.

Returns

AjBool:

ajTrue if the file matches stdout.

Description

Tests whether stdout is in use by an internal file

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileFp

Returns the C file pointer for an open file.

Synopsis

Prototype

FILE* ajFileFp (
      const AjPFile thys
);

Type Name Read/Write Description

const AjPFile thys Input File.

FILE* RETURN C file pointer for the file.

Input

thys:

(Input)

File.

Returns

FILE*:

C file pointer for the file.

Description

Returns the C file pointer for an open file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileEof

Tests whether we have reached end of file already

Synopsis

Prototype

AjBool ajFileEof (
      const AjPFile thys
);

Type Name Read/Write Description

const AjPFile thys Input File

AjBool RETURN ajTrue if we already set end-of-file

Input

thys:

(Input)

File

Returns

AjBool:

ajTrue if we already set end-of-file

Description

Tests whether we have reached end of file already

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: Buffered File Constructors

To replace or reuse an existing file, see instead the File Assignments and File Modifiers functions.

The range of constructors is provided to allow flexibility in how applications can open files to read various kinds of data.

Functions: ajFileBuffNewIn ajFileBuffNew ajFileBuffNewFile ajFileBuffSetFile ajFileBuffNewS ajFileBuffNewF ajFileBuffNewDW ajFileBuffNewDWE ajFileBuffNewDC ajFileBuffNewDF ajFileNewDW ajFileNewDWE ajFileNewDF ajFileNewDirF ajFileNewDC ajFileBuffNewInList

Function ajFileBuffNewIn

Creates a new buffered input file object with an opened named file.

Synopsis

Prototype

AjPFileBuff ajFileBuffNewIn (
      const AjPStr name
);

Type Name Read/Write Description

const AjPStr name Input File name.

AjPFileBuff RETURN New buffered file object.

Input

name:

(Input)

File name.

Returns

AjPFileBuff:

New buffered file object.

Description

Creates a new buffered input file object with an opened named file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileBuffNew

Creates a new buffered input file object with an undefined file.

Synopsis

Prototype

AjPFileBuff ajFileBuffNew (
      void
);

Type Name Read/Write Description

AjPFileBuff RETURN New buffered file object.

Returns

AjPFileBuff:

New buffered file object.

Description

Creates a new buffered input file object with an undefined file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileBuffNewFile

Creates a new buffered input file object from an open file.

Synopsis

Prototype

AjPFileBuff ajFileBuffNewFile (
      AjPFile file
);

Type Name Read/Write Description

AjPFile file Modify File object to be buffered.

AjPFileBuff RETURN New buffered file object.

Input & Output

file:

(Modify)

File object to be buffered.

Returns

AjPFileBuff:

New buffered file object.

Description

Creates a new buffered input file object from an open file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileBuffSetFile

Creates a new buffered input file object from an open file.

The AjPFile pointer is a clone, so we should simply overwrite whatever was there before, but we do need to clear the buffer

Synopsis

Prototype

AjBool ajFileBuffSetFile (
      AjPFileBuff* pthys,
      AjPFile file,
      AjBool samefile
);

Type Name Read/Write Description

AjPFileBuff* pthys Output Buffered file object.

AjPFile file Modify File object to be buffered.

AjBool samefile Input true if the buff currently uses this file

AjBool RETURN ajTrue on success

Input

samefile:

(Input)

true if the buff currently uses this file

Output

pthys:

(Output)

Buffered file object.

Input & Output

file:

(Modify)

File object to be buffered.

Returns

AjBool:

ajTrue on success

Description

Creates a new buffered input file object from an open file.

The AjPFile pointer is a clone, so we should simply overwrite whatever was there before, but we do need to clear the buffer

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileBuffNewS

Creates a new buffered input file object with no file but with one line of buffered data provided.

Synopsis

Prototype

AjPFileBuff ajFileBuffNewS (
      const AjPStr data
);

Type Name Read/Write Description

const AjPStr data Input One line of buffered data.

AjPFileBuff RETURN New buffered file object.

Input

data:

(Input)

One line of buffered data.

Returns

AjPFileBuff:

New buffered file object.

Description

Creates a new buffered input file object with no file but with one line of buffered data provided.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileBuffNewF

Creates a new buffered input file from an already open C file.

Synopsis

Prototype

AjPFileBuff ajFileBuffNewF (
      FILE* fp
);

Type Name Read/Write Description

FILE* fp Modify Open C file.

AjPFileBuff RETURN New buffered file object.

Input & Output

fp:

(Modify)

Open C file.

Returns

AjPFileBuff:

New buffered file object.

Description

Creates a new buffered input file from an already open C file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileBuffNewDW

Opens directory "dir" Looks for file(s) matching "file" Opens them as a list of files using a buffered file object.

Synopsis

Prototype

AjPFileBuff ajFileBuffNewDW (
      const AjPStr dir,
      const AjPStr wildfile
);

Type Name Read/Write Description

const AjPStr dir Input Directory

const AjPStr wildfile Input Wildcard filename.

AjPFileBuff RETURN New buffered file object.

Input

dir:	(Input)	Directory
wildfile:	(Input)	Wildcard filename.

Returns

AjPFileBuff:

New buffered file object.

Description

Opens directory "dir" Looks for file(s) matching "file" Opens them as a list of files using a buffered file object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileBuffNewDWE

Opens directory "dir" Looks for file(s) matching "file" Skip files natching excluded files wildcard Opens them as a list of files using a buffered file object.

Synopsis

Prototype

AjPFileBuff ajFileBuffNewDWE (
      const AjPStr dir,
      const AjPStr wildfile,
      const AjPStr exclude
);

Type Name Read/Write Description

const AjPStr dir Input Directory

const AjPStr wildfile Input Wildcard filename.

const AjPStr exclude Input Wildcard excluded filename.

AjPFileBuff RETURN New buffered file object.

Input

dir:	(Input)	Directory
wildfile:	(Input)	Wildcard filename.
exclude:	(Input)	Wildcard excluded filename.

Returns

AjPFileBuff:

New buffered file object.

Description

Opens directory "dir" Looks for file(s) matching "file" Skip files natching excluded files wildcard Opens them as a list of files using a buffered file object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileBuffNewDC

Opens directory "dir" Looks for file "file" Opens the file.

Synopsis

Prototype

AjPFileBuff ajFileBuffNewDC (
      const AjPStr dir,
      const char* filename
);

Type Name Read/Write Description

const AjPStr dir Input Directory. If empty uses current directory.

const char* filename Input Filename.

AjPFileBuff RETURN New buffered file object.

Input

dir:	(Input)	Directory. If empty uses current directory.
filename:	(Input)	Filename.

Returns

AjPFileBuff:

New buffered file object.

Description

Opens directory "dir" Looks for file "file" Opens the file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileBuffNewDF

Opens directory "dir" Looks for file "file" Opens the file.

Synopsis

Prototype

AjPFileBuff ajFileBuffNewDF (
      const AjPStr dir,
      const AjPStr filename
);

Type Name Read/Write Description

const AjPStr dir Input Directory. If empty uses current directory.

const AjPStr filename Input Filename.

AjPFileBuff RETURN New buffered file object.

Input

dir:	(Input)	Directory. If empty uses current directory.
filename:	(Input)	Filename.

Returns

AjPFileBuff:

New buffered file object.

Description

Opens directory "dir" Looks for file "file" Opens the file.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewDW

Opens directory "dir" Looks for file(s) matching "file" Opens them as a list of files using a simple file object.

Synopsis

Prototype

AjPFile ajFileNewDW (
      const AjPStr dir,
      const AjPStr wildfile
);

Type Name Read/Write Description

const AjPStr dir Input Directory

const AjPStr wildfile Input Wildcard filename.

AjPFile RETURN New file object.

Input

dir:	(Input)	Directory
wildfile:	(Input)	Wildcard filename.

Returns

AjPFile:

New file object.

Description

Opens directory "dir" Looks for file(s) matching "file" Opens them as a list of files using a simple file object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewDWE

Opens directory "dir" Looks for file(s) matching "file" Skip files natching excluded files wildcard Opens them as a list of files using a simple file object.

Synopsis

Prototype

AjPFile ajFileNewDWE (
      const AjPStr dir,
      const AjPStr wildfile,
      const AjPStr exclude
);

Input

dir:	(Input)	Directory
wildfile:	(Input)	Wildcard filename.
exclude:	(Input)	Wildcard excluded filename.

Returns

AjPFile:

New file object.

Description

Opens directory "dir" Looks for file(s) matching "file" Skip files natching excluded files wildcard Opens them as a list of files using a simple file object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewDF

Opens directory "dir" Looks for file "file"

Synopsis

Prototype

AjPFile ajFileNewDF (
      const AjPStr dir,
      const AjPStr filename
);

Type Name Read/Write Description

const AjPStr dir Input Directory

const AjPStr filename Input Wildcard Filename.

AjPFile RETURN New file object.

Input

dir:	(Input)	Directory
filename:	(Input)	Wildcard Filename.

Returns

AjPFile:

New file object.

Description

Opens directory "dir" Looks for file "file"

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewDirF

Opens directory "dir" Looks for file "file" with the extension (if any) specified for the directory

Synopsis

Prototype

AjPFile ajFileNewDirF (
      const AjPDir dir,
      const AjPStr filename
);

Type Name Read/Write Description

const AjPDir dir Input Directory

const AjPStr filename Input Wildcard Filename.

AjPFile RETURN New file object.

Input

dir:	(Input)	Directory
filename:	(Input)	Wildcard Filename.

Returns

AjPFile:

New file object.

Description

Opens directory "dir" Looks for file "file" with the extension (if any) specified for the directory

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileNewDC

Opens directory "dir" Looks for file "file"

Synopsis

Prototype

AjPFile ajFileNewDC (
      const AjPStr dir,
      const char* filename
);

Type Name Read/Write Description

const AjPStr dir Input Directory

const char* filename Input Filename.

AjPFile RETURN New file object.

Input

dir:	(Input)	Directory
filename:	(Input)	Filename.

Returns

AjPFile:

New file object.

Description

Opens directory "dir" Looks for file "file"

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileBuffNewInList

Creates a new buffered file object from a list of filenames.

Synopsis

Prototype

AjPFileBuff ajFileBuffNewInList (
      AjPList list
);

Type Name Read/Write Description

AjPList list Modify List of filenames as strings.

AjPFileBuff RETURN New buffered file object.

Input & Output

list:

(Modify)

List of filenames as strings.

Returns

AjPFileBuff:

New buffered file object.

Description

Creates a new buffered file object from a list of filenames.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: Buffered File Destructors

Destruction is achieved by closing the file.

Unlike ANSI C, there are tests to ensure a file is not closed twice.

Functions: ajFileBuffDel

Function ajFileBuffDel

Destructor for a buffered file object.

Synopsis

Prototype

void ajFileBuffDel (
      AjPFileBuff* pthis
);

Type Name Read/Write Description

AjPFileBuff* pthis Delete Buffered file object.

void RETURN

Output

pthis:

(Delete)

Buffered file object.

Returns

void:

No return value

Description

Destructor for a buffered file object.

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Section: BufferedFile Modifiers

These functions use the contents of a file object and update them.

Functions: ajFileBuffGet ajFileBuffGetTrim ajFileBuffGetStore ajFileBuffGetStoreL ajFileBuffGetL ajFileBuffStripHtml ajFileBuffLoadC ajFileBuffLoadS ajFileBuffEof ajFileBuffEnd ajFileBuffReset ajFileBuffResetStore ajFileBuffResetPos ajFileBuffFix ajFileBuffFreeClear ajFileBuffClear ajFileBuffClearStore ajFileBuffNobuff ajFileBuffBuff

Function ajFileBuffGet

Reads a line from a buffered file. If the buffer has data, reads from the buffer. If the buffer is exhausted, reads from the file. If the file is exhausted, sets end of file and returns. If end of file was already set, looks for another file to open.

Synopsis

Prototype

AjBool ajFileBuffGet (
      AjPFileBuff thys,
      AjPStr* pdest
);

Type Name Read/Write Description

AjPFileBuff thys Modify Buffered input file.

AjPStr* pdest Output Buffer to hold results.

AjBool RETURN ajTrue if data was read.

Output

pdest:

(Output)

Buffer to hold results.

Input & Output

thys:

(Modify)

Buffered input file.

Returns

AjBool:

ajTrue if data was read.

Description

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileBuffGetTrim

Synopsis

Prototype

AjBool ajFileBuffGetTrim (
      AjPFileBuff thys,
      AjPStr* pdest
);

Type Name Read/Write Description

AjPFileBuff thys Modify Buffered input file.

AjPStr* pdest Output Buffer to hold results.

AjBool RETURN ajTrue if data was read.

Output

pdest:

(Output)

Buffer to hold results.

Input & Output

thys:

(Modify)

Buffered input file.

Returns

AjBool:

ajTrue if data was read.

Description

Usage

See source code

Example

In preparation

Errors

See source code

Dependencies

See source code

Availability

In release 5.0.0

Function ajFileBuffGetStore

Reads a line from a buffered file. Also appends the line to a given string if the append flag is true. A double NULL character is added afterwards. If the buffer has data, reads from the buffer. If the buffer is exhausted, reads from the file. If the file is exhausted, sets end of file and returns. If end of file was already set, looks for another file to open.

Synopsis

Prototype

AjBool ajFileBuffGetStore (
      AjPFileBuff thys,
      AjPStr* pdest,
      AjBool store,
      AjPStr* astr
);

Type Name Read/Write Description

AjPFileBuff thys Modify Buffered input file.

AjPStr* pdest Output Buffer to hold results.

AjBool store Input append if true

AjPStr* astr Output string to append to

AjBool RETURN ajTrue if data was read.

Input

store:

(Input)

append if true

Output

pdest:	(Output)	Buffer to hold results.
astr:	(Output)	string to append to

Input & Output

thys:

(Modify)

Buffered input file.

Returns

AjBool:

ajTrue if data was read.

Description

Reads a line from a buffered file. Also appends the line to a given string if the append flag is true. A double NULL character is added afterwards. If the buffer has data,

Type	Name	Read/Write	Description
AjPStr*	pname	Modify	File name, returned with directory prefix
const AjPStr	dir	Input	Directory (optional, can be empty or NULL).
AjBool		RETURN	ajTrue if the filename was changed

Type	Name	Read/Write	Description
const AjPStr	tfile	Input	Filename in AjStr.
AjPFile*	fnew	Output	file pointer.
void		RETURN

Type	Name	Read/Write	Description
void*	ptr	Output	Buffer for output.
size_t	element_size	Input	Number of bytes per element.
size_t	count	Input	Number of elements to read.
AjPFile	thys	Modify	Input file.
size_t		RETURN	Return value from 'fread'

Type	Name	Read/Write	Description
AjPStr*	fname	Modify	File name
AjBool		RETURN	ajTrue on success, and returns a filename. ajFalse on failure, and returns an empty string.

Type	Name	Read/Write	Description
AjPStr*	Ppath	Modify	path.
AjBool		RETURN	True if the data directory is found

Type	Name	Read/Write	Description
const AjPOutfile	thys	Input	Outfile object
AjPFile		RETURN	AjPFile object

Type	Name	Read/Write	Description
const AjPFile	thys	Input	File.
const char*		RETURN	Filename as a C character string.

Type	Name	Read/Write	Description
AjPFileBuff*	pthys	Output	Buffered file object.
AjPFile	file	Modify	File object to be buffered.
AjBool	samefile	Input	true if the buff currently uses this file
AjBool		RETURN	ajTrue on success

Type	Name	Read/Write	Description
const AjPStr	data	Input	One line of buffered data.
AjPFileBuff		RETURN	New buffered file object.

Type	Name	Read/Write	Description
FILE*	fp	Modify	Open C file.
AjPFileBuff		RETURN	New buffered file object.

ajfile.c

Synopsis

Prototype

Input

Returns

Description

Usage

Example

Errors

Dependencies

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

Usage

Example

Errors

Dependencies

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

Usage

Example

Errors

Dependencies

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

Usage

Example

Errors

Dependencies

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

Usage

Example

Errors

Dependencies

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

Usage

Example

Errors

Dependencies

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

Usage

Example

Errors

Dependencies

See Also

Availability

Synopsis

Prototype